skimmd 1.0.0

package/README.md

@@ -0,0 +1,181 @@
+# skimmd
+
+**One command. Zero install. Your markdown, beautifully rendered.**
+
+```bash
+npx skimmd
+```
+
+That's it. Browser opens. Your markdown files look like GitHub. Edit them live.
+
+---
+
+## The Problem
+
+You're writing a README. You want to see how it looks on GitHub. Your options:
+
+1. Push to GitHub, refresh, fix typo, push again, refresh... (we've all been there)
+2. Install a 200MB Electron app
+3. Use VS Code's preview that looks nothing like GitHub
+4. Use `grip` but hit GitHub API rate limits
+
+**skimmd**: One command, works offline, looks like GitHub, updates as you type.
+
+---
+
+## 30-Second Demo
+
+```bash
+# You have Node.js? You're done.
+npx skimmd README.md
+```
+
+Your browser opens. You see your README rendered beautifully. Now open that file in VS Code and make a change. Save. **The browser updates instantly.**
+
+No reload button. No refresh. Just save and see.
+
+---
+
+## Features
+
+### Live Reload
+Edit in VS Code, Vim, or any editor. Save. Browser updates. No plugins, no extensions, no configuration.
+
+### Inline Editing
+Click "Edit" in the browser. Make changes. Hit Ctrl+S. **Saves directly to your .md file.** Your editor picks up the change. Round-trip editing.
+
+### GitHub-Flavored Markdown
+- Tables render correctly
+- Task lists work (`- [x] like this`)
+- Syntax highlighting for 190+ languages
+- Fenced code blocks
+- Strikethrough, autolinks, all of it
+
+### Dark Mode
+Light, Dark, or Auto (follows your system). Because it's 2024 and we're not animals.
+
+### Browse Entire Folders
+```bash
+npx skimmd ./docs
+```
+Sidebar shows all your markdown files. Filter them. Jump between them. Table of contents auto-generated from headings.
+
+---
+
+## Why Not Just Use...
+
+| Tool | The Problem |
+|------|-------------|
+| **VS Code Preview** | Doesn't look like GitHub. No live reload in browser. |
+| **grip** | Hits GitHub API. Rate limited. Requires auth for private repos. |
+| **Typora** | $15. Electron app. Doesn't look like GitHub. |
+| **MacDown** | macOS only. No live reload. Dated UI. |
+| **Obsidian** | Overkill for previewing a README. Different styling. |
+| **glow** | Terminal only. Can't share screen with non-terminal people. |
+| **peekmd** | Requires Bun. No editing. No live reload. |
+
+**skimmd**: Works with Node (you already have it). Zero config. Live reload. Inline editing. Looks like GitHub.
+
+---
+
+## Installation
+
+**Option 1: No install (recommended)**
+```bash
+npx skimmd
+```
+
+**Option 2: Global install**
+```bash
+npm install -g skimmd
+skimmd
+```
+
+---
+
+## Usage
+
+```bash
+# Current directory
+skimmd
+
+# Specific file
+skimmd README.md
+
+# Documentation folder
+skimmd ./docs
+
+# Custom port
+skimmd --port 8080
+
+# Don't auto-open browser
+skimmd --no-open
+```
+
+---
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl/Cmd + S` | Save (when editing) |
+| `Ctrl/Cmd + K` | Focus file filter |
+
+---
+
+## How It Works
+
+1. Starts a local Express server
+2. Watches your markdown files with chokidar
+3. Renders with `marked` (GitHub-flavored)
+4. Syntax highlighting with `highlight.js`
+5. Sends file changes via Server-Sent Events
+6. Browser updates without refresh
+
+All local. Nothing leaves your machine. Works on a plane.
+
+---
+
+## FAQ
+
+**Does it work offline?**
+Yes. Everything runs locally. No API calls.
+
+**Can I use it for a presentation?**
+Yes. Dark mode + clean UI + live reload = great for live coding demos.
+
+**Does it support Mermaid diagrams?**
+Not yet. PRs welcome.
+
+**What about MDX?**
+Just markdown for now. Keep it simple.
+
+**Windows support?**
+Yes. Works anywhere Node.js runs.
+
+---
+
+## Contributing
+
+Found a bug? Want a feature? PRs welcome.
+
+```bash
+git clone https://github.com/lil-Zlang/skimmd
+cd skimmd
+npm install
+npm link
+skimmd ./docs
+```
+
+---
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+  <b>Stop pushing to GitHub just to preview your README.</b><br>
+  <code>npx skimmd</code>
+</p>

package/bin/skimmd.js

@@ -0,0 +1,379 @@
+#!/usr/bin/env node
+
+import path from "path";
+import fs from "fs";
+import fsp from "fs/promises";
+import { fileURLToPath } from "url";
+import express from "express";
+import open from "open";
+import getPort from "get-port";
+import fg from "fast-glob";
+import { program } from "commander";
+import { marked } from "marked";
+import hljs from "highlight.js";
+import TurndownService from "turndown";
+import { watch } from "chokidar";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function normalizeToPosix(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+
+function resolveSafePath(root, target) {
+  const safeTarget = target.replace(/^\/+/, "");
+  const resolvedRoot = path.resolve(root);
+  const resolvedTarget = path.resolve(resolvedRoot, safeTarget);
+  if (resolvedTarget === resolvedRoot) {
+    return resolvedTarget;
+  }
+  if (!resolvedTarget.startsWith(resolvedRoot + path.sep)) {
+    throw new Error("Invalid file path");
+  }
+  return resolvedTarget;
+}
+
+marked.setOptions({
+  gfm: true,
+  breaks: false,
+  highlight: (code, lang) => {
+    if (lang && hljs.getLanguage(lang)) {
+      return hljs.highlight(code, { language: lang }).value;
+    }
+    return hljs.highlightAuto(code).value;
+  },
+});
+
+const turndownService = new TurndownService({
+  codeBlockStyle: "fenced",
+  headingStyle: "atx",
+  bulletListMarker: "-",
+});
+
+async function scanFiles(folderPath) {
+  const entries = await fg(["**/*.{md,markdown,txt}"], {
+    cwd: folderPath,
+    onlyFiles: true,
+    caseSensitiveMatch: false,
+    ignore: ["**/node_modules/**"],
+  });
+
+  const files = await Promise.all(
+    entries.map(async (relativePath) => {
+      const fullPath = path.join(folderPath, relativePath);
+      const stats = await fsp.stat(fullPath);
+      const relativePosix = normalizeToPosix(relativePath);
+      return {
+        id: relativePosix,
+        name: path.basename(relativePosix),
+        path: fullPath,
+        relativePath: relativePosix,
+        metadata: {
+          size: stats.size,
+          modifiedAt: stats.mtime,
+          createdAt: stats.birthtime,
+        },
+      };
+    })
+  );
+
+  files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  return files;
+}
+
+async function ensureSingleFileEntry(folderPath, singleFile) {
+  try {
+    const stats = await fsp.stat(singleFile.absolutePath);
+    const relativePath = normalizeToPosix(
+      path.relative(folderPath, singleFile.absolutePath)
+    );
+    return {
+      id: relativePath,
+      name: singleFile.name,
+      path: singleFile.absolutePath,
+      relativePath,
+      metadata: {
+        size: stats.size,
+        modifiedAt: stats.mtime,
+        createdAt: stats.birthtime,
+      },
+    };
+  } catch {
+    return null;
+  }
+}
+
+function applySingleFileFilter(files, singleFile) {
+  if (!singleFile) {
+    return files;
+  }
+  const filtered = files.filter((file) => {
+    return (
+      file.name === singleFile.name ||
+      file.relativePath === singleFile.relativePath ||
+      file.path === singleFile.absolutePath ||
+      file.relativePath.endsWith("/" + singleFile.name) ||
+      file.relativePath === singleFile.name
+    );
+  });
+  return filtered;
+}
+
+// Store SSE clients for live reload
+const sseClients = new Set();
+
+function broadcastReload(filePath) {
+  const message = JSON.stringify({ type: "reload", file: filePath });
+  for (const client of sseClients) {
+    client.write(`data: ${message}\n\n`);
+  }
+}
+
+function setupFileWatcher(folderPath, singleFile) {
+  const watchPath = singleFile ? singleFile.absolutePath : folderPath;
+
+  const watcher = watch(watchPath, {
+    ignored: [/node_modules/, /\.git/],
+    persistent: true,
+    ignoreInitial: true,
+    depth: 10,
+  });
+
+  function isMarkdownFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return [".md", ".markdown", ".txt"].includes(ext);
+  }
+
+  watcher.on("change", (filePath) => {
+    if (!isMarkdownFile(filePath)) return;
+    const relative = path.relative(folderPath, filePath);
+    console.log(`File changed: ${relative}`);
+    broadcastReload(relative);
+  });
+
+  watcher.on("add", (filePath) => {
+    if (!isMarkdownFile(filePath)) return;
+    const relative = path.relative(folderPath, filePath);
+    console.log(`File added: ${relative}`);
+    broadcastReload(relative);
+  });
+
+  watcher.on("unlink", (filePath) => {
+    if (!isMarkdownFile(filePath)) return;
+    const relative = path.relative(folderPath, filePath);
+    console.log(`File removed: ${relative}`);
+    broadcastReload(relative);
+  });
+
+  watcher.on("ready", () => {
+    console.log("File watcher ready");
+  });
+
+  watcher.on("error", (error) => {
+    console.error("Watcher error:", error);
+  });
+
+  return watcher;
+}
+
+async function createServer(options) {
+  const { folderPath, singleFile, initialFile } = options;
+  const app = express();
+
+  app.use(express.json({ limit: "2mb" }));
+
+  // SSE endpoint for live reload
+  app.get("/api/events", (req, res) => {
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Connection", "keep-alive");
+    res.flushHeaders();
+
+    sseClients.add(res);
+
+    req.on("close", () => {
+      sseClients.delete(res);
+    });
+  });
+
+  app.get("/api/config", (_req, res) => {
+    res.json({
+      folderPath,
+      singleFile: singleFile ? singleFile.relativePath : null,
+      initialFile: initialFile || null,
+    });
+  });
+
+  app.get("/api/files", async (_req, res) => {
+    try {
+      let files = await scanFiles(folderPath);
+      if (singleFile) {
+        files = applySingleFileFilter(files, singleFile);
+        if (files.length === 0) {
+          const entry = await ensureSingleFileEntry(folderPath, singleFile);
+          if (entry) {
+            files = [entry];
+          }
+        }
+      }
+      res.json(files);
+    } catch (error) {
+      res.status(500).json({ error: error instanceof Error ? error.message : "Failed to list files" });
+    }
+  });
+
+  app.get("/api/file", async (req, res) => {
+    const fileId = req.query.path;
+    if (!fileId || typeof fileId !== "string") {
+      return res.status(400).json({ error: "Missing file path" });
+    }
+
+    try {
+      const safePath = resolveSafePath(folderPath, fileId);
+      const content = await fsp.readFile(safePath, "utf-8");
+      const stats = await fsp.stat(safePath);
+      const html = marked.parse(content);
+
+      res.json({
+        content,
+        html,
+        metadata: {
+          size: stats.size,
+          modifiedAt: stats.mtime,
+          createdAt: stats.birthtime,
+        },
+      });
+    } catch (error) {
+      res.status(404).json({ error: error instanceof Error ? error.message : "File not found" });
+    }
+  });
+
+  app.put("/api/file", async (req, res) => {
+    const fileId = req.query.path;
+    const { content, html } = req.body || {};
+    if (!fileId || typeof fileId !== "string") {
+      return res.status(400).json({ error: "Missing file path" });
+    }
+
+    let finalContent = content;
+    if (typeof html === "string") {
+      finalContent = turndownService.turndown(html);
+    }
+    if (typeof finalContent !== "string") {
+      return res.status(400).json({ error: "Missing content" });
+    }
+
+    try {
+      const safePath = resolveSafePath(folderPath, fileId);
+      await fsp.writeFile(safePath, finalContent, "utf-8");
+      const stats = await fsp.stat(safePath);
+      const renderedHtml = marked.parse(finalContent);
+
+      res.json({
+        content: finalContent,
+        html: renderedHtml,
+        metadata: {
+          size: stats.size,
+          modifiedAt: stats.mtime,
+          createdAt: stats.birthtime,
+        },
+      });
+    } catch (error) {
+      res.status(500).json({ error: error instanceof Error ? error.message : "Failed to save file" });
+    }
+  });
+
+  app.post("/api/render", async (req, res) => {
+    const { content } = req.body || {};
+    if (typeof content !== "string") {
+      return res.status(400).json({ error: "Missing content" });
+    }
+    try {
+      const html = marked.parse(content);
+      res.json({ html });
+    } catch (error) {
+      res.status(500).json({ error: error instanceof Error ? error.message : "Failed to render markdown" });
+    }
+  });
+
+  app.use(express.static(path.join(__dirname, "..", "public")));
+
+  app.get("*", (_req, res) => {
+    res.sendFile(path.join(__dirname, "..", "public", "index.html"));
+  });
+
+  return app;
+}
+
+program
+  .name("skimmd")
+  .description("Instant markdown preview with GitHub-style rendering")
+  .argument("[path]", "Path to markdown file or folder", ".")
+  .option("-p, --port <number>", "Port to run on (default: auto-detect)")
+  .option("--no-open", "Don't open browser automatically")
+  .action(async (inputPath, options) => {
+    try {
+      const resolvedPath = path.resolve(inputPath);
+
+      if (!fs.existsSync(resolvedPath)) {
+        console.error(`Error: Path does not exist: ${resolvedPath}`);
+        process.exit(1);
+      }
+
+      const stats = fs.statSync(resolvedPath);
+      let folderPath;
+      let initialFile = null;
+      let singleFile = null;
+
+      if (stats.isDirectory()) {
+        folderPath = resolvedPath;
+      } else if (stats.isFile()) {
+        folderPath = path.dirname(resolvedPath);
+        initialFile = normalizeToPosix(path.relative(folderPath, resolvedPath));
+        singleFile = {
+          name: path.basename(resolvedPath),
+          absolutePath: resolvedPath,
+          relativePath: initialFile,
+        };
+      } else {
+        console.error(`Error: Invalid path: ${resolvedPath}`);
+        process.exit(1);
+      }
+
+      const port = options.port
+        ? Number(options.port)
+        : await getPort({ port: [3000, 3001, 3002, 3003, 3004, 3005] });
+
+      const app = await createServer({ folderPath, singleFile, initialFile });
+      const watcher = setupFileWatcher(folderPath, singleFile);
+
+      const server = app.listen(port, () => {
+        const url = new URL(`http://localhost:${port}`);
+        if (initialFile) {
+          url.searchParams.set("file", initialFile);
+        }
+
+        console.log(`skimmd running at ${url.toString()}`);
+        console.log(`Serving markdown from: ${folderPath}`);
+        console.log(`Watching for changes...`);
+
+        if (options.open) {
+          open(url.toString());
+        }
+      });
+
+      const shutdown = () => {
+        watcher.close();
+        server.close(() => process.exit(0));
+      };
+
+      process.on("SIGINT", shutdown);
+      process.on("SIGTERM", shutdown);
+    } catch (error) {
+      console.error("Error:", error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "skimmd",
+  "version": "1.0.0",
+  "description": "Instant markdown preview in your browser. Zero config, GitHub-style rendering, inline editing.",
+  "type": "module",
+  "bin": {
+    "skimmd": "./bin/skimmd.js"
+  },
+  "scripts": {
+    "start": "node bin/skimmd.js"
+  },
+  "keywords": [
+    "markdown",
+    "preview",
+    "github",
+    "readme",
+    "cli",
+    "viewer",
+    "editor",
+    "md",
+    "gfm"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lil-Zlang/skimmd.git"
+  },
+  "homepage": "https://github.com/lil-Zlang/skimmd#readme",
+  "bugs": {
+    "url": "https://github.com/lil-Zlang/skimmd/issues"
+  },
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "commander": "^12.1.0",
+    "express": "^4.19.2",
+    "fast-glob": "^3.3.3",
+    "get-port": "^7.1.0",
+    "highlight.js": "^11.11.1",
+    "marked": "^12.0.2",
+    "open": "^10.1.0",
+    "turndown": "^7.2.0"
+  }
+}