pandoc-glance 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oliver MacLaren
+
+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,280 @@
+# pandoc-glance
+
+`pandoc-glance` renders Markdown and LaTeX files as good-looking pages in your browser. Add `--watch` to refresh the page whenever you save.
+
+![Dark browser preview showing MathML, highlighted TypeScript, and Mermaid](https://raw.githubusercontent.com/omaclaren/pandoc-glance/main/docs/screenshots/dark-browser.png)
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 22 or newer
+- [Pandoc](https://pandoc.org/) on `PATH`
+
+Install Pandoc on macOS with:
+
+```bash
+brew install pandoc
+```
+
+On Debian/Ubuntu, use `sudo apt install pandoc`. On Windows, use `winget install --id JohnMacFarlane.Pandoc`. If Pandoc is installed elsewhere, set `PANDOC_PATH` to the executable.
+
+## Install
+
+```bash
+npm install --global pandoc-glance
+```
+
+## Usage
+
+```text
+pandoc-glance [options] <file>
+pandoc-glance --watch [options] <file>
+pandoc-glance <file> --watch
+```
+
+| Option | Meaning |
+|---|---|
+| `-w, --watch` | Start a live preview server and re-render after saved changes |
+| `--no-open` | Do not launch a browser; print the generated path or preview URL |
+| `--theme auto\|light\|dark` | Browser theme; default `auto` follows `prefers-color-scheme` |
+| `--format auto\|markdown\|latex` | Input format; default `auto` uses the file extension |
+| `--font-size <px>` | Base document font size from 10 to 24; default 15 |
+| `--port <number>` | Watch-server port; `0` or omission chooses an available port |
+| `-h, --help` | Show help |
+| `-v, --version` | Show the version |
+
+Automatic format detection recognizes common Markdown extensions (`.md`, `.markdown`, `.mdown`, `.mkd`, `.qmd`, and `.rmd`) and standalone LaTeX (`.tex` and `.latex`). Use `--format` for another extension.
+
+### One-shot preview
+
+```bash
+pandoc-glance notes.md
+pandoc-glance paper.tex --theme light --font-size 16
+```
+
+One-shot mode writes a cached HTML file and opens it in the default browser. The cache keeps at most 30 previews.
+
+For headless or SSH use:
+
+```bash
+pandoc-glance --no-open notes.md
+# HTML: /path/to/cache/<id>.html
+```
+
+### Watch mode
+
+```bash
+pandoc-glance --watch notes.md
+pandoc-glance notes.md --watch --theme auto
+pandoc-glance --watch --no-open --port 0 notes.md
+```
+
+Watch mode:
+
+- Opens one browser tab and updates it after each saved change.
+- Handles ordinary writes and atomic saves.
+- Preserves reading position across reloads.
+- Keeps the last successful preview visible after a render error and recovers on the next valid save.
+
+Watch mode sees files on disk, not unsaved editor buffers. Enable autosave for faster updates. If the initial render fails, the error page stays open and waits for a valid save. Stop the server with Ctrl-C.
+
+## Rendering examples
+
+### Math
+
+All of these forms are supported in Markdown:
+
+```markdown
+Inline dollar math: $E = mc^2$.
+
+Inline parenthesized math: \(a^2 + b^2 = c^2\).
+
+$$
+\int_0^1 x^2\,dx = \frac{1}{3}
+$$
+
+\[
+\mathbf{A}\mathbf{x} = \mathbf{b}
+\]
+```
+
+Pandoc emits native MathML when possible. The browser loads MathJax only for equations that Pandoc leaves as TeX.
+
+### Mermaid
+
+````markdown
+```mermaid
+flowchart LR
+  Source[Markdown or LaTeX] --> Pandoc
+  Pandoc --> Browser
+```
+````
+
+Mermaid runs in the preview page and loads only when a `mermaid` fence is present. No local Mermaid package or Mermaid CLI (`mmdc`) is required.
+
+Flowchart icon nodes support `lucide:*` and `logos:*`. Keep each icon declaration on one source line:
+
+````markdown
+```mermaid
+flowchart LR
+  source@{ icon: "lucide:file-code-2", label: "Source" }
+  github@{ icon: "logos:github-icon", label: "GitHub" }
+  source --> github
+```
+````
+
+If Mermaid or an icon pack cannot load, the preview shows the error and the original diagram source.
+
+### Local resources and Obsidian images
+
+Relative paths resolve from the source document's directory:
+
+```markdown
+![Experiment result](figures/result.png)
+![Path containing spaces](<figures/run 01.png>)
+![[figures/result.png|Obsidian-style caption]]
+```
+
+Absolute local image paths are also supported. Watch mode uses revisioned, non-cached resource URLs so saved image changes appear immediately.
+
+### Standalone LaTeX
+
+A `.tex` or `.latex` file is read as a complete LaTeX document:
+
+```latex
+\documentclass{article}
+\usepackage{amsmath}
+\begin{document}
+\section{Example}
+Inline math $x^2$ and display math
+\[
+  \int_0^1 x^2\,dx = \frac{1}{3}.
+\]
+\end{document}
+```
+
+Previewing LaTeX does not run a TeX engine; Pandoc converts supported document structure and equations directly to HTML5/MathML.
+
+## Editor and shell integration
+
+Launch watch mode from any editor or task runner that can invoke a shell command:
+
+```bash
+pandoc-glance --watch "/absolute/path/to/current-file.md"
+```
+
+### Zed
+
+Add this task to `.zed/tasks.json` in a project or to Zed's global tasks file:
+
+```json
+[
+  {
+    "label": "Preview current Markdown/LaTeX file",
+    "command": "pandoc-glance",
+    "args": ["--watch", "$ZED_FILE"],
+    "cwd": "$ZED_WORKTREE_ROOT",
+    "use_new_terminal": true,
+    "allow_concurrent_runs": false,
+    "reveal": "always",
+    "save": "current"
+  }
+]
+```
+
+Run **Preview current Markdown/LaTeX file** from Zed's task picker. With autosave enabled, the browser updates shortly after edits.
+
+### Other examples
+
+- VS Code tasks can pass `${file}`.
+- Vim and Neovim commands can pass the current buffer's expanded filename after writing it.
+- Over SSH, use `--watch --no-open` and forward the printed port when remote browser access is needed.
+- Scripts and CI checks can use one-shot `--no-open` without launching a GUI.
+
+The server binds to `127.0.0.1`, so remote access requires an explicit tunnel such as `ssh -L`.
+
+## Network use
+
+Pandoc conversion, styling, native MathML, syntax highlighting, local resources, and live reload are local. The browser downloads these optional components as needed:
+
+- Mermaid 11.16 from jsDelivr when the document contains a Mermaid block.
+- Lucide or Logos icon data from unpkg when a diagram uses that pack.
+- MathJax 3 from jsDelivr when Pandoc leaves an equation as TeX.
+
+Without network access, the core preview still works. Mermaid remains visible as source with an error, and unsupported equations remain as TeX with a warning.
+
+## Security model
+
+Watch mode:
+
+- Binds only to `127.0.0.1`.
+- Uses a random 192-bit token in every preview route.
+- Sets `no-store`, `nosniff`, no-referrer, same-origin, and content-security headers.
+- Rejects path traversal, including encoded `..` and symlinks outside the source directory.
+- Serves an outside absolute file only when the current document explicitly references it, through an opaque ID.
+
+A failed render keeps the previous HTML and resource allowlist.
+
+## Troubleshooting
+
+### Pandoc was not found
+
+Confirm installation:
+
+```bash
+pandoc --version
+```
+
+Or select a binary explicitly:
+
+```bash
+PANDOC_PATH="/custom/path/pandoc" pandoc-glance notes.md
+```
+
+The CLI validates Pandoc before starting and exits nonzero when it is unavailable.
+
+### The browser did not open
+
+Use `--no-open` and open the printed HTML path or URL manually:
+
+```bash
+pandoc-glance --no-open notes.md
+pandoc-glance --watch --no-open notes.md
+```
+
+The CLI uses the operating system default-browser command (`open`, `xdg-open`, or Windows `start`); it does not hard-code a browser.
+
+### A local image is missing
+
+- Check the path relative to the source file, not the shell's current directory.
+- Put paths containing spaces or parentheses in Markdown angle brackets.
+- In watch mode, a relative symlink whose target is outside the document directory is deliberately blocked; use an explicit absolute path if that file should be allowlisted.
+- Save the image and source file. Resource responses are not browser-cached.
+
+### The selected port is busy
+
+Omit `--port` or use `--port 0` to let the operating system choose an available loopback port.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+The test suite uses real Pandoc but does not open a browser or access the public network.
+
+A representative fixture is available at [`test/fixtures/sample.md`](test/fixtures/sample.md), with a standalone LaTeX companion at [`test/fixtures/sample.tex`](test/fixtures/sample.tex).
+
+For a manual headless smoke test:
+
+```bash
+node dist/cli.js --watch --no-open test/fixtures/sample.md
+```
+
+Fetch the printed loopback URL, save an edit to the fixture or a temporary copy, and observe the revision change. Press Ctrl-C to stop it.
+
+## License
+
+MIT. The rendering palettes and selected normalization/browser-preview patterns were adapted from the MIT-licensed [`pi-markdown-preview`](https://github.com/omaclaren/pi-markdown-preview) implementation; see [`LICENSE`](LICENSE).

package/dist/browser.d.ts

@@ -0,0 +1,3 @@
+/** Open a URL with the operating system's configured default browser. */
+export declare function openInDefaultBrowser(url: string): Promise<void>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAEA,yEAAyE;AACzE,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BrE"}

package/dist/browser.js

@@ -0,0 +1,25 @@
+import { spawn } from "node:child_process";
+/** Open a URL with the operating system's configured default browser. */
+export async function openInDefaultBrowser(url) {
+    const command = process.platform === "darwin"
+        ? { executable: "open", args: [url] }
+        : process.platform === "win32"
+            ? { executable: "cmd.exe", args: ["/d", "/s", "/c", "start", "", url] }
+            : { executable: "xdg-open", args: [url] };
+    await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(command.executable, command.args, {
+            stdio: "ignore",
+            detached: true,
+            windowsHide: true,
+        });
+        child.once("error", (error) => {
+            rejectPromise(new Error(`Could not open the default browser with ${command.executable}: ${error.message}. `
+                + "Retry with --no-open and open the printed URL or HTML path manually.", { cause: error }));
+        });
+        child.once("spawn", () => {
+            child.unref();
+            resolvePromise();
+        });
+    });
+}
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,GAAW;IACpD,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAC3C,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE;QACrC,CAAC,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO;YAC5B,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE;YACvE,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;IAE9C,MAAM,IAAI,OAAO,CAAO,CAAC,cAAc,EAAE,aAAa,EAAE,EAAE;QACxD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,EAAE;YACpD,KAAK,EAAE,QAAQ;YACf,QAAQ,EAAE,IAAI;YACd,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC5B,aAAa,CACX,IAAI,KAAK,CACP,2CAA2C,OAAO,CAAC,UAAU,KAAK,KAAK,CAAC,OAAO,IAAI;kBAC/E,sEAAsE,EAC1E,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CACF,CAAC;QACJ,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;YACvB,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,cAAc,EAAE,CAAC;QACnB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { type PreviewFormatOption } from "./render.js";
+import type { PreviewTheme } from "./styles.js";
+export declare const VERSION = "0.1.0";
+export declare const DEFAULT_FONT_SIZE_PX = 15;
+export declare const MIN_FONT_SIZE_PX = 10;
+export declare const MAX_FONT_SIZE_PX = 24;
+export interface CliOptions {
+    action: "run" | "help" | "version";
+    inputPath?: string;
+    watch: boolean;
+    open: boolean;
+    theme: PreviewTheme;
+    format: PreviewFormatOption;
+    fontSizePx: number;
+    port: number;
+}
+export declare class CliArgumentError extends Error {
+    constructor(message: string);
+}
+export declare function parseCliArgs(argv: string[]): CliOptions;
+export declare function helpText(): string;
+export declare function runCli(argv: string[]): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AASA,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,eAAO,MAAM,OAAO,UAAU,CAAC;AAC/B,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAqCD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAyGvD;AAED,wBAAgB,QAAQ,IAAI,MAAM,CAsBjC;AA2ID,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiC5D"}