Read Markdown in a browser with ak:markdown-novel-viewer

Use ak:markdown-novel-viewer to read a long Markdown file in a focused, book-like browser interface or browse a directory of documents. It starts a Node.js HTTP server, renders Markdown on request, resolves local images, and adds navigation, reading progress, syntax highlighting, and Mermaid diagrams.

Choose ak:markdown-novel-viewer for reading

Use ak:markdown-novel-viewer when

• You want a distraction-free view of an RFC, runbook, design document, report, specification, plan, or long-form manuscript.
• You want to browse a document directory and follow Markdown links visually.
• You want headings, a table of contents, code highlighting, theme and font controls, reading progress, or plan-specific previous and next navigation.
• You want browser-rendered Mermaid blocks and can allow the required CDN request.

Choose another workflow when

• You need a self-contained HTML file rather than a running server. Use the HTML generation mode in ak:preview.
• You need to edit or validate the Markdown content. Use ak:docs or the relevant authoring Skill before previewing it.
• You need a Mermaid source artifact that is validated independently of this viewer. Use ak:mermaidjs-v11.
• The content is untrusted or sensitive and cannot be safely rendered as HTML or exposed through a local HTTP process.

Prepare Node, the source, and browser access

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the current runtime and scope.
• Provide one Markdown file or one directory. Relative paths resolve from the current working directory.
• Make Node.js and the Skill's npm dependencies available. The package declares marked, highlight.js, and gray-matter; without installation, Markdown rendering returns an HTTP 500 error.
• Approve dependency installation separately. Running npm install in the Skill directory writes dependency artifacts and uses the package registry.
• Decide whether the browser may reach Google Fonts, cdnjs, and jsDelivr. The rendered page loads fonts, Highlight.js theme CSS, and Mermaid 11 from those public CDNs.

The declared input is [file-or-directory]. State the path, host, port policy, browser-opening preference, background or foreground lifecycle, network access, and stop behavior when those boundaries matter.

Start a local-only reader

/ak:markdown-novel-viewer ./docs/system-design.md "Serve on localhost, use the first available port from 3456, do not bind to the network, do not open a browser automatically, report the URL and PID state, and stop the server when I finish reviewing."

/ak:markdown-novel-viewer ./docs/system-design.md "Serve on localhost, use the first available port from 3456, do not bind to the network, do not open a browser automatically, report the URL and PID state, and stop the server when I finish reviewing."

$ak:markdown-novel-viewer ./docs/system-design.md "Serve on localhost, use the first available port from 3456, do not bind to the network, do not open a browser automatically, report the URL and PID state, and stop the server when I finish reviewing."

The Skill's documented integration also points to ak:preview for quick access. Use the dedicated viewer invocation when you want its server lifecycle and security boundary to be the explicit subject of the request.

Understand the server controls

For direct script use, run the packaged node scripts/server.cjs entry point from an environment where its dependencies resolve. A successful attached start reports the URL, path, port, host, and file or directory mode. Background, foreground, child, and command-integrated paths emit JSON; a network URL is added when binding to 0.0.0.0 and a local IPv4 address is found.

Observe the reader stages

1. The Skill resolves the input. It checks the current working directory, determines file or directory mode, and rejects a missing or invalid path.
2. It prepares the runtime. Required npm modules must resolve before the first Markdown render.
3. It chooses an available port. The requested port is used when free or the next available port is reported.
4. It starts the HTTP server. Assets, the current working directory, and the target directory become allowed file roots for that process.
5. It renders the document or listing. Markdown frontmatter, headings, local images, code blocks, plan navigation, and directory entries become HTML.
6. The browser loads enhancements. Local reader JavaScript adds theme, font, sidebar, keyboard, mobile, and progress behavior; external CDN resources add fonts, highlight themes, and Mermaid.
7. The run remains active until stopped. PID files support discovery and shutdown; the final report should confirm the process and port are gone.

Read Mermaid blocks and plan documents

Fenced mermaid blocks are escaped on the server, then rendered in the browser with Mermaid 11 from jsDelivr. The diagram follows the light or dark reader theme, can expand to the main content width, and is re-rendered after theme changes. A render failure is shown inline with the source preview.

This is rendering evidence, not a complete validation guarantee. The page must reach the CDN, the browser must execute modules, and the source must be valid for the fetched Mermaid 11 release. The reader initializes Mermaid with securityLevel: 'loose'; do not use untrusted diagram source.

Plan navigation is inferred from recognized plan files and phase tables. When a document is not detected as a plan, it still receives standard headings and a table of contents, but phase badges and previous or next navigation may be absent. Reader preferences and accordion state are stored in browser localStorage.

Keep the HTTP and content boundary controlled

• The Markdown renderer does not add a sanitization layer for raw HTML. Treat Markdown, embedded HTML, links, filenames, and Mermaid source as trusted input before opening the page.
• Directory mode lists non-hidden files of many types and links them through the local file route. Do not serve a broad project directory containing secrets, private reports, source maps, exports, or credentials.
• Local images are resolved relative to the Markdown file and served through the same process. Remote image URLs remain remote and can disclose browser network metadata to their hosts.
• The reader contacts public font and script or stylesheet CDNs unless the browser blocks them. Offline reading can lose fonts, highlight themes, and Mermaid rendering even when plain Markdown still loads.
• Browser launch uses the operating system opener. Keep --no-open when the session should only report a URL or when opening a UI is not authorized.
• Stopping by --stop targets every discovered viewer PID. Inspect active instances first if other users or tasks may have a reader running.

Verify the live output

A complete result should include:

• Resolved source path, file or directory mode, bind host, actual port, local URL, optional network URL, process mode, and PID-file state.
• Confirmation that dependencies resolved and whether installation changed the Skill directory.
• HTTP results for the target page and local assets, plus browser confirmation for headings, tables, code, images, navigation, theme, keyboard, and mobile behavior requested by the user.
• Mermaid source and render status for every diagram, with CDN or syntax errors kept distinct from server-rendering failures.
• Network requests made to fonts or CDNs, and the exact directories available through browse or file routes.
• Shutdown evidence showing the server process ended, the port closed, and stale PID files were handled.

The package contains unit-style and server helpers for ports, PID state, MIME types, path checks, Markdown image resolution, headings, tables of contents, and plan navigation. Those tests were not executed for this documentation batch. The pinned stable and beta releases contain the same viewer files.

Troubleshoot and interpret limits

Use ak:preview for a broader preview workflow or ak:mermaidjs-v11 to author and validate diagram source.