Why veslx?

veslx is a zero-config CLI that transforms your markdown files into a polished documentation site. Write in MDX, import React components, render LaTeX equations, display image galleries, and create slide and pdf presentations—all from simple markdown files.

Built on Vite + React + Tailwind. Fast builds. Instant hot reload. Beautiful defaults.

bun install -g veslx
veslx serve

That's it. Your docs are live at localhost:3000.

Quick Start

Install

# Using bun (recommended)
bun install -g veslx

# Or npm
npm install -g veslx

Create Your First Post

mkdir -p docs/hello-world
cat > docs/hello-world/README.mdx << 'EOF'
---
title: Hello World
date: 2025-01-15
description: My first veslx post
---

# Hello World

Welcome to **veslx**! This is MDX, so you can use React components:

$$
E = mc^2
$$

EOF

Run

cd docs
veslx serve

Open localhost:3000. Done.

Features

| Feature | Description | |---------|-------------| | MDX | Write markdown with embedded React components | | LaTeX | Beautiful math rendering via KaTeX | | Syntax Highlighting | Code blocks with Shiki (150+ languages) | | Image Galleries | Built-in <Gallery> component with lightbox | | Slides | Create presentations from markdown | | Local Imports | Import .tsx components from your content directory | | Parameter Tables | Display YAML/JSON configs with collapsible sections | | Dark Mode | Automatic theme switching | | Hot Reload | Instant updates during development | | Print to PDF | Export slides as landscape PDFs |

Content Structure

veslx scans your directory for README.mdx (posts) and SLIDES.mdx (presentations):

content/
├── my-post/
│   ├── README.mdx          # → /my-post
│   ├── Chart.tsx           # Local component (importable)
│   └── images/
│       └── figure1.png
├── my-slides/
│   └── SLIDES.mdx          # → /my-slides/slides
└── another-post/
    └── README.mdx

Frontmatter

---
title: My Post Title
date: 2025-01-15
description: A brief description
visibility: public          # or "hidden" to hide from listings
---

Components

Gallery

Display images with titles, captions, and a fullscreen lightbox:

<Gallery
  path="my-post/images"
  globs={["*.png", "*.jpg"]}
  title="Experiment Results"
  subtitle="Phase 1 measurements"
  caption="Data collected over 30 days"
  captionLabel="Figure 1"
/>

| Prop | Type | Description | |------|------|-------------| | path | string | Path to images directory | | globs | string[] | Glob patterns to match files | | title | string | Gallery title | | subtitle | string | Subtitle below title | | caption | string | Caption below images | | captionLabel | string | Label prefix (e.g., "Figure 1") | | limit | number | Max images to show |

ParameterTable

Display YAML or JSON configuration files with collapsible sections:

<ParameterTable
  path="config.yaml"
  keys={[".simulation.timestep", ".model.layers"]}
/>

| Prop | Type | Description | |------|------|-------------| | path | string | Path to YAML/JSON file | | keys | string[] | jq-like paths to filter (optional) |

Local Imports

Import React components directly from your content directory:

import Chart from './Chart.tsx'
import { DataTable } from './components/DataTable.tsx'

# My Analysis

<Chart data={[25, 50, 75, 40, 90]} />
<DataTable source="results.json" />

Components are compiled at build time by Vite—no runtime overhead.

Slides

Create presentations in SLIDES.mdx files. Separate slides with ---:

---
title: My Presentation
date: 2025-01-15
---

<FrontMatter />

---

# Introduction

First slide content

---

# Methods

Second slide with an image gallery:

<Gallery path="images" globs={["chart*.png"]} />

---

# Conclusion

Final thoughts

Navigation

| Key | Action | |-----|--------| | ↓ → j | Next slide | | ↑ ← k | Previous slide | | Scroll | Natural trackpad scrolling |

Print to PDF

1. Open slides in browser
2. Press Cmd+P (or Ctrl+P)
3. Select "Save as PDF"
4. Choose Landscape orientation

Each slide becomes one PDF page, centered and optimized for print.

CLI Commands

veslx init      # Create veslx.config.ts
veslx serve     # Start dev server with hot reload
veslx build     # Build for production → dist/
veslx start     # Run as background daemon (PM2)
veslx stop      # Stop the daemon

Configuration

Create veslx.config.ts in your content root:

export default {
  dir: './content',  // Content directory (default: current dir)
}

Or run veslx init to generate it.

Styling

veslx uses a clean, technical aesthetic out of the box:

• Typography: Inter + JetBrains Mono
• Colors: Neutral palette with cyan accents
• Dark mode: Automatic system detection + manual toggle

Built on Tailwind CSS and shadcn/ui components.

Development

# Clone the repo
git clone https://github.com/eoinmurray/veslx.git
cd veslx

# Install dependencies
bun install

# Run in dev mode (with hot reload on src/)
bun run dev

# Build for production
bun run build

Project Structure

veslx/
├── bin/              # CLI entry point
├── plugin/           # Vite plugins (MDX, content scanning)
├── src/
│   ├── components/   # React components (Gallery, Slides, etc.)
│   ├── hooks/        # React hooks
│   ├── pages/        # Route pages
│   └── lib/          # Utilities
└── test-content/     # Example content for testing

Tech Stack

• Runtime: Bun
• Build: Vite
• Framework: React 19
• Styling: Tailwind CSS 4
• Components: shadcn/ui + Radix
• MDX: @mdx-js/rollup
• Math: KaTeX
• Syntax: Shiki
• Daemon: PM2

License

MIT