npm package: @peaceroad/markdown-imgattr-to-pcaption
Description: Change img alt attribute to figure caption paragraph for p7d-markdown-it-p-captions.
Author: peaceroad
Latest version: 0.6.0

# markdown-imgattr-to-pcaption

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

## Install

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

## Markdown transformer (`index.js`)

### Usage

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

const out = setMarkdownImgAttrToPCaption(markdown)
```

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

### Example

Input:

```md
Paragraph.

![A caption](image.jpg)

Paragraph.
```

Output:

```md
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:

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

Per-language config example:

```js
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

```html
<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`