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.
| 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 |
For markdown-it, install the host parser and adapter:
npm install markdown-it markdown-it-inline-annotationconst 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-annotationconst {
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.
| 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.
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.
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:packcheck 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.
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:statusThis 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.
MIT — Baksi Li. See LICENSE.
