markdown-imgattr-to-pcaption

Convert image alt / title text into caption paragraphs that work with p7d-markdown-it-p-captions.

Install

npm i @peaceroad/markdown-imgattr-to-pcaption

Markdown transformer (index.js)

Usage

import setMarkdownImgAttrToPCaption from '@peaceroad/markdown-imgattr-to-pcaption'

const out = setMarkdownImgAttrToPCaption(markdown)

• markdown must be a string.
  • Non-string input throws TypeError.

Example

Input:

Paragraph.

![A caption](image.jpg)

Paragraph.

Output:

Paragraph.

Figure. A caption

![](image.jpg)

Paragraph.

Options

• imgAltCaption (boolean, default: true)
  • Use image alt as caption source.
• imgTitleCaption (boolean, default: false)
  • Use image title as caption source.
  • When enabled, imgAltCaption is disabled.
• labelLang (string, default: en)
  • Preferred generated-label language (en/ja out of the box).
• autoLangDetection (boolean, default: true)
  • Resolves generated-label metadata from the first eligible image caption through p-captions.
  • Uses labelLang as the preferred-language tie-break when the caption text is ambiguous.
  • Uses the upstream sentence-boundary and Japanese-text rules rather than a separate local detector.
• labelSet (object|null, default: null)
  • Override generated label / joint / space.
  • Supports single config or per-language map.
• imgAltCaption / imgTitleCaption / autoLangDetection accept boolean values only.
  • Non-boolean values are ignored.

Single config example:

setMarkdownImgAttrToPCaption(markdown, {
  labelSet: { label: '図', joint: '：', space: '　' }
})

Per-language config example:

setMarkdownImgAttrToPCaption(markdown, {
  labelSet: {
    en: { label: 'Figure', joint: '.', space: ' ' },
    ja: { label: '図', joint: '　', space: '' },
    fr: { label: 'Fig', joint: '.', space: ' ' },
  }
})

p-captions 0.25 label resolution

Generated-label language selection now follows p-captions directly. Compared with earlier releases, labelLang is a preferred-language tie-break rather than an ASCII/Japanese override, and Japanese text after an upstream sentence boundary does not change the generated label language. This can intentionally change output when autoLangDetection: true.

Conversion rules

• Converts only single-line image syntax surrounded by blank lines.
• Skips fenced code blocks (backtick fences and tilde fences).
• Skips display math fence blocks using $ markers ($$ ... $$, $$$$ ... $$$$, etc.).
• Uses p7d-markdown-it-p-captions label patterns for label detection.
• autoLangDetection resolves upstream generated-label metadata once from the first eligible image.

Browser DOM helper (script/set-img-figure-caption.js)

Usage

<script type="module">
import setImgFigureCaption from '@peaceroad/markdown-imgattr-to-pcaption/script/set-img-figure-caption.js'

await setImgFigureCaption({
  imgAltCaption: true,
  imgTitleCaption: false,
  observe: true,
})
</script>

Behavior

• Mirrors label/caption decisions from markdown transformer.
• Processes all img elements by default (scope: 'all').
• In observe mode, keeps one observer per document.
• Uses internal source cache for stable reprocessing without extra DOM attributes.
• Pauses observation during helper-driven updates so its own attribute and tree mutations do not schedule redundant passes.
• Discards stale scheduled observer work after observation is disabled or replaced.
• Restores the cached source attribute when switching between alt and title caption modes.
• Discards helper source state after captions are disabled and restored, so a later enable starts from the current DOM.
• Re-detects language when first-image context changes.
• observe supports tuning by attribute/meta/child-list granularity and optional quiet-period debounce.
• If caption modes are later disabled, restores helper-managed captions and source attributes where possible.

Options

Caption and label:

• imgAltCaption (boolean, default: true)
• imgTitleCaption (boolean, default: false)
• labelLang (string, default: en)
• autoLangDetection (boolean, default: true)
• labelSet (object|null, default: null)
• figureClass (string, default: f-img)

Meta + observe:

• readMeta (boolean, default: false)
• observe (boolean, default: false)
• observeAttributes (string[], default: ['alt', 'title'])
  • Select image attributes to watch in observe mode.
  • Supported values: alt, title.
• observeMetaContent (boolean, default: true)
  • When readMeta: true, watch meta[name="markdown-frontmatter"] content changes.
• observeChildList (boolean, default: true)
  • Watch DOM tree changes (childList) in observe mode.
• observeDebounceMs (number, default: 0)
  • Quiet-period debounce for observe reprocessing (0 keeps immediate scheduling behavior).

Scope:

• scope ('all'|'standalone'|'figure-only', default: 'all')
  • all: process every img.
  • standalone: process only standalone images (no significant siblings; empty/whitespace text and comments are ignored) and images already inside figure.
  • figure-only: process only images already inside figure.

Boolean-only option rule:

• imgAltCaption, imgTitleCaption, autoLangDetection, readMeta, observe, observeMetaContent, and observeChildList accept boolean values only.
  • Non-boolean values (including frontmatter values) are ignored.

Limitations

• Only single-line inline image syntax is supported.
  • Supported forms include ![alt](url "title") and ![alt](url (title)).
• Multi-line image link syntax is out of scope.
• Complex alt text patterns that rely on raw ]( are out of scope.
• Indented code blocks (4 spaces or tab) are out of scope.
  • Use fenced code blocks if you need guaranteed skip behavior.
• Some non-inline image styles (for example reference-style edge cases) are out of scope.

Related plugin

If you use markdown-it figure/caption flows, see:

• @peaceroad/markdown-it-figure-with-p-caption

This package does not depend on that figure plugin. Its responsibility remains limited to generating p-captions-compatible Markdown captions from image attributes; chapter/appendix scope analysis and automatic numbering belong to the figure/numbering integrations.