Skip to content

About

Inline Annotation for Markdown: ruby/furigana, interlinear glosses, bouten, overlines and underlines. Spec, parser, and Obsidian, Logseq, VS Code and markdown-it integrations.

Topics

Resources

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

Inline Annotation for Markdown

Inline Annotation cat icon

npm version Cross-platform downloads: 3.3k+ CI

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: original terms and translations above and below Chinese prose, with per-character phonetic readings and grouped glosses.

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.

About

Inline Annotation for Markdown: ruby/furigana, interlinear glosses, bouten, overlines and underlines. Spec, parser, and Obsidian, Logseq, VS Code and markdown-it integrations.

Topics

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages