@exor404/mdslides 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eXor404
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# mdslides
+
+> Markdown in, presentation out.
+
+The slides sibling of [mdstack](https://github.com/eXor404/mdstack). Point it
+at a folder — `mdslides` scaffolds a starter `slides.md`, then presents it in a
+dev server or builds a self-contained `dist/` you can host anywhere static.
+
+> **Status:** pre-1.0, provisional. CLI flags and markdown conventions may
+> change before `0.x → 1.0`.
+
+## Quick start
+
+```bash
+mdslides ./chemistry          # scaffolds a project, then presents it
+```
+
+Point `mdslides` at a folder and it scaffolds a project: it **asks for a
+name**, writes `<name>.md` (e.g. `chemistry.md`) with three sample slides — a
+title page, a list, and a help slide — plus a `mdslides.config.js`, then opens
+the dev server. The name defaults to the folder, so pressing Enter at
+`Name your presentation (chemistry):` gives you `chemistry/chemistry.md`. That
+file *is* your deck — edit it and the slides live-reload.
+
+```bash
+mdslides ./chemistry          # present (dev server, live-reload)
+mdslides build ./chemistry    # static build → ./chemistry/dist/
+mdslides preview ./chemistry  # serve the built dist/
+mdslides export ./chemistry   # → chemistry.pdf (one page per slide)
+```
+
+Already have a deck? Point straight at the file: `mdslides ./chemistry.md`.
+
+Try the bundled example:
+
+```bash
+npm install
+npm run dev        # opens ./example
+```
+
+## The deck model
+
+**One markdown file is the whole deck.** Every `#` (H1) heading starts a new
+slide — write plain markdown in between. A standalone `---` line is an
+explicit break (for a slide with no heading, or to split one section).
+
+```markdown
+# Presentation title
+## A subtitle
+**Your Name** · {{date}}
+
+# Second slide
+- a point
+- another (bullets reveal one at a time)
+```
+
+### Title slide
+
+The **first slide is the title slide** automatically: the `#` renders large,
+`##` is the subtitle, and the last line becomes a byline pinned to the bottom —
+write your presenter name(s) in markdown there. The `{{date}}` token resolves to
+today's date. Opt a slide out with `<!-- slide: plain -->`, or mark another
+slide as a title with `<!-- slide: title -->`.
+
+## Supported markdown (the lean subset)
+
+Only what slides actually need:
+
+- Headings, paragraphs, **bold**, *italic*, ~~strike~~, ==highlight==
+- Lists (reveal one item at a time — see [Reveal & motion](#reveal--motion)), tables, blockquotes
+- `inline code` and fenced code blocks (syntax-highlighted via [Shiki](https://shiki.style))
+- Math — `$inline$` and `$$block$$` via KaTeX
+- Images (relative paths resolve from the deck folder)
+
+Fence a block with a language for syntax highlighting:
+
+````markdown
+```js
+export default { theme: 'angular' };
+```
+````
+
+## Presenting
+
+| Key | Action |
+| --- | --- |
+| `→` `space` `PageDn` | next slide / reveal next fragment |
+| `←` `PageUp` | previous |
+| `Home` / `End` | first / last slide |
+| `O` | overview grid (click a slide to jump) |
+| `F` | fullscreen |
+| `.` | black screen |
+| `?` | help |
+
+The URL hash tracks the current slide (`#/3`) so deep links work.
+
+### Reveal & motion
+
+Slides build themselves as you talk:
+
+- **Content fades in** when a slide opens — headings, paragraphs, images, code,
+  tables and quotes rise into place with a light stagger.
+- **Lists reveal step by step.** Every list item is hidden when the slide opens
+  and appears one at a time on `→` / `space`; `←` steps back. Once all items
+  are shown, the next press advances to the following slide. This is automatic —
+  you don't need to mark anything.
+- **Manual fragments.** Append `{.fragment}` to any other line (a paragraph,
+  a heading) to hold it back and reveal it on a later press, in document order
+  alongside the list items.
+
+In the **overview grid** and **PDF export**, everything is shown at once. Motion
+respects the OS "reduce motion" setting.
+
+### Per-slide directives
+
+A leading comment configures one slide:
+
+```markdown
+# A slide
+<!-- slide: center bg=#1a0b2e -->
+```
+
+- `center` — vertically + horizontally centered
+- `bg=<color|url(...)>` — slide background
+
+## Configuration
+
+First run drops a `mdslides.config.js` next to your deck:
+
+```js
+export default {
+  brand: { text: 'mdslides' },   // bottom-left wordmark; '' to hide
+  theme: 'angular',              // built-in: 'angular'
+  transition: 'fade',            // 'fade' | 'slide' | 'none'
+};
+```
+
+## PDF export
+
+`mdslides export` renders the `/print` route (one slide per page, all
+fragments shown). It uses [Playwright](https://playwright.dev) if installed
+(`npm i -D playwright && npx playwright install chromium`); otherwise open
+`/print` in a browser and use **Save as PDF**.
+
+## Releasing
+
+Releases go to the **public npm registry** (npmjs.com), so anyone can
+`npx @exor404/mdslides`. A tag-triggered GitHub Actions pipeline
+([`.github/workflows/package-publish.yml`](.github/workflows/package-publish.yml))
+publishes via **OIDC Trusted Publishing** — GitHub mints a one-time identity
+token for the run, so **no npm token or secret is ever stored**.
+
+**One-time setup** (needed once, because Trusted Publishing attaches to an
+existing package):
+
+```bash
+npm login                       # browser sign-in to npmjs.com
+npm publish --access public     # publish the first version by hand
+```
+
+Then on npmjs.com open the package → **Settings → Trusted Publisher → GitHub
+Actions** and register:
+
+- **Repository:** `eXor404/mdslides`
+- **Workflow filename:** `package-publish.yml`
+
+After that, every release is automatic:
+
+```bash
+npm version patch          # bumps package.json (0.1.0 → 0.1.1) and tags v0.1.1
+git push origin main       # push the version-bump commit
+git push origin v0.1.1     # push the tag → the pipeline publishes, tokenlessly
+```
+
+`npm version` creates the matching `vX.Y.Z` tag for you. The workflow refuses
+to publish if the tag and `package.json` version disagree, so they can't drift.
+
+## Requirements
+
+Node 18+.
+
+## License
+
+MIT

package/app/astro.config.mjs

@@ -0,0 +1,27 @@
+import { defineConfig } from 'astro/config';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import mdslidesAssets from './integrations/mdslides-assets.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const theme = process.env.MD_THEME || 'angular';
+const themeFile = resolve(__dirname, 'src', 'themes', `${theme}.css`);
+
+export default defineConfig({
+  // Markdown is rendered by src/lib/deck.js (a dedicated unified pipeline),
+  // not Astro's content layer — so there's no markdown config here.
+  integrations: [mdslidesAssets()],
+  vite: {
+    resolve: {
+      alias: {
+        '~theme': themeFile,
+      },
+    },
+    server: {
+      // mdslides is a local CLI; deps live above APP_ROOT (or hoisted under
+      // npx). Disable strict fs serving so KaTeX fonts and source-folder
+      // assets resolve regardless of where they're installed.
+      fs: { strict: false },
+    },
+  },
+});

package/app/integrations/mdslides-assets.js

@@ -0,0 +1,167 @@
+import { promises as fs, mkdtempSync, rmSync } from 'node:fs';
+import { resolve, relative, extname, join, dirname, basename, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+import { findChrome, printUrlToPdf } from './pdf-export.js';
+
+const MIME = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+};
+
+const EXCLUDED_TOP = new Set(['dist', 'node_modules', '.git', '.astro', '.vscode', '.idea']);
+const EXCLUDED_FILES = new Set(['mdslides.config.js']);
+
+function isExcludedRel(rel) {
+  if (!rel || rel === '.' || rel === '..') return true;
+  if (EXCLUDED_FILES.has(rel)) return true;
+  const parts = rel.split(/[\\/]/);
+  if (parts[0].startsWith('.')) return true;
+  if (EXCLUDED_TOP.has(parts[0])) return true;
+  return false;
+}
+
+// Copy every non-.md file from the source folder so a built deck is
+// self-contained (images, fonts, video…).
+async function* walkAssets(root, current = root) {
+  let entries;
+  try {
+    entries = await fs.readdir(current, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = join(current, entry.name);
+    const rel = relative(root, full);
+    if (isExcludedRel(rel)) continue;
+    if (entry.isDirectory()) {
+      yield* walkAssets(root, full);
+    } else if (entry.isFile() && extname(entry.name).toLowerCase() !== '.md') {
+      yield { full, rel };
+    }
+  }
+}
+
+export default function mdslidesAssets() {
+  const source = process.env.MD_SOURCE;
+  const deckFile = process.env.MD_FILE;
+  if (!source) {
+    throw new Error('mdslides: MD_SOURCE env var not set — run via the mdslides CLI.');
+  }
+
+  return {
+    name: 'mdslides:assets',
+    hooks: {
+      'astro:server:setup': ({ server }) => {
+        // PDF export endpoint: prints the live /print route to PDF with
+        // headless Chrome and streams it back as a download. This is the deck
+        // PDF button's primary path — browser-independent and pixel-accurate
+        // (Safari/Chrome ⌘P can't reliably size or color slide pages).
+        server.middlewares.use(async (req, res, next) => {
+          const path = (req.url || '').split('?')[0];
+          if (path !== '/__export.pdf') return next();
+          const chrome = findChrome();
+          if (!chrome) {
+            res.statusCode = 501;
+            res.end('No headless Chrome found. Install Google Chrome or set CHROME_PATH.');
+            return;
+          }
+          const host = req.headers.host || 'localhost';
+          const name = deckFile ? basename(deckFile).replace(/\.md$/i, '') : 'slides';
+          const dir = mkdtempSync(join(tmpdir(), 'mdslides-pdf-'));
+          const pdfPath = join(dir, `${name}.pdf`);
+          try {
+            await printUrlToPdf(chrome, `http://${host}/print/`, pdfPath);
+            const data = await fs.readFile(pdfPath);
+            res.setHeader('Content-Type', 'application/pdf');
+            res.setHeader('Content-Disposition', `attachment; filename="${name}.pdf"`);
+            res.setHeader('Content-Length', String(data.length));
+            res.end(data);
+          } catch (err) {
+            res.statusCode = 500;
+            res.end(`PDF export failed: ${err.message}`);
+          } finally {
+            try { rmSync(dir, { recursive: true, force: true }); } catch {}
+          }
+        });
+
+        // Live-reload when the deck markdown changes (it lives outside Astro's
+        // own watched tree, so add it explicitly).
+        if (deckFile) {
+          server.watcher.add(deckFile);
+          server.watcher.on('change', (changed) => {
+            if (resolve(changed) === resolve(deckFile)) {
+              server.ws.send({ type: 'full-reload' });
+            }
+          });
+        }
+
+        // Serve source-folder assets in dev.
+        server.middlewares.use(async (req, res, next) => {
+          if (!req.url || (req.method && req.method !== 'GET' && req.method !== 'HEAD')) {
+            return next();
+          }
+          let pathname;
+          try {
+            pathname = decodeURIComponent(req.url.split('?')[0].split('#')[0]);
+          } catch {
+            return next();
+          }
+          if (!pathname || pathname === '/' || pathname.endsWith('/')) return next();
+          const ext = extname(pathname).toLowerCase();
+          if (!ext || ext === '.md') return next();
+          if (pathname.startsWith('/@') || pathname.startsWith('/_astro/') || pathname.startsWith('/node_modules/')) {
+            return next();
+          }
+
+          const rel = pathname.replace(/^\/+/, '');
+          if (isExcludedRel(rel)) return next();
+
+          const filePath = resolve(source, rel);
+          const sourceWithSep = source.endsWith(sep) ? source : source + sep;
+          if (filePath !== source && !filePath.startsWith(sourceWithSep)) return next();
+
+          try {
+            const stat = await fs.stat(filePath);
+            if (!stat.isFile()) return next();
+            res.setHeader('Content-Type', MIME[ext] || 'application/octet-stream');
+            res.setHeader('Content-Length', String(stat.size));
+            res.setHeader('Cache-Control', 'no-cache');
+            if (req.method === 'HEAD') {
+              res.end();
+              return;
+            }
+            res.end(await fs.readFile(filePath));
+          } catch {
+            return next();
+          }
+        });
+      },
+      'astro:build:done': async ({ dir, logger }) => {
+        const outDir = fileURLToPath(dir);
+        const log = logger?.info?.bind(logger) ?? console.log;
+        let count = 0;
+        for await (const { full, rel } of walkAssets(source)) {
+          const dest = join(outDir, rel);
+          await fs.mkdir(dirname(dest), { recursive: true });
+          await fs.copyFile(full, dest);
+          count++;
+        }
+        if (count > 0) log(`copied ${count} asset${count === 1 ? '' : 's'} from source folder`);
+      },
+    },
+  };
+}

package/app/integrations/pdf-export.js

@@ -0,0 +1,86 @@
+// Shared headless-Chrome PDF helper, used by both the `mdslides export` CLI
+// command and the dev server's /__export.pdf endpoint.
+import { spawn, execSync } from 'node:child_process';
+import { existsSync, statSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+function whichSync(bin) {
+  try {
+    return execSync(`command -v ${bin}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+export function findChrome() {
+  if (process.env.CHROME_PATH && existsSync(process.env.CHROME_PATH)) return process.env.CHROME_PATH;
+  const candidates = [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+  ];
+  for (const c of candidates) if (existsSync(c)) return c;
+  for (const bin of ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser']) {
+    const found = whichSync(bin);
+    if (found) return found;
+  }
+  return null;
+}
+
+// Print a URL to `pdfPath` with headless Chrome. Recent Chrome
+// (`--headless=new`) does the print but doesn't reliably exit, so we wait for
+// the PDF's size to settle, then kill the process — robust across versions.
+export function printUrlToPdf(chrome, url, pdfPath) {
+  return new Promise((res, rej) => {
+    try { if (existsSync(pdfPath)) rmSync(pdfPath); } catch {}
+    const profile = mkdtempSync(join(tmpdir(), 'mdslides-'));
+    const args = [
+      '--headless=new',
+      '--disable-gpu',
+      '--no-sandbox',
+      '--hide-scrollbars',
+      '--no-pdf-header-footer',
+      '--run-all-compositor-stages-before-draw',
+      '--virtual-time-budget=5000',
+      `--user-data-dir=${profile}`,
+      `--print-to-pdf=${pdfPath}`,
+      url,
+    ];
+    const ps = spawn(chrome, args, { stdio: 'ignore' });
+
+    let done = false;
+    let lastSize = -1;
+    let stable = 0;
+    const finish = (err) => {
+      if (done) return;
+      done = true;
+      clearInterval(poll);
+      clearTimeout(timer);
+      try { ps.kill('SIGKILL'); } catch {}
+      try { rmSync(profile, { recursive: true, force: true }); } catch {}
+      err ? rej(err) : res(pdfPath);
+    };
+    const poll = setInterval(() => {
+      if (!existsSync(pdfPath)) return;
+      let size = 0;
+      try { size = statSync(pdfPath).size; } catch { return; }
+      if (size > 0 && size === lastSize) {
+        if (++stable >= 3) finish();
+      } else {
+        stable = 0;
+        lastSize = size;
+      }
+    }, 300);
+    const timer = setTimeout(() => finish(new Error('Chrome timed out after 45s')), 45000);
+
+    ps.on('error', finish);
+    ps.on('exit', (code) => {
+      if (existsSync(pdfPath)) finish();
+      else finish(new Error(`Chrome exited with code ${code} without producing a PDF`));
+    });
+  });
+}

package/app/integrations/rehype-shiki.js

@@ -0,0 +1,59 @@
+// Syntax-highlight fenced code blocks with Shiki.
+//
+// We keep the deck's own `<pre><code>` wrapper (so the theme's border, radius,
+// padding and dark background still apply) and only swap the code's children
+// for Shiki's colored token spans. Spans carry inline `color` styles, so no
+// extra theme CSS is needed. Code blocks with no language — or an unknown one —
+// are left untouched.
+import { codeToHast } from 'shiki';
+
+const THEME = 'github-dark';
+
+function rawText(node) {
+  if (node.type === 'text') return node.value;
+  if (Array.isArray(node.children)) return node.children.map(rawText).join('');
+  return '';
+}
+
+function langOf(codeEl) {
+  const cls = codeEl.properties?.className;
+  const list = Array.isArray(cls) ? cls : cls ? [cls] : [];
+  const hit = list.map(String).find((c) => c.startsWith('language-'));
+  return hit ? hit.slice('language-'.length) : null;
+}
+
+export default function rehypeShiki() {
+  // Collect <pre><code> blocks first, then highlight them (async).
+  return async (tree) => {
+    const blocks = [];
+    const visit = (node) => {
+      if (
+        node.type === 'element' &&
+        node.tagName === 'pre' &&
+        node.children?.[0]?.type === 'element' &&
+        node.children[0].tagName === 'code'
+      ) {
+        blocks.push(node.children[0]);
+        return; // don't descend into code
+      }
+      if (Array.isArray(node.children)) node.children.forEach(visit);
+    };
+    visit(tree);
+
+    await Promise.all(
+      blocks.map(async (code) => {
+        const lang = langOf(code);
+        if (!lang) return;
+        const source = rawText(code).replace(/\n$/, '');
+        try {
+          const hast = await codeToHast(source, { lang, theme: THEME });
+          const pre = hast.children.find((c) => c.tagName === 'pre');
+          const inner = pre?.children.find((c) => c.tagName === 'code');
+          if (inner) code.children = inner.children;
+        } catch {
+          // Unknown language → leave the code block as plain text.
+        }
+      })
+    );
+  };
+}

package/app/integrations/remark-highlight.js

@@ -0,0 +1,45 @@
+// ==highlight== → <mark>highlight</mark>
+const HIGHLIGHT_RE = /==([^=\n]+?)==/g;
+
+function transformChildren(parent) {
+  if (!Array.isArray(parent.children)) return;
+  const out = [];
+  for (const child of parent.children) {
+    if (Array.isArray(child.children)) transformChildren(child);
+
+    if (child.type !== 'text' || typeof child.value !== 'string' || !child.value.includes('==')) {
+      out.push(child);
+      continue;
+    }
+
+    const value = child.value;
+    let lastIdx = 0;
+    let matched = false;
+    HIGHLIGHT_RE.lastIndex = 0;
+    let m;
+    while ((m = HIGHLIGHT_RE.exec(value)) !== null) {
+      matched = true;
+      if (m.index > lastIdx) {
+        out.push({ type: 'text', value: value.slice(lastIdx, m.index) });
+      }
+      // Custom mdast node → <mark> via data.hName (no raw HTML, so it
+      // survives remark-rehype without allowDangerousHtml).
+      out.push({
+        type: 'highlight',
+        data: { hName: 'mark' },
+        children: [{ type: 'text', value: m[1] }],
+      });
+      lastIdx = m.index + m[0].length;
+    }
+    if (!matched) {
+      out.push(child);
+    } else if (lastIdx < value.length) {
+      out.push({ type: 'text', value: value.slice(lastIdx) });
+    }
+  }
+  parent.children = out;
+}
+
+export default function remarkHighlight() {
+  return (tree) => transformChildren(tree);
+}

package/app/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "mdslides-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module"
+}

package/app/public/favicon.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 28 28">
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#ff0080"/>
+      <stop offset="50%" stop-color="#ff4500"/>
+      <stop offset="100%" stop-color="#ffa500"/>
+    </linearGradient>
+    <style>
+      .frame { fill: #0d0d0d; }
+      @media (prefers-color-scheme: light) { .frame { fill: #ffffff; } }
+    </style>
+  </defs>
+  <rect x="0" y="0" width="28" height="28" rx="7" fill="url(#g)"/>
+  <rect x="4" y="9" width="20" height="13" rx="2" class="frame"/>
+  <rect x="7" y="12" width="14" height="2.4" rx="1.2" fill="url(#g)"/>
+  <rect x="7" y="16.5" width="9" height="2.4" rx="1.2" fill="url(#g)"/>
+</svg>