Skip to content

Future document renderer: Mermaid, LaTeX math, expandable details and heading navigation #462

Open
Open
Future document renderer: Mermaid, LaTeX math, expandable details and heading navigation#462
Labels
needs-human-testRequires human terminal validationstatus:ongoingtype:featureNew feature or improvement

Description

@raiseCatError
raiseCatError
opened on Oct 20, 2026

Status

Deferred research and specification; not v0.22 release scope. Re-evaluate after current Claude work lands. Document rendering must stay safe and lightweight by default, with optional rich browser preview.

Requested features

  • Mermaid fenced diagrams with local rendering where practical, interactive pan/zoom when a graphics backend supports it, and readable fenced-code fallback. Never execute arbitrary scripts from Markdown as an implicit side effect.
  • TeX math (inline $...$, display $$...$$, and fenced math variants) with appropriate KaTeX/MathJax research. KaTeX tends to be faster for static preview; MathJax offers broad TeX coverage; compare versions/features/licensing and avoid mandatory Chromium for basic Markdown. Render formula images via shared graphics backend if available; fallback to readable TeX source. Bound math layout and recursion/CPU.
  • GFM/HTML <details><summary>…</summary>…</details> collapsible disclosure, keyboard and mouse accessible, persistent open state while editing/refreshing as reasonable; all HTML sanitized and inert in native view.
  • GitHub/Jekyll-compatible heading slugs including duplicate-heading disambiguation, #fragment links, /view file.md#anchor where safe, jump-to-heading picker and an optional floating/sticky heading outline or collapsible table-of-contents rail. In a plain terminal this must be an NMSh-owned overlay/dock, not assume real CSS position:sticky. Identify GitHub vs Jekyll differences (explicit {: #id}, frontmatter, Jekyll/Kramdown syntax) and decide compatibility rules; do not claim total Jekyll equivalence.
  • A small render/source toggle that preserves the cursor's underlying source position and scroll anchor. For active editing plain letters must type letters, not act as shortcuts. Integrate with hybrid mode #460 and future split preview.
  • Full Markdown/HTML modes remain available. When Chromium browser-quality preview is explicitly enabled, use safe isolated profiles and disabled JS/network for untrusted local documents unless trusted/opted-in.

Research

  • Edamame README already advertises Mermaid diagrams and LaTeX math; it's not accurate to say those are entirely absent from Edamame. Its editing docs say other HTML (including <details>) displays as literal text instead of rendering. Edamame has heading anchors and Ctrl+G heading picker; a persistent floating outline remains distinct. Apache-2.0, Rust/ratatui; borrow concepts only.
  • Mermaid and mermaid-cli: potentially heavyweight browser-side diagram pipeline, optional lazy backend if useful. Research sandboxing, file access, and image/diagram size limits.
  • KaTeX vs MathJax: research performance, output formats, fonts, security and licensing before choosing. Prefer a small lazy renderer and the shared graphics infrastructure.
  • NMSh src/markdown/{blocks,html,inline,render}.ts currently handles supported markup with sanitized HTML subset; #454 tracks the v0.22 HTML work. Avoid another standalone Markdown parser absent source-position justification. Existing viewer tracking #397, editor umbrella #402.

Acceptance / test plan

  • Heading slugs and duplicate IDs are deterministic; internal navigation/back-history preserves source anchors through edits/resize.
  • Kramdown/Jekyll constructs recognized only to the documented extent. Test malformed/frontmatter/explicit-id examples.
  • Details expand/collapse via keyboard and pointer, without modifying source, executing script or losing edit state.
  • Math/diagrams rendered in supported terminal backend and safe text/source placeholders when unavailable; no silent remote fetching or arbitrary executable scripts.
  • Hover/focus/preview title/controls theme-aware, responsive and keyboard usable; outline non-obstructive at 30/50/80/120 columns.
  • Tests for Unicode math, long diagrams, adversarial Mermaid directives/HTML, CPU and output limits, link schemes, cleanup, NO_COLOR, Safe Glyphs, Ghostty and Zed physical QA.

Non-goals

Not a promise of full browser CSS in ANSI mode; no forced MathJax installation, no automatic network content fetching, no new standalone PTY, no release blocker.

