README file from
GithubInline Annotation for Markdown
Downloads across Obsidian, npm, VS Code, and Logseq (2026-11-18 snapshot).
Inline Annotation is a small Markdown extension for ruby/furigana, phonetic guides, interlinear glosses, bouten emphasis dots, overlines, and underlines:
[漢字]^^(かんじ)
[base]^^(over)^_(under)
[重要]^^(..)^_(.~)
It implements the syntax proposed by Baksi Li in Ruby (Furigana) Syntax in Markdown. The original Logseq implementation grew into a shared syntax, reference parser, and integrations for markdown-it, Marked, Obsidian, VS Code, Logseq, and SilverBullet.
Inline Annotation (Ruby) in Obsidian. The Obsidian guide includes Reading-view and Live Preview screenshots.
The specification defines its grammar, escaping, source ranges, and rendering contract; the shared fixtures keep implementations aligned. This is a proposal with working implementations.
Ports and implementations
| Project | Where to get it | Integration |
|---|---|---|
markdown-it-inline-annotation |
npm · guide | Reference parser/model, HTML renderer, and markdown-it plugin |
| Inline Annotation (Ruby) for Obsidian | Community directory · guide | Reading view and Live Preview |
| Inline Annotation for VS Code | Marketplace · guide | Built-in Markdown preview |
logseq-furigana-ruby |
Logseq Marketplace · guide | Logseq renderer, macros, and conversion commands |
marked-inline-annotation |
npm · guide | Inline tokenizer for Marked 18 |
| Inline Annotation for SilverBullet | Preview release · guide | SilverBullet Library Manager, editor preview and HTML rendering |
satteri-inline-annotation |
Local pilot | Two-phase Sätteri adapter; not published to npm |
Install
For markdown-it, install the host parser and adapter:
npm install markdown-it markdown-it-inline-annotation
const MarkdownIt = require("markdown-it");
const { inlineAnnotationPlugin } = require("markdown-it-inline-annotation");
const md = new MarkdownIt().use(inlineAnnotationPlugin);
md.render("[漢字]^^(かんじ)");
For a parser/model and HTML renderer without markdown-it:
npm install markdown-it-inline-annotation
const {
findInlineAnnotationModels,
renderInlineAnnotationsToHtml,
} = require("markdown-it-inline-annotation/core");
const models = findInlineAnnotationModels("[漢字]^^(かんじ)");
const html = renderInlineAnnotationsToHtml("[漢字]^^(かんじ)");
markdown-it is an optional peer dependency. Core-only consumers do not need
to install it. See the package guide for options,
stylesheet imports, CommonJS/ES module exports, and model APIs.
Supported syntax
| Input | Meaning |
|---|---|
[base]^^(ruby) |
Annotation above |
[base]^_(gloss) |
Annotation below |
base^^(ruby) |
Abbreviated single-token base |
[base]^^(over|under) |
Two-slot annotation |
[base]^^(over)^_(under) |
Chained two-slot annotation |
[[護]^^(まも)れ]^_(プロテゴ) |
Nested or overlapping annotation |
[漢字]^^(..) |
Bouten / emphasis dots above |
[base]^_(.-) |
Solid underline |
[base]^_(.~) |
Wavy underline |
[base]^_(.=) |
Double underline |
[title]^^(.-) |
Solid overline |
[artefact]^^((semi-)formal artefact) |
Balanced parentheses inside a gloss |
Space-separated readings can align per character:
[春夏秋冬]^^(はる なつ あき ふゆ)
Annotation parentheses must balance; use \( or \) for standalone literal
parentheses. See the specification for the complete grammar and
compatibility notes, including migration from the earlier first-close rule.
The playground and before/after page are standalone HTML examples. Download or open them locally to try the core.
Design and compatibility
Inline Annotation is meant to be a small cross-editor syntax. Its stable surface is the source syntax, two-slot model, escaping rules, rendering marks, and compatibility fixtures. HTML is the first renderer.
The core parses contiguous source strings and exposes UTF-16 source ranges. Host adapters decide where parsing is allowed and preserve host-owned links, code, and semantic formatting boundaries.
Logseq's highlight parsing can conflict with multiple ^^() expressions in
one block; its macros and conversion commands handle those cases. Obsidian
Reading view sees rendered DOM, while Live Preview works on editor source
ranges. These boundaries are documented in the integration guides and
adapter contract.
For contributors
Use Node.js 24 and npm. All commands run from this directory.
npm ci
npm run build
npm test
npm run check
npm run release:pack
check runs the integration and package suites, including the SilverBullet
delimiter checks. release:pack creates and verifies the npm tarballs, Logseq
ZIP, Obsidian assets, VSIX, and checksums in artifacts/.
It needs zip and unzip, available on macOS and the Linux CI runner.
Run a single integration with npm run test --workspace plugins/logseq, for example.
Build packages/markdown-it first when working directly on a dependent workspace.
SPEC.md, fixtures/, and docs/ are canonical. The parser build copies them into its
ignored publication directory; Logseq reads the canonical fixtures directly.
Release
One version tag checks all integrations, packages them once, and publishes to GitHub, npm, and VS Code Marketplace; Obsidian discovers the matching GitHub release. See the release guide for preparation, verification, and retries.
npm run release:status
This reports total cross-platform downloads, the platform breakdown, stars, and directory handover status. Monthly downloads and installs remain separate; these are activity counters, not unique-user counts.
All integrations now share this monorepo, continuing the original Obsidian repository with its stars, history, plugin IDs, and update channels preserved (migration details).
Further reading: roadmap · design history · adapter contract and future ports.
License
MIT — Baksi Li. See LICENSE.