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)
  • Default label language (en/ja out of the box).
• autoLangDetection (boolean, default: true)
  • Detect language from the first eligible image caption.
  • ja if Japanese characters exist.
  • en if ASCII letters exist and labelLang is still the default en/ja family.
  • Preserves explicit non-en/ja labelLang on ASCII-only text.
  • Otherwise falls back to the current upstream label-default priority.
• 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: ' ' },
  }
})

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 runs once on 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.
• Re-detects language when first-image context changes.
• observe supports tuning by attribute/meta/child-list granularity and optional quiet-period debounce.

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) 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