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.

Setting	Default	Description
Auto-refresh delay (ms)	500	Milliseconds to wait after the last keystroke before re-rendering. Minimum: 100 ms.

.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:

Trigger	Scenario
workspace → editor-change	The same file is open in Obsidian's built-in plain-text editor in another pane
Plugin internal broadcast	The file is open in AsciiDoc Live's Source mode in a split pane
vault → modify	The file was saved to disk (auto-save, Ctrl+S, or external editor)

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.