veslx 0.1.14 → 0.1.16

package/README.md

@@ -1,130 +1,337 @@
-# veslx
+<p align="center">
+  <pre align="center">
+▗▖  ▗▖▗▄▄▄▖ ▗▄▄▖▗▖   ▗▖  ▗▖
+▐▌  ▐▌▐▌   ▐▌   ▐▌    ▝▚▞▘
+▐▌  ▐▌▐▛▀▀▘ ▝▀▚▖▐▌     ▐▌
+ ▝▚▞▘ ▐▙▄▄▖▗▄▄▞▘▐▙▄▄▖▗▞▘▝▚▖
+  </pre>
+</p>
+
+<p align="center">
+  <strong>Turn markdown directories into beautiful documentation sites and presentations</strong>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#features">Features</a> •
+  <a href="#components">Components</a> •
+  <a href="#slides">Slides</a> •
+  <a href="#configuration">Config</a>
+</p>
 
-A CLI tool for turning markdown directories into beautiful documentation sites and slide presentations.
+---
+
+## Why veslx?
 
-## Installation
+**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.
 
 ```bash
 bun install -g veslx
+veslx serve
 ```
 
+That's it. Your docs are live at `localhost:3000`.
+
+---
+
 ## Quick Start
 
+### Install
+
 ```bash
-# Initialize in your content directory
-veslx init
+# Using bun (recommended)
+bun install -g veslx
 
-# Start development server
-veslx serve
+# Or npm
+npm install -g veslx
+```
 
-# Build for production
-veslx build
+### Create Your First Post
+
+```bash
+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
+
+```bash
+cd docs
+veslx serve
 ```
 
-## Commands
+Open [localhost:3000](http://localhost:3000). Done.
+
+---
 
-| Command | Description |
+## Features
+
+| Feature | Description |
 |---------|-------------|
-| `veslx init` | Create a `veslx.config.ts` configuration file |
-| `veslx serve` | Start development server with hot reload |
-| `veslx build` | Build for production to `dist/` |
-| `veslx start` | Run as a background daemon (PM2) |
-| `veslx stop` | Stop the daemon |
+| **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 content directory for markdown files and renders them as posts or slides:
+veslx scans your directory for `README.mdx` (posts) and `SLIDES.mdx` (presentations):
 
 ```
 content/
 ├── my-post/
-│   ├── README.mdx      # Rendered as a blog post
-│   └── SLIDES.mdx      # Rendered as a presentation
-├── another-post/
-│   └── README.mdx
-└── ...
+│   ├── README.mdx          # → /my-post
+│   ├── Chart.tsx           # Local component (importable)
+│   └── images/
+│       └── figure1.png
+├── my-slides/
+│   └── SLIDES.mdx          # → /my-slides/slides
+└── another-post/
+    └── README.mdx
 ```
 
 ### Frontmatter
 
-Add YAML frontmatter to control metadata:
-
-```mdx
+```yaml
 ---
 title: My Post Title
 date: 2025-01-15
-description: A brief description of the post
-visibility: public
+description: A brief description
+visibility: public          # or "hidden" to hide from listings
+---
+```
+
 ---
 
-Your content here...
+## Components
+
+### Gallery
+
+Display images with titles, captions, and a fullscreen lightbox:
+
+```mdx
+<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:
+
+```mdx
+<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:
+
+```mdx
+import Chart from './Chart.tsx'
+import { DataTable } from './components/DataTable.tsx'
+
+# My Analysis
+
+<Chart data={[25, 50, 75, 40, 90]} />
+<DataTable source="results.json" />
 ```
 
-| Field | Description |
-|-------|-------------|
-| `title` | Display title (falls back to directory name) |
-| `date` | Publication date |
-| `description` | Short description shown in listings |
-| `visibility` | Set to `hidden` to hide from listings |
+Components are compiled at build time by Vite—no runtime overhead.
+
+---
 
