今夜は★カツ★カレーです。
console.log(md.render('今日は甘味処が%%午後%%休みです。')) //今日は甘味処が%%午後%%休みです。
console.log(md.render('昼食は親子丼《おやこどん》です。')) //昼食は親子丼です。
console.log(md.render('詳細は（図A.1）を参照してください。')) //詳細は（図A.1）を参照してください。
console.log(md.render('詳細は **図A.1** を参照してください。')) //詳細は 図A.1 を参照してください。
``` ## Ruby Syntax Ruby conversion is based on: - bare shorthand: `([Han + 0-9A-Za-z._-]+)《reading》` - explicit wrapper shorthand: `base《reading》` (open/close pair required, case-insensitive tag match) Examples: ``` Input: 寿司は職人《しょくにん》の技です。 Output:寿司は職人の技です。
Input: 商品名はRAMEN2025《らーめんにーぜろにーごー》です。 Output:商品名はRAMEN2025です。
``` When the base text has long kanji runs, spaces, or hiragana/katakana, use an explicit `...` boundary for predictable wrapping. The explicit form accepts nonempty plain-text base and reading fields without nested angle markup, raw angle characters, or extra ruby brackets. Bare shorthand keeps the stricter Han/ASCII base grammar: ```md Input: お店の名物鯛茶漬《たいちゃづけ》を紹介します。 Output:お店の名物鯛茶漬を紹介します。
``` Ruby shorthand conversion works in both `html:true` and `html:false`. With `html:false`, HTML-like input is generally escaped, while ruby shorthand and explicit `...` wrappers are still rendered as ruby HTML. Each complete explicit wrapper owns its entire range. If that range contains a nested `` wrapper or other inline markup, its shorthand is left unconverted instead of converting a bare-looking suffix inside the wrapper. With `html:true`, an existing parsed `` wrapper may carry attributes; direct plain-text shorthand is converted inside that wrapper without creating a nested `` element. Attribute-bearing wrappers remain escaped under `html:false`, where only the exact attribute-free shorthand wrapper is the explicit HTML exception. If the wrapper is unclosed (for example `寿司《すし》`), the wrapper text is treated as normal text and only shorthand part is converted. `html:false` example: ```md Input:案内文：寿司《すし》を掲載します。 Output:案内文：寿司を掲載します。
``` ## Figure Reference Syntax `figureReference: true` enables both authoring styles. Use the two mode-specific options when only one style is wanted or when overriding one side of the shorthand: - `figureReferenceAuto`: automatically decorate a recognized label and identifier inside paired ASCII or fullwidth parentheses. The parentheses and surrounding whitespace are preserved. - `figureReferenceManual`: treat an exact recognized reference wrapped in `**...**` or `*...*` as an explicit reference marker. Both use the configured figure-reference tag instead of emitting `` or `` because the wrapper is a presentation hook rather than author emphasis. ```md Input: 詳細は（図1）と（図A.1）を参照してください。 Output:詳細は（図1）と（図A.1）を参照してください。
Input: See (Figure 1-1) and (Figure A). Output:See (Figure 1-1) and (Figure A).
Input: See (Fig. 1), (Fig.A-1), and (Figure.A.1). Output:See (Fig. 1), (Fig.A-1), and (Figure.A.1).
Input: 詳細は（図3、4）と（図A-1、図B-1）を参照してください。 Output:詳細は（図3、4）と（図A-1、図B-1）を参照してください。
Input: See (Figure 3, Figure 4) and (Figs. 5 and 6). Output:See (Figure 3, Figure 4) and (Figs. 5 and 6).
Input: 詳細は（**図1**）と **図A.1** を参照してください。 Output:詳細は（図1）と 図A.1 を参照してください。
Input: See *Figure A* and **Figures 3 and 4**. Output:See Figure A and Figures 3 and 4.
``` Recognized forms: - Parentheses must be a matching `(...)` or `（...）` pair. - Japanese references start with `図` and have no intervening space. - A Japanese reference can list identifiers with `、`; `図` may be omitted or repeated after the separator. This covers `図3、4`, `図3、図4`, and mixed identifiers such as `図A-1、B-1、図C.1`. - English references start with case-sensitive `Figure`, `Figures`, `Fig`, or `Figs`. - `Figure` / `Figures` are followed by either an ASCII dot or one or more spaces, tabs, or fullwidth spaces. - `Fig` / `Figs` are followed by one or more such spaces, or by an ASCII dot with optional spaces after it. This covers `Fig 1`, `Fig.1`, and `Fig. 1`. - Singular English labels can be repeated in a comma/`and` list, such as `Figure 3, Figure 4` or `Fig. 3 and Fig. 4`. The same label form must be used for every item. - Plural `Figures` / `Figs` require at least two identifiers and a final `and`; intermediate identifiers are optional, and lists of three or more may use an Oxford comma. This covers `Figures 3 and 4`, `Figures 3, 4 and 5`, and `Figs. 3, 4, and 5`. - Each identifier component is either one ASCII/fullwidth uppercase letter or one or more ASCII/fullwidth digits. - Components can be joined with ASCII `.` or `-`. Examples include `図1`, `図１`, `図A`, `図Ａ`, `図1.1`, `図A.1`, `図1-1`, `図A-1`, `Figure 1`, `Figure A.1`, `Figure.1`, `Figure.A-1`, and `Figure.A.1`, `Fig 1`, `Fig.1`, `Fig. 1`, and `Fig.A-1`. A recognized list is wrapped as one reference phrase rather than one element per identifier. Lowercase aliases such as `figure` / `fig` and all-uppercase `FIG` are not recognized. Fullwidth separators such as `．`, `－`, `：`, and `，` are intentionally not recognized. English shorthand without a repeated or plural label, such as `Figure 3, 4`, is also left unchanged. Both modes default to ``. Use `figureReferenceTag` to select `span`, `b`, or `i` for both. Set `figureReferenceManualTagFromMarker: true` when manual `**...**` should use `b` and manual `*...*` should use `i` instead. Use `figureReferenceClass` to change the class in both modes. The plugin emits the class hook but does not bundle a stylesheet for it. ```js md.use(mditRendererInlineText, { figureReferenceManual: true, figureReferenceManualTagFromMarker: true, }) // **図1** -> 図1 // *図1* -> 図1 ``` Manual mode accepts only an exact recognized reference inside one asterisk delimiter pair. It intentionally leaves `_図1_`, `***図1***`, `** 図1 **`, and ordinary emphasis such as `**重要**` to markdown-it. It reuses markdown-it's parsed emphasis tokens; if a preset disables the `emphasis` inline rule (for example the unmodified `zero` preset), manual mode has no delimiter tokens to retag and leaves the source unchanged. Inline/fenced code and link destinations are not rewritten. With `html:true`, raw HTML and its attributes are also left unchanged. With `html:false`, HTML-looking source is ordinary text, so a reference inside it can be decorated while markdown-it escapes the tag-like text. An odd backslash run before either opening parenthesis prevents conversion. Markdown-it removes the escaping backslash from `\(Figure 1)`; a backslash before fullwidth `（` remains literal because it is not standard Markdown ASCII punctuation. ### Compatibility with `@peaceroad/markdown-it-figure-with-p-caption` Caption detection runs before this plugin's manual core transform, so plain caption labels such as `図1 Caption` and `Figure 1. Caption` remain owned by the figure plugin. This is stable in either `.use(...)` order. Caption labels generated as ``, ``, or `` by that plugin are not retagged; explicit references in caption body text can still use the manual syntax. Do not use `**図1**` as the leading caption label. The figure plugin does not recognize an emphasis token as a caption label even without this plugin. Use a plain source label and its `bLabel: true` option when the rendered caption label should use ``. The classes intentionally remain role-specific: `f-img-label` identifies a label in a caption, while `f-ref` identifies a reference in body text. When they need the same appearance, group the selectors in CSS (for example, `:where(.f-img-label, .f-ref)`) rather than making the DOM roles share one class name. ## ★ / %% Comment Syntax Both syntaxes are pair-based markers: - Star: `★...★` -> `...` - Percent: `%%...%%` -> `...` (or custom class) Behavior summary (without examples): - Pair matching is per marker type, so `★...★` and `%%...%%` are handled independently. - Escaped markers (odd backslash parity) stay as plain text. - In a backslash run before a marker, each pair produces one literal backslash; an unpaired final backslash escapes the marker. This is consistent for `html: false` and `html: true`. - In default span mode, matched ranges are wrapped and preserved in output. - In delete mode, only the enabled marker type is removed from output. - In inline mode, marker ranges are fixed by preparse before markdown inline formatting. ### Escape Markers ```md Input:料理名は\★限定★ではありません。 Output:料理名は★限定★ではありません。
Input:今日の注記は\%%内輪%%ではありません。 Output:今日の注記は%%内輪%%ではありません。
``` ### Span Element (Default) Basic: ``` Input: 蕎麦は★売り切れ次第終了です。★美味しいです。 Output:蕎麦は★売り切れ次第終了です。★美味しいです。
Input: 喫茶店に%%季節限定の%%パフェがあります。 Output:喫茶店に%%季節限定の%%パフェがあります。
Input: 今日は★**本日のおすすめ**の★ハンバーグを注文します。 Output:今日は★**本日のおすすめ**の★ハンバーグを注文します。
``` In `html:true`, inline HTML inside a marker range is kept as HTML: ```md Input: メニューから★だし香る★うどんを選びます。 Output:メニューから★だし香る★うどんを選びます。
``` Marker priority is high in inline mode (`html:true` / `html:false`): markdown syntax inside marker ranges stays literal. ``` Input: **春★御膳**定★食を案内します。 Output:**春★御膳**定★食を案内します。
``` ### Delete option `starCommentDelete` and `percentCommentDelete` are independent: - `starCommentDelete: true` removes only `★...★` ranges. - `percentCommentDelete: true` removes only `%%...%%` ranges. In paragraph mode, delete removes only the marked paragraph. It does not delete the containing list item or neighboring paragraphs, and adjacent visible paragraphs are emitted without a placeholder blank line. If the marked paragraph is the only content of a list item, the structural empty `` remains. If source inline HTML opens in that paragraph and closes outside it, paragraph deletion fails closed instead of orphaning the external close tag. Non-delete line and paragraph modes wrap the complete parsed inline range, so nested links, emphasis, and code spans remain inside balanced comment markup. If a link, emphasis run, or raw HTML element crosses a line boundary, line mode uses separate wrappers around the visible leaf tokens on the marked line rather than emitting overlapping tags. Line deletion likewise retains only the structural open/close tokens needed by surviving text on adjacent lines. Paragraph decoration uses the same leaf fallback when a raw element is not balanced inside the paragraph. A multiline raw HTML tag or comment held in one `html_inline` token, or an inline construct such as a multiline code span that normalizes away a source newline, is left unchanged in line mode because its individual editor lines cannot be isolated safely. ```js const md = MarkdownIt().use(rendererInlineText, { starComment: true, starCommentDelete: true, percentComment: true, percentCommentDelete: true, }) console.log(md.render('カレーのメインは%%海老%%鶏肉です。')) //カレーのメインは鶏肉です。
console.log(md.render('カレーのメインは★あさり★マトンです。')) //カレーのメインはマトンです。
``` ### Line and Paragraph Mode Line mode example: Options:`{ starComment: true, starCommentLine: true }` ``` Input: 通常案内 ★売り切れ注意 通常案内 Output:通常案内 ★売り切れ注意 通常案内
``` Percent comments follow the same line/paragraph behaviors with `percentCommentLine`, `percentCommentParagraph`, and `percentCommentParagraphClass`. Paragraph mode example: Options:`{ starComment: true, starCommentParagraph: true }` ``` Input: ★本日は売り切れ次第終了です。 Output:★本日は売り切れ次第終了です。
``` Paragraph-only class example: Options:`{ starComment: true, starCommentParagraph: true, starCommentParagraphClass: true }` ``` Input: ★本日は売り切れ次第終了です。 Output:★本日は売り切れ次第終了です。
``` ## Options - `ruby` (default: `false`) Enable ruby conversion. - `figureReference` (default: `false`) Enable both automatic and manual figure-reference conversion. It supplies the default for each mode-specific option. - `figureReferenceAuto` (default: value of `figureReference`) Automatically decorate recognized single or listed `図...`, `Figure...` / `Figures...`, and `Fig...` / `Figs...` references inside paired parentheses. An explicit value overrides `figureReference` for this mode. - `figureReferenceManual` (default: value of `figureReference`) Convert exact single or listed `**reference**` / `*reference*` author markers with the configured reference tag and class. An explicit value overrides `figureReference` for this mode. - `figureReferenceTag` (default: `"span"`) Output tag for automatic and manual references. Allowed values are `"span"`, `"b"`, and `"i"`. - `figureReferenceManualTagFromMarker` (default: `false`) In manual mode, derive the tag from the author marker instead of `figureReferenceTag`: `**reference**` uses `` and `*reference*` uses ``. - `figureReferenceClass` (default: `"f-ref"`) CSS class for automatic and manual references. - `starComment` (default: `false`) Enable `★...★` comments. - `starCommentDelete` (default: `false`) Delete star-comment spans instead of rendering them. - `starCommentParagraph` (default: `false`) Paragraph mode for stars (paragraph starts with `★`). - `starCommentLine` (default: `false`) Line mode for stars (editor line starts with `★`). - `starCommentParagraphClass` (default: `false`) In star paragraph mode, add class to `` and skip inner span wrapping. `true` uses `"star-comment"`, and a string uses that class name. - `percentComment` (default: `false`) Enable `%%...%%` comments. - `percentCommentDelete` (default: `false`) Delete percent-comment spans instead of rendering them. - `percentCommentParagraph` (default: `false`) Paragraph mode for percents (paragraph starts with `%%`). - `percentCommentLine` (default: `false`) Line mode for percents (editor line starts with `%%`). - `percentCommentParagraphClass` (default: `false`) In percent paragraph mode, add class to `
` and skip inner span wrapping. `true` uses `percentClass`, and a string uses that class name. - `percentClass` (default: `"percent-comment"`) CSS class for percent-comment spans. Notes: - If `starCommentLine` is `true`, `starCommentParagraph` is disabled. - If `percentCommentLine` is `true`, `percentCommentParagraph` is disabled. - In paragraph mode, delete takes precedence over `starCommentParagraphClass` / `percentCommentParagraphClass`; a paragraph that cannot be deleted safely is left unchanged rather than falling back to a class. - Line and paragraph modes replace inline pair conversion for the same marker. A matching line or paragraph is wrapped only once, while marker pairs outside that mode's target remain literal. - Star and percent line modes can be enabled together; mixed ★/%% lines are classified independently, including delete mode. - `percentClass` is escaped via `md.utils.escapeHtml`. - `figureReferenceTag` is validated at setup time; token attribute rendering escapes `figureReferenceClass`. - `figureReferenceManualTagFromMarker` affects only the manual output tag; range recognition is unchanged. - `figureReference: true` enables both modes; explicit `figureReferenceAuto` / `figureReferenceManual` values override the shorthand independently. ## Analyzer API (Experimental) You can also import a parserless analyzer API from: ```js import { normalizeOptions, createRuntimePlan, lineStartsWithStar, lineStartsWithPercent, isEscapedStar, isEscapedPercent, normalizeLineWindow, expandToParagraphBoundaries, shouldFullAnalyze, scanInlineRanges, analyzeLines, analyzeLineWindow, } from '@peaceroad/markdown-it-renderer-inline-text/analyzer' ``` This API is intended for editor-side highlighting (for example VSCode) without running markdown-it. Recommended editor workflow: - Use `analyzeLineWindow(...)` for viewport/diff updates. - Expand a changed range with `expandToParagraphBoundaries(...)` (or use `analyzeLineWindow` default expansion). - Paragraph types are resolved from the actual paragraph start even when a requested window or its context starts mid-paragraph. - Use `shouldFullAnalyze(changeCount, totalLines)` to decide when to fallback to full-document `analyzeLines(...)`. - Keep final HTML output on `markdown-it + plugin` (not analyzer output). - Results from `normalizeOptions(...)` and `createRuntimePlan(...)` are frozen. Pass a fresh option object when behavior changes so precedence and `inlineProfileMask` cannot drift after normalization. - Treat `inlineRanges` and `lineModeRange` returned by `analyzeLines(...)` and `analyzeLineWindow(...)` as read-only. Cached range arrays and range objects are frozen so duplicate lines and later incremental analyses cannot be corrupted through shared references. Guaranteed parity scope: - marker escape parity (`★`, `%%`) - inline marker pairing in inline mode (`starInlineEnabled` / `percentInlineEnabled`) - line-start checks (`starCommentLine` / `percentCommentLine`) - ruby shorthand range detection outside inline marker-wrapped ranges - automatic/manual figure-reference range detection outside inline marker-wrapped ranges With `figureReferenceAuto`, matching ranges use `type: "figure-reference"` and cover the full parenthesized source range. With `figureReferenceManual`, they cover the full asterisk-marked range. Rendering wraps only the recognized label and identifier in either mode. Out of scope for strict parity: - full markdown-it token behavior (lists, links, emphasis nesting, fenced blocks) - HTML block/inline token boundary decisions made by markdown-it and other plugins - analyzer parity for source entities that markdown-it decodes before a manual figure-reference or ruby decision - renderer-time wrapper suppression / list-item hiding behavior ## Notes ### Rule Details - Escape parity rule: - Odd number of backslashes before marker: marker is escaped. - Even number: marker can participate in pairing. - In inline mode (`html:true` / `html:false`), one preparse pass selects the earliest valid enabled star, percent, or figure-reference candidate. - Markdown inline syntax inside a marker range is kept literal (for example, `★**bold**★`, ``★`code`★``, `★[link](...)★`). - Ruby conversion runs on text tokens; when marker preparse has already wrapped a range, ruby conversion does not rewrite inside that wrapped marker content. - Figure references emit normal paired inline tokens; figure-only configuration does not install the core conversion rule. ### HTML Boundary Behavior - With `html:true`, conversion targets markdown-it inline `text` tokens. - Raw `html_block` token bodies are not rewritten by this plugin. - HTML attributes are not rewritten. - Raw-text elements are skipped: `script`, `style`, `textarea`, `title`. - Inside literal-priority ★/%% ranges, enabled markdown-it `html_inline` and `entity` rules remain authoritative: valid inline HTML is preserved, character references are decoded as usual, and other `<`, `>`, and `&` characters are escaped. Other Markdown delimiters in the range remain literal. Preserved inline HTML must be structurally self-contained inside the marker pair. If an opening or closing source tag would cross the generated comment boundary, conversion and deletion both fail closed for that pair. - With `html:false`, HTML-like input is treated as text and escaped, but marker/ruby transforms still apply. Explicit `...` wrappers used with ruby shorthand are preserved. Block/inline example: ``` Input:
店内に★売り切れ注意の★張り紙が貼ってあります。