@peaceroad/markdown-it-figure-with-p-caption 0.19.0 → 0.20.0

package/docs/examples.md

@@ -0,0 +1,571 @@
+# Complete conversion and option examples
+
+This document contains the exhaustive input/output and option examples for
+`@peaceroad/markdown-it-figure-with-p-caption`. For installation and
+representative examples, start with the [project README](../README.md). For
+behavioral contracts, see the [behavior and options reference](reference.md).
+Numbering-specific examples and contracts are documented in
+[Automatic numbering and integration API](numbering.md).
+
+Complete pairs whose fence info includes `{test id="..."}` are rendered and
+compared exactly by `npm run test:docs`. A Markdown fence may also select one
+of the test runner's fixed, non-evaluated `setup` names. Abbreviated examples
+containing `...` remain illustrative and intentionally omit the test metadata.
+
+## Contents
+
+- [Conversion examples](#conversion-examples)
+  - [Default before/after caption detection](#default-beforeafter-caption-paragraph-detection)
+  - [Auto alt/title detection](#auto-alttitle-detection)
+  - [Multiple images](#multiple-images)
+- [Option examples](#option-examples)
+  - [Styles](#styles)
+  - [Automatic detection fallbacks](#automatic-detection-fallbacks)
+  - [Role helpers](#role-helpers)
+  - [Captionless conversion toggles](#captionless-conversion-toggles)
+    - [Current social embed structures](#current-social-embed-structures)
+  - [Iframe-type blockquote class override](#iframe-type-blockquote-class-override)
+  - [All iframe/embed class override](#all-iframeembed-class-override)
+  - [Caption markers](#caption-markers)
+
+## Conversion Examples
+
+### Default before/after caption paragraph detection
+
+~~~
+[Markdown]
+![A single cat](figure.jpg)
+
+[HTML]
+<p><img src="figure.jpg" alt="A single cat"></p>
+
+<!-- Above: If imageOnlyParagraphWithoutCaption (or its legacy alias oneImageWithoutCaption) is true, this img element has wrapped into figure element without caption. -->
+
+
+[Markdown]
+Figure. A Caption.
+
+![A single cat](figure.jpg)
+[HTML]
+<figure class="f-img">
+<figcaption><span class="f-img-label">Figure<span class="f-img-label-joint">.</span></span> A Caption.</figcaption>
+<img src="figure.jpg" alt="A single cat">
+</figure>
+
+
+[Markdown]
+![A single cat](figure.jpg)
+
+Figure. A Caption.
+[HTML]
+<figure class="f-img">
+<img src="figure.jpg" alt="A single cat">
+<figcaption><span class="f-img-label">Figure<span class="f-img-label-joint">.</span></span> A Caption.</figcaption>
+</figure>
+
+
+[Markdown]
+Table. A Caption.
+
+| Tokyo | Osaka |
+| ----- | ----- |
+| Sushi | Takoyaki |
+
+[HTML]
+<figure class="f-table">
+<figcaption><span class="f-table-label">Table<span class="f-table-label-joint">.</span></span> A Caption.</figcaption>
+<table>
+<thead>
+<tr>
+<th>Tokyo</th>
+<th>Osaka</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Sushi</td>
+<td>Takoyaki</td>
+</tr>
+</tbody>
+</table>
+</figure>
+
+
+[Markdown]
+Code. A Caption.
+
+```js
+console.log('Hello World!');
+```
+
+[HTML]
+<figure class="f-pre-code">
+<figcaption><span class="f-pre-code-label">Code<span class="f-pre-code-label-joint">.</span></span> A Caption.</figcaption>
+<pre><code class="language-js">console.log('Hello World!');
+</code></pre>
+</figure>
+
+<!-- Above: class attribute of code element is generated by markdown-it option. -->
+
+
+[Markdown]
+Source. A Caption.
+
+> A quoted paragraph.
+
+[HTML]
+<figure class="f-blockquote">
+<figcaption><span class="f-blockquote-label">Source<span class="f-blockquote-label-joint">.</span></span> A Caption.</figcaption>
+<blockquote>
+<p>A quoted paragraph.</p>
+</blockquote>
+</figure>
+
+
+[Markdown]
+Terminal. A Caption.
+
+```samp
+$ pwd
+/home/user
+```
+
+[HTML]
+<figure class="f-pre-samp">
+<figcaption><span class="f-pre-samp-label">Terminal<span class="f-pre-samp-label-joint">.</span></span> A Caption.</figcaption>
+<pre><samp>$ pwd
+/home/user
+</samp></pre>
+</figure>
+
+<!-- Above: When @peaceroad/markdown-it-renderer-fence is used, a samp element is generated automatically for `samp` fences. -->
+
+[Markdown]
+Video. An MP4 video.
+
+<video controls width="400" height="300">
+<source src="example.mp4" type="video/mp4">
+</video>
+
+[HTML]
+<figure class="f-video">
+<figcaption><span class="f-video-label">Video<span class="f-video-label-joint">.</span></span> An MP4 video.</figcaption>
+<video controls width="400" height="300">
+<source src="example.mp4" type="video/mp4">
+</video>
+</figure>
+
+
+[Markdown]
+Audio. A narration.
+
+<audio controls>
+<source src="example.mp3" type="audio/mpeg">
+</audio>
+
+[HTML]
+<figure class="f-audio">
+<figcaption><span class="f-audio-label">Audio<span class="f-audio-label-joint">.</span></span> A narration.</figcaption>
+<audio controls>
+<source src="example.mp3" type="audio/mpeg">
+</audio>
+</figure>
+
+
+[Markdown]
+Video. A YouTube video.
+
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/XXXXXXXXXXX" ...></iframe>
+
+[HTML]
+<figure class="f-video">
+<figcaption><span class="f-video-label">Video<span class="f-video-label-joint">.</span></span> A YouTube video.</figcaption>
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/XXXXXXXXXXX" ...></iframe>
+</figure>
+
+
+[Markdown]
+Figure. Mastodon post.
+
+<blockquote class="mastodon-embed" ...> ...... </blockquote><script async src="https://example.com/embed.js"></script>
+
+[HTML]
+<figure class="f-img">
+<figcaption><span class="f-img-label">Figure<span class="f-img-label-joint">.</span></span> Mastodon post.</figcaption>
+<blockquote class="mastodon-embed" ...> ...... </blockquote><script async src="https://example.com/embed.js"></script>
+</figure>
+
+
+[Markdown]
+Quote. Mastodon post.
+
+<blockquote class="mastodon-embed" ...> ...... </blockquote><script async src="https://example.com/embed.js"></script>
+
+[HTML]
+<figure class="f-img">
+<figcaption><span class="f-blockquote-label">Quote<span class="f-blockquote-label-joint">.</span></span> Mastodon post.</figcaption>
+<blockquote class="mastodon-embed" ...> ...... </blockquote><script async src="https://example.com/embed.js"></script>
+</figure>
+
+
+[Markdown]
+Slide. A Speaker Deck.
+
+<iframe src="https://speakerdeck.com/player/XXXXXXXXXXX" width="640" height="360" frameborder="0" allowfullscreen></iframe>
+
+[HTML]
+<figure class="f-slide">
+<figcaption><span class="f-slide-label">Slide<span class="f-slide-label-joint">.</span></span> A Speaker Deck.</figcaption>
+<iframe src="https://speakerdeck.com/player/XXXXXXXXXXX" width="640" height="360" frameborder="0" allowfullscreen></iframe>
+</figure>
+~~~
+
+### Auto alt/title detection
+
+The consumed `alt` or `title` value is cleared only after the image paragraph is confirmed to be wrappable. Tight-list images and image paragraphs with trailing non-image text keep their original accessibility attributes and baseline rendering.
+
+```md {test id="docs-auto-caption-alt"}
+![Figure. A cat.](cat.jpg)
+```
+
+```html {test id="docs-auto-caption-alt"}
+<figure class="f-img">
+<figcaption><span class="f-img-label">Figure<span class="f-img-label-joint">.</span></span> A cat.</figcaption>
+<img src="cat.jpg" alt="">
+</figure>
+```
+
+```md {test id="docs-auto-caption-title"}
+![A white cat eats fish.](cat.jpg "Figure. A cat.")
+```
+
+```html {test id="docs-auto-caption-title"}
+<figure class="f-img">
+<figcaption><span class="f-img-label">Figure<span class="f-img-label-joint">.</span></span> A cat.</figcaption>
+<img src="cat.jpg" alt="A white cat eats fish.">
+</figure>
+```
+
+### Multiple images
+
+```md {test id="docs-multiple-images-horizontal"}
+A paragraph. multipleImages: true. horizontal images only.
+
+![Sitting cat](cat1.jpg) ![Standing cat](cat2.jpg)
+
+Figure. Cats.
+
+A paragraph.
+```
+
+```html {test id="docs-multiple-images-horizontal"}
+<p>A paragraph. multipleImages: true. horizontal images only.</p>
+<figure class="f-img-horizontal">
+<img src="cat1.jpg" alt="Sitting cat"><img src="cat2.jpg" alt="Standing cat">
+<figcaption><span class="f-img-label">Figure<span class="f-img-label-joint">.</span></span> Cats.</figcaption>
+</figure>
+<p>A paragraph.</p>
+```
+
+```md {test id="docs-multiple-images-vertical"}
+A paragraph. multipleImages: true. vertical images only.
+
+Figure. Cats.
+
+![Sitting cat](cat1.jpg)
+![Standing cat](cat2.jpg)
+
+A paragraph.
+```
+
+```html {test id="docs-multiple-images-vertical"}
+<p>A paragraph. multipleImages: true. vertical images only.</p>
+<figure class="f-img-vertical">
+<figcaption><span class="f-img-label">Figure<span class="f-img-label-joint">.</span></span> Cats.</figcaption>
+<img src="cat1.jpg" alt="Sitting cat">
+<img src="cat2.jpg" alt="Standing cat">
+</figure>
+<p>A paragraph.</p>
+```
+
+```md {test id="docs-multiple-images-mixed"}
+A paragraph. multipleImages: true.
+
+Figure. Cats.
+
+![Sitting cat](cat1.jpg) ![Standing cat](cat2.jpg)
+![Sleeping cat](cat3.jpg)
+
+A paragraph.
+```
+
+```html {test id="docs-multiple-images-mixed"}
+<p>A paragraph. multipleImages: true.</p>
+<figure class="f-img-multiple">
+<figcaption><span class="f-img-label">Figure<span class="f-img-label-joint">.</span></span> Cats.</figcaption>
+<img src="cat1.jpg" alt="Sitting cat"><img src="cat2.jpg" alt="Standing cat">
+<img src="cat3.jpg" alt="Sleeping cat">
+</figure>
+<p>A paragraph.</p>
+```
+
+## Option Examples
+
+### Styles
+
+This example uses `classPrefix: 'custom'` and leaves `styleProcess: true` so a trailing `{.notice}` block moves onto the `<figure>` wrapper. This fallback only handles the final trailing attrs block on an image-only paragraph; it supports quoted values with spaces, but for broader attrs syntax support, keep using `markdown-it-attrs`.
+
+```md {test id="docs-custom-style" setup="custom-style"}
+Figure. Highlighted cat.
+
+![Highlighted cat](cat.jpg) {.notice}
+```
+
+```html {test id="docs-custom-style"}
+<figure class="custom-img notice">
+<figcaption><span class="custom-img-label">Figure<span class="custom-img-label-joint">.</span></span> Highlighted cat.</figcaption>
+<img src="cat.jpg" alt="Highlighted cat">
+</figure>
+```
+
+### Automatic detection fallbacks
+
+`autoCaptionDetection` combined with `autoAltCaption` / `autoTitleCaption` can still generate caption text even when the original alt/title lacks labels, as long as the alt/title body is non-empty. The corresponding attributes are cleared after conversion so the figcaption becomes the canonical source. When these fallbacks are `true`, the generated label text and punctuation come from `p7d-markdown-it-p-captions` locale metadata rather than a local hardcoded map. When these fallbacks are strings, the string must be a label stem recognized as an image caption label by `p7d-markdown-it-p-captions`; invalid strings fail during plugin setup instead of producing a stray paragraph.
+
+The first example assumes `autoAltCaption: true`; the second assumes
+`autoTitleCaption: true`.
+
+```md {test id="docs-auto-alt-fallback" setup="auto-alt"}
+![Alt fallback example](bird.jpg)
+```
+
+```html {test id="docs-auto-alt-fallback"}
+<figure class="f-img">
+<figcaption><span class="f-img-label">Figure<span class="f-img-label-joint">.</span></span> Alt fallback example</figcaption>
+<img src="bird.jpg" alt="">
+</figure>
+```
+
+```md {test id="docs-auto-title-fallback" setup="auto-title"}
+![No caption](fish.jpg "Plain title text")
+```
+
+```html {test id="docs-auto-title-fallback"}
+<figure class="f-img">
+<figcaption><span class="f-img-label">Figure<span class="f-img-label-joint">.</span></span> Plain title text</figcaption>
+<img src="fish.jpg" alt="No caption">
+</figure>
+```
+
+### Role helpers
+
+Set `roleDocExample: true` to add `role="doc-example"` to code/samp figures.
+This option decorates an eligible figure; it does not wrap a captionless fence
+by itself.
+
+~~~md {test id="docs-role-doc-example" setup="role-doc-example"}
+Terminal. Current directory.
+
+```samp
+$ pwd
+/home/user
+```
+~~~
+
+```html {test id="docs-role-doc-example"}
+<figure class="f-pre-samp" role="doc-example">
+<figcaption><span class="f-pre-samp-label">Terminal<span class="f-pre-samp-label-joint">.</span></span> Current directory.</figcaption>
+<pre><samp>$ pwd
+/home/user
+</samp></pre>
+</figure>
+```
+
+### Captionless conversion toggles
+
+If `imageOnlyParagraphWithoutCaption` (or the legacy alias `oneImageWithoutCaption`) is enabled, a single image paragraph will be wrapped with `<figure class="f-img">` even without a caption. Multi-image image-only paragraphs can also be wrapped, in which case the normal layout classes such as `f-img-horizontal`, `f-img-vertical`, or `f-img-multiple` are used.
+
+```md {test id="docs-captionless-image" setup="captionless-image"}
+![A single cat](cat.jpg)
+```
+
+```html {test id="docs-captionless-image"}
+<figure class="f-img">
+<img src="cat.jpg" alt="A single cat">
+</figure>
+```
+
+If `videoWithoutCaption` is enabled, `<video>` elements and iframes pointing to known video hosts (such as `www.youtube.com`, `youtube.com`, `www.youtube-nocookie.com`, or Vimeo) will be wrapped with `<figure class="f-video">`.
+
+```md {test id="docs-captionless-video-iframe" setup="captionless-video"}
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/XXXXXXXXXXX"></iframe>
+```
+
+```html {test id="docs-captionless-video-iframe"}
+<figure class="f-video">
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/XXXXXXXXXXX"></iframe>
+</figure>
+```
+
+```md {test id="docs-captionless-video" setup="captionless-video"}
+<video controls width="400" height="300">
+<source src="example.mp4" type="video/mp4">
+</video>
+```
+
+```html {test id="docs-captionless-video"}
+<figure class="f-video">
+<video controls width="400" height="300">
+<source src="example.mp4" type="video/mp4">
+</video>
+</figure>
+```
+
+When `iframeWithoutCaption` is enabled, generic iframe HTML blocks are wrapped
+with `<figure class="f-iframe">`. It also permits captionless wrapping of known
+video iframes, which retain `<figure class="f-video">`. `videoWithoutCaption`
+permits captionless `<video>` blocks and known video iframes without enabling
+generic iframes. If `iframeTypeBlockquoteWithoutCaption` is enabled, recognized
+blockquote-based embeds (for example, X) are wrapped with
+`<figure class="f-img">` or another configured class.
+
+```md {test id="docs-captionless-iframe" setup="captionless-iframe"}
+<iframe src="https://example.com/embed"></iframe>
+```
+
+```html {test id="docs-captionless-iframe"}
+<figure class="f-iframe">
+<iframe src="https://example.com/embed"></iframe>
+</figure>
+```
+
+#### Current social embed structures
+
+Social embed detection uses the exact class token on the opening `blockquote`.
+Additional `data-*` attributes, inline styles, SVG content, and current script
+hosts are preserved. The following compact examples exercise the same
+structures as the longer provider-generated snippets.
+
+```md {test id="docs-modern-mastodon" setup="captionless-social"}
+<blockquote class="mastodon-embed" data-embed-url="https://mastodon.social/@Mastodon/1/embed" style="background: #FCF8FF"><a href="https://mastodon.social/@Mastodon/1"><svg viewBox="0 0 79 75"><path d="M0 0"/></svg><span>View on Mastodon</span></a></blockquote> <script data-allowed-prefixes="https://mastodon.social/" async src="https://mastodon.social/embed.js"></script>
+```
+
+```html {test id="docs-modern-mastodon"}
+<figure class="f-img">
+<blockquote class="mastodon-embed" data-embed-url="https://mastodon.social/@Mastodon/1/embed" style="background: #FCF8FF"><a href="https://mastodon.social/@Mastodon/1"><svg viewBox="0 0 79 75"><path d="M0 0"/></svg><span>View on Mastodon</span></a></blockquote> <script data-allowed-prefixes="https://mastodon.social/" async src="https://mastodon.social/embed.js"></script>
+</figure>
+```
+
+```md {test id="docs-modern-threads" setup="captionless-social"}
+<blockquote class="text-post-media" data-text-post-permalink="https://www.threads.com/@threads/post/1" data-text-post-version="0" id="ig-tp-1"><a href="https://www.threads.com/@threads/post/1"><svg aria-label="Threads" viewBox="0 0 192 192"><path d="M0 0"/></svg><span>Threadsで見る</span></a></blockquote>
+<script async src="https://www.threads.com/embed.js"></script>
+```
+
+```html {test id="docs-modern-threads"}
+<figure class="f-img">
+<blockquote class="text-post-media" data-text-post-permalink="https://www.threads.com/@threads/post/1" data-text-post-version="0" id="ig-tp-1"><a href="https://www.threads.com/@threads/post/1"><svg aria-label="Threads" viewBox="0 0 192 192"><path d="M0 0"/></svg><span>Threadsで見る</span></a></blockquote>
+<script async src="https://www.threads.com/embed.js"></script>
+</figure>
+```
+
+```md {test id="docs-modern-x" setup="captionless-social"}
+<blockquote class="twitter-tweet" data-dnt="true"><p lang="en" dir="ltr">A post</p>&mdash; X (@X)</blockquote> <script async src="https://platform.x.com/widgets.js" charset="utf-8"></script>
+```
+
+```html {test id="docs-modern-x"}
+<figure class="f-img">
+<blockquote class="twitter-tweet" data-dnt="true"><p lang="en" dir="ltr">A post</p>&mdash; X (@X)</blockquote> <script async src="https://platform.x.com/widgets.js" charset="utf-8"></script>
+</figure>
+```
+
+```md {test id="docs-modern-bluesky" setup="captionless-social"}
+<blockquote class="bluesky-embed" data-bluesky-uri="at://did:plc:example/app.bsky.feed.post/1" data-bluesky-cid="cid" data-bluesky-embed-color-mode="system"><p lang="en">First line
+
+Second line</p>&mdash; Bluesky</blockquote><script async src="https://embed.bsky.app/static/embed.js" charset="utf-8"></script>
+```
+
+```html {test id="docs-modern-bluesky"}
+<figure class="f-img">
+<blockquote class="bluesky-embed" data-bluesky-uri="at://did:plc:example/app.bsky.feed.post/1" data-bluesky-cid="cid" data-bluesky-embed-color-mode="system"><p lang="en">First line
+
+Second line</p>&mdash; Bluesky</blockquote><script async src="https://embed.bsky.app/static/embed.js" charset="utf-8"></script>
+</figure>
+```
+
+### Iframe-type blockquote class override
+
+Set `figureClassThatWrapsIframeTypeBlockquote: 'f-social'` (or any class you prefer) to wrap blockquote-based embeds (for example, X, Mastodon, Bluesky) with that class.
+
+```md {test id="docs-social-class" setup="social-class"}
+Figure. Twitter embed.
+
+<blockquote class="twitter-tweet"><p>Embed content</p></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
+```
+
+```html {test id="docs-social-class"}
+<figure class="f-social">
+<figcaption><span class="f-img-label">Figure<span class="f-img-label-joint">.</span></span> Twitter embed.</figcaption>
+<blockquote class="twitter-tweet"><p>Embed content</p></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
+</figure>
+```
+
+### All iframe/embed class override
+
+Set `allIframeTypeFigureClassName: 'f-embed'` (or any class you prefer) to consolidate iframe-like embeds under one class.
+
+```md {test id="docs-all-iframe-class" setup="all-iframe-class"}
+Video. Custom embed.
+
+<iframe width="560" height="315" src="https://example.com/embed/123" title="Custom embed" frameborder="0" allowfullscreen></iframe>
+```
+
+```html {test id="docs-all-iframe-class"}
+<figure class="f-embed">
+<figcaption><span class="f-video-label">Video<span class="f-video-label-joint">.</span></span> Custom embed.</figcaption>
+<iframe width="560" height="315" src="https://example.com/embed/123" title="Custom embed" frameborder="0" allowfullscreen></iframe>
+</figure>
+```
+
+Need matching caption classes too? Use `labelClassFollowsFigure` (and optionally `figureToLabelClassMap`) so the `figcaption` spans inherit the embed class you just applied (e.g., `f-embed-label`, `f-embed-label-joint`). If `figureToLabelClassMap` is provided, figure-following mode is enabled automatically unless `labelClassFollowsFigure` is set explicitly.
+
+
+### Caption markers
+
+- `allowLabelPrefixMarkerWithoutLabel`: when `true`, marker-only paragraphs (e.g., `▼Caption`) are treated as captions without labels. If `labelPrefixMarker` is an array, the first entry is used for the previous caption and the second for the next caption. The marker is stripped from output.
+
+```js
+const figureOption = {
+  labelPrefixMarker: ['▼', '▲'],
+  allowLabelPrefixMarkerWithoutLabel: true,
+}
+
+const md = mdit({ html: true }).use(mditFigureWithPCaption, figureOption)
+```
+
+The first marker applies to captions before the figure, the second to captions after it.
+
+```md {test id="docs-caption-marker-before" setup="caption-markers"}
+▼Caption
+
+![Cat](cat.jpg)
+```
+
+```html {test id="docs-caption-marker-before"}
+<figure class="f-img">
+<figcaption>Caption</figcaption>
+<img src="cat.jpg" alt="Cat">
+</figure>
+```
+
+```md {test id="docs-caption-marker-after" setup="caption-markers"}
+![Cat](cat.jpg)
+
+▲Caption
+```
+
+```html {test id="docs-caption-marker-after"}
+<figure class="f-img">
+<img src="cat.jpg" alt="Cat">
+<figcaption>Caption</figcaption>
+</figure>
+```