-### Slides
+## Slides
 
 Create presentations in `SLIDES.mdx` files. Separate slides with `---`:
 
 ```mdx
 ---
 title: My Presentation
+date: 2025-01-15
+---
+
+<FrontMatter />
+
 ---
 
-# Slide 1
+# 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
 
-Content for the first slide
+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.
 
 ---
 
-# Slide 2
+## CLI Commands
 
-Content for the second slide
+```bash
+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
 ```
 
-Navigate slides with arrow keys or `j`/`k`.
+---
 
 ## Configuration
 
-The `veslx.config.ts` file specifies your content directory:
+Create `veslx.config.ts` in your content root:
 
 ```typescript
 export default {
-  dir: './content',
+  dir: './content',  // Content directory (default: current dir)
 }
 ```
 
-## Features
+Or run `veslx init` to generate it.
+
+---
+
+## Styling
 
-- **MDX Support** - Write with React components in markdown
-- **Math Rendering** - LaTeX equations via KaTeX
-- **Syntax Highlighting** - Code blocks with Shiki
-- **Hot Reload** - See changes instantly during development
-- **Slide Presentations** - Keyboard-navigable slides from markdown
-- **Dark Mode** - Automatic theme switching
-- **Daemon Mode** - Run as a background service with PM2
+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](https://tailwindcss.com) and [shadcn/ui](https://ui.shadcn.com) components.
+
+---
 
 ## Development
 
 ```bash
+# Clone the repo
+git clone https://github.com/eoinmurray/veslx.git
+cd veslx
+
 # Install dependencies
 bun install
 
-# Run locally
+# Run in dev mode (with hot reload on src/)
 bun run dev
 
-# Type check
-bun run typecheck
+# Build for production
+bun run build
+```
+
+### Project Structure
 
-# Lint
-bun run lint
 ```
+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](https://bun.sh)
+- **Build**: [Vite](https://vitejs.dev)
+- **Framework**: [React 19](https://react.dev)
+- **Styling**: [Tailwind CSS 4](https://tailwindcss.com)
+- **Components**: [shadcn/ui](https://ui.shadcn.com) + [Radix](https://radix-ui.com)
+- **MDX**: [@mdx-js/rollup](https://mdxjs.com)
+- **Math**: [KaTeX](https://katex.org)
+- **Syntax**: [Shiki](https://shiki.style)
+- **Daemon**: [PM2](https://pm2.keymetrics.io)
+
+---
 
 ## License
 
 MIT
+
+---
+
+<p align="center">
+  <sub>Built with care for researchers, engineers, and anyone who writes technical content.</sub>
+</p>

package/bin/lib/build.ts

@@ -1,5 +1,5 @@
-
 import { build } from 'vite'
+import { execSync } from 'child_process'
 import path from 'path'
 import fs from 'fs'
 import importConfig from "./import-config";
@@ -24,17 +24,69 @@ function copyDirSync(src: string, dest: string) {
   }
 }
 
-export default async function buildApp() {
+interface PackageJson {
+  name?: string;
+  description?: string;
+}
+
+async function readPackageJson(cwd: string): Promise<PackageJson | null> {
+  const file = Bun.file(path.join(cwd, 'package.json'));
+  if (!await file.exists()) return null;
+  try {
+    return await file.json();
+  } catch {
+    return null;
+  }
+}
+
+function getGitHubRepo(cwd: string): string {
+  try {
+    const remote = execSync('git remote get-url origin', { cwd, encoding: 'utf-8' }).trim();
+    const match = remote.match(/github\.com[:/]([^/]+\/[^/.]+)/);
+    return match ? match[1] : '';
+  } catch {
+    return '';
+  }
+}
+
+async function getDefaultConfig(cwd: string) {
+  const pkg = await readPackageJson(cwd);
+  const folderName = path.basename(cwd);
+  const name = pkg?.name || folderName;
+
+  return {
+    dir: '.',
+    site: {
+      name,
+      description: pkg?.description || '',
+      github: getGitHubRepo(cwd),
+    }
+  };
+}
+
+export default async function buildApp(dir?: string) {
   const cwd = process.cwd()
 
   console.log(`Building veslx app in ${cwd}`);
 
-  const config = await importConfig(cwd);
+  // Resolve content directory from CLI arg
+  const contentDir = dir
+    ? (path.isAbsolute(dir) ? dir : path.resolve(cwd, dir))
+    : cwd;
 
-  if (!config) {
-    console.error("Configuration file 'veslx.config.ts' not found in the current directory.");
-    return
-  }
+  // Get defaults first, then merge with config file if it exists
+  // Look for config in content directory first, then fall back to cwd
+  const defaults = await getDefaultConfig(contentDir);
+  const fileConfig = await importConfig(contentDir) || await importConfig(cwd);
+
+  // CLI argument takes precedence over config file
+  const config = {
+    dir: dir || fileConfig?.dir || defaults.dir,
+    site: {
+      ...defaults.site,
+      ...fileConfig?.site,
+    }
+  };
 
   const veslxRoot = new URL('../..', import.meta.url).pathname;
   const configFile = new URL('../../vite.config.ts', import.meta.url).pathname;
@@ -43,10 +95,10 @@ export default async function buildApp() {
   const tempOutDir = path.join(veslxRoot, '.veslx-build')
   const finalOutDir = path.join(cwd, 'dist')
 
-  // Resolve content directory relative to user's cwd (where config lives)
-  const contentDir = path.isAbsolute(config.dir)
-    ? config.dir
-    : path.resolve(cwd, config.dir);
+  // Final content directory: CLI arg already resolved, or resolve from config
+  const finalContentDir = dir
+    ? contentDir
+    : (path.isAbsolute(config.dir) ? config.dir : path.resolve(cwd, config.dir));
 
   await build({
     root: veslxRoot,
@@ -63,7 +115,7 @@ export default async function buildApp() {
       },
     },
     plugins: [
-      veslxPlugin(contentDir)
+      veslxPlugin(finalContentDir, config)
     ],
     logLevel: 'info',
   })
@@ -78,4 +130,4 @@ export default async function buildApp() {
   fs.rmSync(tempOutDir, { recursive: true })
 
   console.log(`\nBuild complete: ${finalOutDir}`)
-}
+}

package/bin/lib/import-config.ts

@@ -1,13 +1,14 @@
+import yaml from 'js-yaml';
+import type { VeslxConfig } from '../../plugin/src/types';
 
-
-export default async function importConfig(root: string) {
-  const file = Bun.file(`${root}/veslx.config.ts`);
+export default async function importConfig(root: string): Promise<VeslxConfig | undefined> {
+  const file = Bun.file(`${root}/veslx.yaml`);
 
   if (!await file.exists()) {
-    return
+    return undefined;
   }
-  
-  const module = await import(`file://${root}/veslx.config.ts`);
-  const config = module.default;
-  return config
-}
+
+  const content = await file.text();
+  const config = yaml.load(content) as VeslxConfig;
+  return config;
+}

package/bin/lib/init.ts

@@ -1,31 +1,30 @@
-import { createPrompt } from "bun-promptx";
+import nodePath from "path";
+import yaml from "js-yaml";
 
 export default async function createNewConfig() {
+  const configPath = "veslx.yaml";
 
-  const path = "veslx.config.ts"
-
-  if (await Bun.file(path).exists()) {
-    console.error(`Configuration file '${path}' already exists in the current directory.`);
-    return
+  if (await Bun.file(configPath).exists()) {
+    console.error(`Configuration file '${configPath}' already exists.`);
+    return;
   }
 
-  console.log("Initializing a new veslx project...");
-
-  const dir = createPrompt("Enter dir: ");
-  if (dir.error) {
-    console.error("Failed to read dir");
-    process.exit(1);
-  }
+  const cwd = process.cwd();
+  const folderName = nodePath.basename(cwd);
 
-  console.log("You entered:", dir.value);
+  const config = {
+    dir: ".",
+    site: {
+      name: folderName,
+      github: "",
+    },
+  };
 
-  const configStr = `
-export default {
-  dir: '${dir.value}',
-}`
+  const configStr = yaml.dump(config, { indent: 2, quotingType: '"' });
 
-  await Bun.write(path, configStr.trim());
+  await Bun.write(configPath, configStr);
 
-  console.log("Created 'veslx.config.ts' in the current directory.");
-  console.log("You can now run 'veslx serve' to start the development server.");
-}
+  console.log(`Created veslx.yaml`);
+  console.log(`\nEdit the file to customize your site, then run:`);
+  console.log(`  veslx serve`);
+}

package/bin/lib/serve.ts

@@ -1,27 +1,81 @@
 import { createServer } from 'vite'
+import { execSync } from 'child_process'
 import importConfig from "./import-config";
 import veslxPlugin from '../../plugin/src/plugin'
 import path from 'path'
 
-export default async function start() {
+interface PackageJson {
+  name?: string;
+  description?: string;
+}
+
+async function readPackageJson(cwd: string): Promise<PackageJson | null> {
+  const file = Bun.file(path.join(cwd, 'package.json'));
+  if (!await file.exists()) return null;
+  try {
+    return await file.json();
+  } catch {
+    return null;
+  }
+}
+
+function getGitHubRepo(cwd: string): string {
+  try {
+    const remote = execSync('git remote get-url origin', { cwd, encoding: 'utf-8' }).trim();
+    // Parse github URL: git@github.com:user/repo.git or https://github.com/user/repo.git
+    const match = remote.match(/github\.com[:/]([^/]+\/[^/.]+)/);
+    return match ? match[1] : '';
+  } catch {
+    return '';
+  }
+}
+
+async function getDefaultConfig(cwd: string) {
+  const pkg = await readPackageJson(cwd);
+  const folderName = path.basename(cwd);
+  const name = pkg?.name || folderName;
+
+  return {
+    dir: '.',
+    site: {
+      name,
+      description: pkg?.description || '',
+      github: getGitHubRepo(cwd),
+    }
+  };
+}
+
+export default async function start(dir?: string) {
   const cwd = process.cwd()
 
   console.log(`Starting veslx dev server in ${cwd}`);
 
-  const config = await importConfig(cwd);
+  // Resolve content directory - CLI arg takes precedence
+  const contentDir = dir
+    ? (path.isAbsolute(dir) ? dir : path.resolve(cwd, dir))
+    : cwd;
 
-  if (!config) {
-    console.error("Configuration file 'veslx.config.ts' not found in the current directory.");
-    return
-  }
+  // Get defaults first, then merge with config file if it exists
+  // Look for config in content directory first, then fall back to cwd
+  const defaults = await getDefaultConfig(contentDir);
+  const fileConfig = await importConfig(contentDir) || await importConfig(cwd);
+
+  // CLI argument takes precedence over config file
+  const config = {
+    dir: dir || fileConfig?.dir || defaults.dir,
+    site: {
+      ...defaults.site,
+      ...fileConfig?.site,
+    }
+  };
 
   const veslxRoot = new URL('../..', import.meta.url).pathname;
   const configFile = new URL('../../vite.config.ts', import.meta.url).pathname;
 
-  // Resolve content directory relative to user's cwd (where config lives)
-  const contentDir = path.isAbsolute(config.dir)
-    ? config.dir
-    : path.resolve(cwd, config.dir);
+  // Final content directory: CLI arg already resolved, or resolve from config
+  const finalContentDir = dir
+    ? contentDir
+    : (path.isAbsolute(config.dir) ? config.dir : path.resolve(cwd, config.dir));
 
   const server = await createServer({
     root: veslxRoot,
@@ -29,11 +83,11 @@ export default async function start() {
     // Cache in user's project so it persists across bunx runs
     cacheDir: path.join(cwd, 'node_modules/.vite'),
     plugins: [
-      veslxPlugin(contentDir)
+      veslxPlugin(finalContentDir, config)
     ],
   })
 
   await server.listen()
   server.printUrls()
   server.bindCLIShortcuts({ print: true })
-}
+}