Activity

  1. raiseCatError
    added
    type:featureNew feature or improvement
    status:paused
    status:ongoing
    and removed
    status:paused
    on Oct 20, 2026

  2. raiseCatError commented on Oct 21, 2026

    @raiseCatError
    raiseCatError
    on Oct 21, 2026
    OwnerAuthor

    Resumed for v0.24 (the earlier pause protected the v0.22/v0.23 schedule; the issue text predates v0.23, so scope is reconciled against the current code before implementation). Order and dependencies: docs/development/v024-ledger.md on branch feature/v024-draft-recovery (PR #489).

  3. raiseCatError
    added 7 commits that reference this issue on Oct 21, 2026

    Markdown: heading navigation on the shared source-position map (#462)

    a511b94

    Markdown: heading navigation on the shared source-position map (#462)

    d223b77

    Markdown: heading navigation on the shared source-position map (#462)

    715700d

    Merge pull request #495 from raiseCatError/feature/v024-outline

    c9ef84e

    Merge pull request #500 from raiseCatError/feature/v024-details

    ab9816a

    Merge pull request #501 from raiseCatError/feature/v024-math

    7da8000

    Merge pull request #502 from raiseCatError/feature/v024-mermaid

    47339ff

  4. raiseCatError commented on Oct 22, 2026

    @raiseCatError
    raiseCatError
    on Oct 22, 2026
    OwnerAuthor

    Mermaid diagrams merged into dev (PR #502, merge 47339ff)

    What changed: mermaid fences are drawn as diagrams in Preview (NMSh's renderer and the Chromium preview), in Split's preview pane, in the viewer, and in Hybrid's inactive blocks.

    • Renderer: NMSh uses the Mermaid you installed (npm install -g mermaid or NMSH_MERMAID). It runs inside the existing Chromium in an isolated world, with page scripts off, the network refused, and only PNG pixels coming back. Nothing is downloaded.
    • Setting: Settings → General → Mermaid diagrams. On request (the default) draws after D, or F1 › Diagrams while editing. The other options are Automatic and Off.
    • Design: docs/design/diagrams.md

    Automated verification:

    • Unit and integration tests (tests/diagrams*.test.ts, plus the workspace app and preview tests).
    • Real Chrome with real Mermaid 12.2.0, in CI on macOS and Ubuntu. It covers 17 diagram types and a hostile-input set that sent zero network requests and ran no page script. It also covers timeouts, crashes and open/close cleanup.
    • A PTY smoke run of the built binary: no Chromium before D, the diagram drawn after D, nothing left after exit.
    • An independent review: 4 bugs fixed with regression tests; no security issues.

    Physical QA: NOT RUN. Use Ghostty (Kitty graphics) and Zed (character art). The checklist is in docs/testing/v024-editor-physical-qa.md, section "Mermaid diagrams (#462)". Key things to try:

    1. With Mermaid and Chrome installed, open a .md with flowchart, sequence, class and state fences. Press h, then D. No Chromium should run before D.
    2. Press i on a diagram to zoom and pan, then Esc.
    3. In Hybrid (F3), edit inside a fence and move out of it. In Split (F2), type in a fence.
    4. Try the Automatic and Off settings, a missing Mermaid, the real browser Off, and Images Off.
    5. Check 30/50/80/120 columns, NO_COLOR and Safe Glyphs.

    #462 acceptance status

    • Heading slugs, /view file#anchor, the heading prompt and back (slice 1)
    • <details> from the keyboard (z/Z)
    • Math (offline typesetter) and Mermaid diagrams, each with a source fallback; no remote fetching or document scripts; CPU, output and size limits
    • Following #fragment links inside a rendered document
    • Outline refinements (an optional persistent outline rail)
    • <details> toggling by pointer and in Hybrid
    • A /doctor line for Mermaid (small follow-up)
    • Physical Ghostty and Zed QA for everything above
  5. raiseCatError
    added
    needs-human-testRequires human terminal validation
    on Oct 22, 2026
  6. raiseCatError
    added a commit that references this issue on Oct 22, 2026

    Merge pull request #504 from raiseCatError/feature/v024-browser-console

    be3f6ab

  7. raiseCatError commented on Oct 22, 2026

    @raiseCatError
    raiseCatError
    on Oct 22, 2026
    OwnerAuthor

    /doctor Documents section merged into dev (PR #504, merge be3f6ab). Physical QA: NOT RUN.

    /doctor now shows:

    • the browser that previews would use (its version only if a browser surface already checked it this session, and whether it's running)
    • the Mermaid installation found (path and version, with a warning for a major version other than the tested 12)
    • the Mermaid diagrams setting
    • the reason diagrams would not be drawn, if any

    It launches nothing, doesn't read the Mermaid bundle, labels its result as detection only, and gives up on this section after 3 seconds.

    To test: run /doctor in each of these setups:

    • with Mermaid installed and not installed
    • with NMSH_MERMAID set to a wrong path
    • with Settings → Real browser Off and with Images Off
    • before and after opening a browser preview

    Still open for #462: following #fragment links inside rendered documents, the outline rail, toggling <details> with the pointer and in Hybrid view, and physical QA.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs-human-testRequires human terminal validationstatus:ongoingtype:featureNew feature or improvement

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions