Markdown viewer

Markdown viewer

Read local Markdown files in track's reading view without adding them to a vault. The viewer uses the workspace's typography, theme, and reading settings, but the selected files remain a separate, read-only source. Browser-selected files stay in browser memory. The optional Neovim/CLI handoff briefly transfers a snapshot through your local workspace. Neither method imports or indexes the files, and the viewer cannot edit them.

Open a file or folder

1. Start the live Web workspace with track web and open the address it prints.
2. Choose Markdown viewer in the navigation rail, or open /markdown on that workspace.
3. Choose Open Markdown files for one or more .md or .markdown files, or Open folder for a directory containing Markdown and its local images.
4. Use the file selector to switch between the selected Markdown files. The viewer prefers a README.md or README.markdown nearest the selected root; otherwise it opens the first Markdown file in sorted order.

Folder selection includes files in its subfolders and preserves their relative paths. Choose a folder when a README links to nested documentation or images. Picking individual Markdown files does not give the viewer access to the rest of their directory.

This viewer is available in the live workspace, not the published static help site. Source selection accepts local files and folders, not remote URLs.

Open the current file from Neovim

Save your Markdown buffer, then run:

:Track markdown

Track starts the local workspace when needed, or reuses a compatible server at the plugin's web_addr (default 127.0.0.1:8765), and opens the current file directly in this viewer. You do not need to pick it again. The CLI bundled with the plugin and the running workspace must both support this command; update Track if an older workspace is already using the address.

Unnamed, unreadable, special and modified buffers are refused with a message. Track never saves your buffer automatically. After saving another edit, run :Track markdown again to refresh. The server started by Neovim stops when Neovim exits; a reused server keeps its existing lifetime. To stop it explicitly, use :Track webStop; see Start, stop, and update the server before restarting after an update.

The containing folder is the source: supported sibling Markdown files and images, including those in subfolders, are included so relative links and images work. The current file opens first, even when that folder contains a README. Links above this folder are outside the source. Hidden directories, node_modules, vendor and symlinks inside the folder are excluded. Keep related documents in a small documentation folder; all supported sibling files are transferred, not only files directly linked by the current document.

The editor handoff reads saved disk contents and sends them only to the loopback workspace. It never gives the HTTP API a filesystem path to open. The pending snapshot expires after one minute and can be opened only once; after opening, the files remain in browser memory until closed or reloaded. If the handoff expires, run the command again. The folder snapshot is limited to 16 MiB in total and 5,000 visited entries, in addition to the per-file limits below.

From a shell, start track web first, then run:

track markdown -- "./docs/日本語 guide.md"
track markdown --addr 127.0.0.1:8765 -- "./docs/README.md"

The CLI prints JSON containing a one-use url; open that address in your browser. Quote paths containing spaces. Use -- before the filename so a leading - is treated as part of the name. track markdown --check probes for a compatible server without reading any files. The CLI does not start a server or open a browser itself.

Follow local links

Ordinary Markdown links can open another selected Markdown file. Heading links work both within the current file and across selected files:

[Setup on this page](#setup)
[Installation guide](docs/install.md)
[Install requirements](docs/install.md#requirements)
![Overview](images/overview.png)

For that example, select the containing folder with this layout:

project/
  README.md
  docs/
    install.md
  images/
    overview.png

The #setup link targets ## Setup in the current file; #requirements targets ## Requirements in docs/install.md. Relative paths are resolved from the Markdown file that contains the link. They can only reach files in your selection: a link cannot grant access to a neighboring folder, an unselected file, or a vault note. Choose a larger containing folder if the documents need shared files outside the folder you initially selected.

Local PNG, JPEG, GIF, and WebP images are displayed only when their files are included in the selected source. Remote images and rich embeds are not fetched automatically. An explicit click on an ordinary HTTP or HTTPS link opens that external destination normally; it does not load it as a viewer source.

What renders

• Standard Markdown, GFM tables, read-only task lists, syntax-highlighted code, and math use the normal reading styles.
• Raw HTML is not rendered. HTML cannot introduce scripts, frames, or remote resources.
• Vault wiki links, includes, queries, and task-update controls are inactive. Their source remains plain text or code rather than resolving against your vault.
• Diagram and data fences, including Mermaid and track query blocks, stay as inert code. The viewer does not execute code or activate the vault's diagram, chart, or dashboard features.

The viewer deliberately renders a smaller set than a trusted vault note. See Syntax for the normal note syntax and Embeds for features that apply to vault notes instead.

Refresh or close a source

The viewer reads a snapshot of the files you choose. After editing a file on disk, use Open Markdown files or Open folder again to read the updated contents. There is no automatic disk watching or write-back.

Normal navigation to a vault note and browser Back keep the selection during the current page session. A full page reload forgets the selection, so choose the files or folder again. The /markdown address alone cannot restore local files or share them with someone else.

Choose Close source to forget the current selection immediately. This does not delete or change any file on disk.

Limits and troubleshooting

• Each Markdown file may be at most 2 MiB; each supported raster image may be at most 10 MiB. Reduce an oversized file before selecting it again.
• Markdown must be valid UTF-8. If the viewer reports an encoding error, save a UTF-8 copy in your editor and select it again.
• A selection may contain at most 5,000 files, including unsupported files in a selected folder. For a large repository, choose its documentation folder instead of the whole repository.
• Each selected source can load at most 128 images totaling 32 MiB. If later images become unavailable, choose a smaller source.
• If a folder contains no supported Markdown files, choose a folder containing .md or .markdown files instead.
• If a local link or image is unavailable, check its relative path and make sure its target is in the selected source. The viewer cannot fall back to reading arbitrary disk paths or the vault.
• SVG, HTML, PDFs, videos, and other rich embeds are not supported local images.
• Folder selection depends on the browser. If it is unavailable, use Open Markdown files; use a browser with folder selection for nested documentation and images. File and folder choosers in the macOS app's embedded browser have not yet been verified.

Return to Web workspace for vault reading, search, and editing.