AsciiDoc Live

AsciiDoc Live renders .adoc files natively with a live-updating preview that refreshes automatically while you type — no manual reload required.

AsciiDoc Live bundles Asciidoctor.js directly and handles .adoc, .asciidoc, and .asc files out of the box.

The problem this solves

Other AsciiDoc tools render the file on open but do not update the preview while you edit. You have to manually trigger a reload every time you change something. Markdown files in Obsidian don't have this limitation — AsciiDoc Live brings the same behaviour to AsciiDoc.

Features

• Renders .adoc / .asciidoc / .asc files with full AsciiDoc support: headings, tables, admonitions, code blocks, images, TOC, footnotes, callout lists, and more
• Live preview — automatically re-renders while you type, with a configurable debounce delay
• Three auto-refresh triggers work simultaneously:
  1. Editing in AsciiDoc Live's own Source mode (textarea in a split pane)
  2. Editing the file in Obsidian's built-in plain-text editor in another pane
  3. Any external modification detected by the vault (auto-save, external editor)
• Editor toolbar — formatting shortcuts visible only in Source mode (see below)
• Image paste from clipboard — Ctrl+V in Source mode saves the image to the vault and inserts the correct image::filename[] syntax automatically
• Math formulas — [latexmath] and [asciimath] / [stem] macros rendered via Obsidian's built-in MathJax engine; AsciiMath is converted to TeX automatically using a bundled converter — no external plugins or internet connection required.

[!IMPORTANT] In the current version, only multiline [stem]/[asciimath] blocks and multiline [latexmath] blocks are supported

• xref and cross-reference link resolution — xref: links and <<File#anchor>> cross-references open the target .adoc file in a new tab; in-page anchors (<<anchor>>) scroll smoothly within the preview
• Cross-document anchor navigation — xref:File.adoc#section[text] opens the target file in a new tab and scrolls to the named anchor
• Internal link handling — all clicks in the preview are intercepted: external URLs open in the system browser, in-page anchors scroll smoothly, cross-file links open in Obsidian
• Image paths resolved to vault resources automatically; respects Obsidian's attachment folder settings
• Table styling follows the AsciiDoc frame= and grid= attributes — [frame=none, grid=none] fully removes borders
• Admonition blocks (NOTE / TIP / WARNING / CAUTION / IMPORTANT) rendered as cards with a coloured header
• Styles adapt to the active Obsidian theme via CSS variables

Installation

Disable other AsciiDoc plugins first

AsciiDoc Live registers the .adoc, .asciidoc, and .asc extensions. If another AsciiDoc-render plugin is active at the same time, there will probably be a conflict. Disable any other AsciiDoc plugin before enabling AsciiDoc Live.

Manual installation

1. Download main.js, manifest.json, and styles.css from the latest release
2. Copy all three files into .obsidian/plugins/asciidoc-live/ inside your vault
3. Reload Obsidian and enable the plugin under Settings → Community plugins

Usage

Create or open any .adoc file — it opens in Preview mode by default.

Split-pane live editing

1. Open a .adoc file → it shows the rendered preview
2. Right-click the tab → Split right (or use the command palette)
3. In one pane, click the book icon to switch to Source mode
4. Type in the Source pane — the Preview pane updates automatically

New AsciiDoc note

• Right-click any file or folder in the file explorer → New .adoc note
• Or open the Command Palette (Ctrl+P) → AsciiDoc Live: New AsciiDoc note

The new file opens immediately and is created in the same folder as the selected item.

Pasting images

• Ctrl+V with an image in the clipboard — AsciiDoc Live detects the image, saves it to the vault (using Obsidian's configured attachment folder), and inserts image::Pasted image YYYYMMDD_HHmmss.png[] at the cursor. No extra steps required.
• Img toolbar button — same behaviour when the clipboard contains an image; inserts a placeholder template otherwise.

Cross-references and anchors

// Define an anchor on a heading or block
[#my-section]
== My Section

// Link to it within the same document
<<my-section>>

// Link to it from another document (opens in a new tab and scrolls to the section)
xref:OtherFile.adoc#my-section[Go to My Section]

// Alternative cross-reference syntax
<<OtherFile.adoc#my-section,Go to My Section>>

All three forms work. External .html paths generated by Asciidoctor are automatically rewritten to .adoc before the lookup.

Math formulas

AsciiDoc Live renders math self-contained — no external plugins or internet required. LaTeX is rendered via Obsidian's built-in MathJax; AsciiMath is automatically converted to TeX by a bundled converter.

Currently, the application supports only multiline stem blocks and multiline latexmath blocks.

Supported syntaxes follow AsciiDoc stem documentation:

// latexmath block 
[latexmath]
++++
\lim_{n \to \infty}\frac{n}{\sqrt[n]{n!}} = {\large e}
++++

// asciimath block 
[asciimath]
++++
x = (-b +- sqrt(b^2 - 4ac)) / (2a)
++++

// stem block (defaults to asciimath)
[stem]
++++
\begin{equation}
c = \sqrt{a^2 + b^2}
\end{equation}
++++

Settings

Open Settings → AsciiDoc Live.

.adoc files always open in Preview mode.

How the live refresh works

When a Preview pane is open, it listens to three independent triggers simultaneously:

All three routes feed into the same renderPreview() function, which runs Asciidoctor.convert() on the latest content and injects the HTML into the preview pane.

Repository structure

asciidoc-live/
├── main.ts               # Plugin source (TypeScript)
│                           ├─ AdocView       — TextFileView subclass
│                           │                    renderer · source editor · toolbar
│                           │                    link handler · image paste · anchor nav
│                           ├─ AdocPlugin     — Plugin entry point, shared Asciidoctor
│                           │                    processor, pending-anchor registry
│                           └─ AdocSettingTab — Settings UI
├── main.js               # Compiled & bundled output — committed for distribution
├── manifest.json         # Obsidian plugin metadata
├── versions.json         # Maps each release version to its minimum Obsidian version
├── styles.css            # View container, toolbar, source editor, and preview styles
│                           (admonition cards, frame/grid-aware table borders, theme vars)
├── esbuild.config.mjs    # esbuild bundler configuration
├── tsconfig.json         # TypeScript compiler options
├── package.json          # npm project config; includes @asciidoctor/core as a dependency
├── version-bump.mjs      # Syncs version across manifest.json and versions.json on npm version
└── LICENSE               # MIT License

Development

Requirements: Node.js ≥ 18, npm

# Install dependencies (includes @asciidoctor/core, ~1.6 MB bundle)
npm install

# Watch mode — rebuilds on every save
npm run dev

# Production build — type-check then bundle
npm run build

# Bump version (updates package.json, manifest.json, versions.json)
npm version patch   # or: minor / major

To test locally, copy main.js, manifest.json, and styles.css into .obsidian/plugins/asciidoc-live/ in your Obsidian vault, then reload Obsidian.

[!NOTE] The production bundle is ~1.6 MB because Asciidoctor.js is included in full. This is expected for any AsciiDoc renderer plugin.