User Guide

Installation

Chrome Web Store

Coming soon. AsciiMark will be available on the Chrome Web Store in a future release.

Manual Installation

1. Clone the repository:

   git clone https://github.com/djalmajr/asciimark.git
   cd asciimark

2. Install dependencies:

   bun install

3. Build the extension:

   bun run build

4. Open chrome://extensions in your browser
5. Enable Developer mode (toggle in the top-right corner)
6. Click Load unpacked and select the dist/ folder from the cloned repository

Opening Files

There are several ways to open documents in AsciiMark:

Open Folder

Click the Open Folder button in the sidebar to select a directory from your filesystem. AsciiMark will display all .adoc and .md files in a navigable file tree.

Drag & Drop

Drag and drop folders or individual files directly onto the AsciiMark window. Dropping a folder populates the file tree; dropping a file opens it immediately for preview.

Extension Mode

When you navigate to a URL ending in .adoc or .md, AsciiMark automatically detects the file and renders it as formatted HTML. This works with remote URLs served over https://.

File URL Access

To render local files opened via file:// URLs:

1. Go to chrome://extensions
2. Find AsciiMark and click Details
3. Enable Allow access to file URLs

With this enabled, opening a local .adoc or .md file in Chrome will automatically render it through AsciiMark.

Navigation

File Tree Sidebar

The sidebar displays all supported files in the opened directory as a collapsible tree. Click any file to open it in the preview pane.

Hash-Based SPA Routing

AsciiMark uses hash-based routing (e.g., #path/to/file.adoc) to track the currently viewed file. This enables browser history navigation and bookmarkable document URLs.

Cross-Reference Links

Cross-reference (xref) links in AsciiDoc documents are resolved and navigable. Clicking an xref link opens the referenced document within AsciiMark.

Back & Forward Navigation

Use the browser's back and forward buttons to navigate between previously viewed documents, just like browsing web pages.

Breadcrumb Trail

A breadcrumb trail at the top of the preview shows the current file path, allowing quick navigation to parent directories.

Table of Contents

Collapsible TOC Sidebar

A table of contents panel displays all headings in the current document. The TOC can be toggled open or closed to save screen space.

Auto-Generated from Headings

The TOC is automatically generated from the document's heading hierarchy. No manual configuration is needed.

Scroll-Based Active Heading

As you scroll through a document, the TOC highlights the currently visible section, making it easy to track your position in long documents.

Search

Search in File Tree

Type in the file tree search box to filter files by name. The tree updates in real time, showing only files matching your query.

Search in Preview

Press Ctrl+F to open a search overlay within the document preview. Matching terms are highlighted, and you can navigate between results using the overlay controls.

Editor

Inline Editor (Split View)

Toggle the inline editor to get a side-by-side split view with the source on the left and the rendered preview on the right. The editor is powered by CodeMirror with syntax highlighting for Markdown.

Save Changes

Press Ctrl+S to save your edits directly to disk. This uses the File System Access API, so changes are written back to the original file without any download dialogs.

Appearance

Theme

Choose between three theme options:

• Light — A clean light interface
• Dark — A dark interface that reduces eye strain
• System — Automatically matches your operating system's color scheme

Code Syntax Theme

Select from multiple syntax highlighting themes for code blocks. The theme applies to all fenced code blocks in your documents.

Font Size & Family

Adjust the font size and font family for the document preview from the settings panel to suit your reading preference.

Document Processing

AsciiDoc Rendering

AsciiDoc files are rendered using @asciidoctor/core, providing full support for AsciiDoc syntax including admonitions, tables, source blocks, cross-references, and more.

Markdown Rendering

Markdown files are rendered using markdown-it with 14 plugins, including support for:

• Tables, footnotes, and definition lists
• Task lists (checkboxes)
• Abbreviations and subscript/superscript
• Custom containers and attributes
• Anchor links and table of contents generation

Recursive Include Resolution

AsciiDoc include:: directives are resolved recursively, allowing you to preview documents that are composed from multiple files.

KaTeX Math Expressions

Inline and block math expressions are rendered using KaTeX. Use $...$ for inline math and $$...$$ for display math in Markdown, or the standard STEM syntax in AsciiDoc.

Diagrams

Mermaid Diagrams

Fenced code blocks with the mermaid language tag are rendered as interactive diagrams directly in the browser. Supports flowcharts, sequence diagrams, Gantt charts, class diagrams, and more. No external service is needed.

Kroki Diagrams

For diagram types not covered by Mermaid, AsciiMark supports Kroki for rendering PlantUML, Ditaa, Graphviz, and many other diagram formats. Kroki diagrams are rendered by sending the diagram source to the Kroki service.

Export

PDF Export via Browser Print

Press Ctrl+P to open the browser's print dialog with print-optimized styling. From there you can save the document as a PDF using your browser's built-in "Save as PDF" option.

Direct PDF Download

Use the PDF download button for a direct export powered by html2pdf.js. This generates a PDF file and triggers a download without opening the print dialog.

Keyboard Shortcuts

On macOS, use Cmd instead of Ctrl.