@mirrordown/sat-caption 0.0.0 → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +9 -0
- package/README.md +176 -4
- package/dist/caption.css +23 -0
- package/dist/index.d.mts +18 -0
- package/dist/index.d.mts.map +1 -0
- package/dist/index.mjs +26 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +34 -2
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
<sub>2026-10-28</sub>
|
|
5
|
+
|
|
6
|
+
- *(minor)*
|
|
7
|
+
Add the caption plugin set: a `~:` line written right after a block captions it, wrapping the block in `<figure class="markdown-caption">` with a `<figcaption>`. Any block can take a caption (an image, paragraph, quote, code, table, list, or the containers other plugins add); a heading, thematic break, raw HTML or another caption can't. An image alone in its paragraph becomes the figure's content, and its alt text stays its alt text. The caption runs to the end of its paragraph and holds inline markdown; the `>` markers and indentation a caption line is written with decide which block it captions, as attrs places a line of attributes, and attributes ending a caption go on the figure. The markdown-it, remark and Sätteri plugins emit identical HTML.
|
|
8
|
+
- *(patch)*
|
|
9
|
+
Captioned lightbox images: a lightbox image (`!`) followed by a `~:` caption is now the figure's content, so its trigger sits directly in the `<figure>` without unwrap-images. The lightbox plugins take a `caption` option (off by default) that shows a captioned image's caption under it in the dialog; repeated images share one dialog, which shows the first caption any of them has. The presets pass lightbox options through (`lightbox: { caption: true }`). The lightbox READMEs are now generated from its guide.
|
package/README.md
CHANGED
|
@@ -1,9 +1,181 @@
|
|
|
1
1
|
# @mirrordown/sat-caption
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> Part of [Mirrordown](https://github.com/mirrordown/mirrordown) — a suite of markdown syntax extensions for the unified, markdown-it and Sätteri ecosystems.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
A Sätteri plugin for the `caption` syntax extension.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Overview
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
The `caption` plugin captions a block with a line starting `~:` written right after it. The block goes in a [`<figure>`](https://developer.mozilla.org/docs/Web/HTML/Element/figure), and the caption becomes its [`<figcaption>`](https://developer.mozilla.org/docs/Web/HTML/Element/figcaption):
|
|
10
|
+
|
|
11
|
+
```html
|
|
12
|
+
<figure class="markdown-caption">
|
|
13
|
+
<img src="fuji.jpg" alt="Mount Fuji at dawn">
|
|
14
|
+
<figcaption>Mount Fuji from Lake Kawaguchi.</figcaption>
|
|
15
|
+
</figure>
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Any block can take a caption: an image, a paragraph, a quote, code, a table, a list, and the blocks other plugins add, such as tabs, steps, alerts, definition lists and diagrams.
|
|
19
|
+
|
|
20
|
+
The marker follows the `~` that [definition lists](/guide/plugins/definition-list) use, with a colon, so it can't be mistaken for one: a term followed by `~ definition` stays a definition list. In renderers without the plugin, the caption stays a line of text.
|
|
21
|
+
|
|
22
|
+
## Syntax
|
|
23
|
+
|
|
24
|
+
Write `~:`, a space and the caption on the line right after the block, with no blank line between them. The caption runs to the end of its paragraph and can hold inline markdown.
|
|
25
|
+
|
|
26
|
+
### Images
|
|
27
|
+
|
|
28
|
+
An image alone in its paragraph becomes the figure's content. Its alt text stays its alt text, which describes the image to people who can't see it; the caption is for everyone.
|
|
29
|
+
|
|
30
|
+
````markdown
|
|
31
|
+

|
|
32
|
+
~: Mount Fuji from Lake Kawaguchi, *at dawn*.
|
|
33
|
+
````
|
|
34
|
+
|
|
35
|
+
A [lightbox](/guide/plugins/lightbox) image (`!`) works the same: its trigger is the figure's content, and the lightbox can show the caption in its dialog too. Several images in one paragraph make one figure. An image inside a sentence isn't a figure of its own, so a caption after it captions the paragraph.
|
|
36
|
+
|
|
37
|
+
### Quotes
|
|
38
|
+
|
|
39
|
+
A caption written after a quote, without its `>`, attributes it.
|
|
40
|
+
|
|
41
|
+
````markdown
|
|
42
|
+
> Simple is better than complex.
|
|
43
|
+
~: Tim Peters, *The Zen of Python*
|
|
44
|
+
````
|
|
45
|
+
|
|
46
|
+
### Code
|
|
47
|
+
|
|
48
|
+
`````markdown
|
|
49
|
+
```sh
|
|
50
|
+
npm install @mirrordown/remd-caption
|
|
51
|
+
```
|
|
52
|
+
~: Installing the remark plugin
|
|
53
|
+
`````
|
|
54
|
+
|
|
55
|
+
### Tables
|
|
56
|
+
|
|
57
|
+
````markdown
|
|
58
|
+
| Engine | Plugin |
|
|
59
|
+
| ----------- | --------------------------- |
|
|
60
|
+
| markdown-it | `@mirrordown/mdit-caption` |
|
|
61
|
+
| remark | `@mirrordown/remd-caption` |
|
|
62
|
+
| Sätteri | `@mirrordown/sat-caption` |
|
|
63
|
+
~: One plugin per engine
|
|
64
|
+
````
|
|
65
|
+
|
|
66
|
+
A table reads the caption line as a row of its own, so a table's caption can't contain a `|` (write `\|`).
|
|
67
|
+
|
|
68
|
+
### Any other block
|
|
69
|
+
|
|
70
|
+
````markdown
|
|
71
|
+
1. Measure twice.
|
|
72
|
+
2. Cut once.
|
|
73
|
+
~: A carpenter's rule
|
|
74
|
+
````
|
|
75
|
+
|
|
76
|
+
## Which block a caption goes on
|
|
77
|
+
|
|
78
|
+
A caption goes on the block it's written after, at the level its `>` markers and indentation put it, the same rule [attrs](/guide/plugins/attrs) uses for a line of attributes. Written inside a quote or list item, it captions the block before it there; written outside, it captions the quote or the whole list.
|
|
79
|
+
|
|
80
|
+
````markdown
|
|
81
|
+
> > A quote in a quote
|
|
82
|
+
> ~: Captions the inner quote
|
|
83
|
+
~: Captions the outer quote
|
|
84
|
+
|
|
85
|
+
- An item
|
|
86
|
+
~: Captions the item's paragraph
|
|
87
|
+
- Another item
|
|
88
|
+
~: Captions the list
|
|
89
|
+
````
|
|
90
|
+
|
|
91
|
+
The caption runs to the end of its paragraph, so a `~:` on a later line at the same level is part of it. A caption doesn't attach to a heading, a thematic break, raw HTML, or another caption, and a `~:` after a blank line is text, so a caption always touches its block.
|
|
92
|
+
|
|
93
|
+
### Attributes
|
|
94
|
+
|
|
95
|
+
With the [`attrs`](/guide/plugins/attrs) plugin, attributes written at the end of a caption go on the figure, which gives it an id to link to. A block keeps its own attributes.
|
|
96
|
+
|
|
97
|
+
````markdown
|
|
98
|
+
{.photo}
|
|
99
|
+
~: Wild rice in late summer {#fig-rice}
|
|
100
|
+
````
|
|
101
|
+
|
|
102
|
+
```html
|
|
103
|
+
<figure class="markdown-caption" id="fig-rice">
|
|
104
|
+
<img src="wild-rice.jpg" alt="Wild rice growing in a marsh" class="photo">
|
|
105
|
+
<figcaption>Wild rice in late summer</figcaption>
|
|
106
|
+
</figure>
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Customization
|
|
110
|
+
|
|
111
|
+
The stylesheet keeps its rules in `@layer markdown-caption`, so any unlayered CSS you write overrides them. It removes the browser's default figure indent (40px on each side, which would narrow tables and code) and sets the caption a little smaller and lighter than the text around it.
|
|
112
|
+
|
|
113
|
+
```css
|
|
114
|
+
.markdown-caption > figcaption {
|
|
115
|
+
font-style: italic;
|
|
116
|
+
text-align: center;
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Number figures with a CSS counter:
|
|
121
|
+
|
|
122
|
+
```css
|
|
123
|
+
.content {
|
|
124
|
+
counter-reset: figure;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
.markdown-caption > figcaption::before {
|
|
128
|
+
counter-increment: figure;
|
|
129
|
+
content: "Figure " counter(figure) ": ";
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Compared with remark-captions
|
|
134
|
+
|
|
135
|
+
[remark-captions](https://github.com/zestedesavoir/zmarkdown/tree/master/packages/remark-captions) uses a word for each kind of block (`Figure:`, `Source:`, `Code:`, `Table:`) and captions only the kinds it's configured for. This plugin has one marker for every block. Its table captions also work with today's GFM tables, where remark-captions' `Table:` line becomes a row.
|
|
136
|
+
|
|
137
|
+
## Install
|
|
138
|
+
|
|
139
|
+
```sh
|
|
140
|
+
npm install @mirrordown/sat-caption
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
List it after the plugins that build container blocks (tabs, steps, alerts). Sätteri reads attributes itself, with its `attributes` feature.
|
|
144
|
+
|
|
145
|
+
### Standalone
|
|
146
|
+
|
|
147
|
+
```ts
|
|
148
|
+
import { markdownToHtml } from "satteri";
|
|
149
|
+
import { satteriCaption } from "@mirrordown/sat-caption";
|
|
150
|
+
import "@mirrordown/sat-caption/caption.css";
|
|
151
|
+
|
|
152
|
+
const { html } = markdownToHtml(source, {
|
|
153
|
+
mdastPlugins: [satteriCaption()],
|
|
154
|
+
});
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### Astro
|
|
158
|
+
|
|
159
|
+
```ts
|
|
160
|
+
// astro.config.ts
|
|
161
|
+
import { defineConfig } from "astro/config";
|
|
162
|
+
import { satteri } from "@astrojs/markdown-satteri";
|
|
163
|
+
import { satteriCaption } from "@mirrordown/sat-caption";
|
|
164
|
+
|
|
165
|
+
export default defineConfig({
|
|
166
|
+
markdown: {
|
|
167
|
+
processor: satteri({ mdastPlugins: [satteriCaption()] }),
|
|
168
|
+
},
|
|
169
|
+
});
|
|
170
|
+
|
|
171
|
+
// In your layout:
|
|
172
|
+
import "@mirrordown/sat-caption/caption.css";
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## Documentation
|
|
176
|
+
|
|
177
|
+
Full documentation, more examples, and configuration options: [github.com/mirrordown/mirrordown](https://github.com/mirrordown/mirrordown) (dedicated docs site coming soon).
|
|
178
|
+
|
|
179
|
+
## License
|
|
180
|
+
|
|
181
|
+
MIT © [Drake Costa](https://saeris.gg)
|
package/dist/caption.css
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/*
|
|
2
|
+
Captions — default stylesheet
|
|
3
|
+
-----------------------------
|
|
4
|
+
All rules live inside @layer markdown-caption so any unlayered consumer CSS
|
|
5
|
+
overrides them without needing !important.
|
|
6
|
+
|
|
7
|
+
A captioned block is wrapped in `<figure class="markdown-caption">`, with its
|
|
8
|
+
`<figcaption>` last. Browsers indent a figure by 40px on each side, which
|
|
9
|
+
would narrow the tables, code and lists it holds, so the indent is removed.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
@layer markdown-caption {
|
|
13
|
+
.markdown-caption {
|
|
14
|
+
margin-inline: 0;
|
|
15
|
+
margin-block: 1em;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
.markdown-caption > figcaption {
|
|
19
|
+
margin-block-start: 0.5em;
|
|
20
|
+
font-size: 0.875em;
|
|
21
|
+
color: color-mix(in oklab, currentColor 70%, transparent);
|
|
22
|
+
}
|
|
23
|
+
}
|
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { MdastPluginInstance, PluginFactoryContext } from "satteri";
|
|
2
|
+
type BeforeHook = NonNullable<MdastPluginInstance["before"]>;
|
|
3
|
+
/**
|
|
4
|
+
* The plugin's definition: only the keys it defines, with a synchronous hook, so `markdownToHtml` returns its result directly.
|
|
5
|
+
*/
|
|
6
|
+
export interface CaptionPlugin {
|
|
7
|
+
name: string;
|
|
8
|
+
options: {
|
|
9
|
+
position: boolean;
|
|
10
|
+
};
|
|
11
|
+
before: (...args: Parameters<BeforeHook>) => void;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Sätteri plugin that captions a block with a `~:` line right after it: the block goes in a `<figure class="markdown-caption">` whose `<figcaption>` holds the caption, as `@mirrordown/remd-caption` and `@mirrordown/mdit-caption` render it. List it after the container plugins (tabs, steps, alerts): Sätteri reads attribute blocks itself, and those ending a caption go on the figure. Recognition is shared with the remark plugin through `@mirrordown/core`; the figures render through `hName` nodes.
|
|
15
|
+
*/
|
|
16
|
+
export declare const satteriCaption: () => ((ctx: PluginFactoryContext) => CaptionPlugin);
|
|
17
|
+
export {};
|
|
18
|
+
//# sourceMappingURL=index.d.mts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";KAWK,aAAa,YAAY;;;;iBAKb;EACf;EACA;IAAW;;EACX,YAAY,MAAM,WAAW;;;;;qBAMlB,wBACL,KAAK,yBAAyB"}
|
package/dist/index.mjs
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { editableTree, processCaptions } from "@mirrordown/core";
|
|
2
|
+
import { defineMdastPlugin } from "satteri";
|
|
3
|
+
// src/index.ts
|
|
4
|
+
/**
|
|
5
|
+
* Sätteri plugin that captions a block with a `~:` line right after it: the block goes in a `<figure class="markdown-caption">` whose `<figcaption>` holds the caption, as `@mirrordown/remd-caption` and `@mirrordown/mdit-caption` render it. List it after the container plugins (tabs, steps, alerts): Sätteri reads attribute blocks itself, and those ending a caption go on the figure. Recognition is shared with the remark plugin through `@mirrordown/core`; the figures render through `hName` nodes.
|
|
6
|
+
*/
|
|
7
|
+
const satteriCaption = () => ({ source }) => defineMdastPlugin({
|
|
8
|
+
name: `caption`,
|
|
9
|
+
options: { position: true },
|
|
10
|
+
before(root, ctx) {
|
|
11
|
+
if (!source.includes(`~:`)) return;
|
|
12
|
+
const { tree, writeBack } = editableTree(root, (node, back) => `children` in node ? {
|
|
13
|
+
...node,
|
|
14
|
+
children: node.children.map(back)
|
|
15
|
+
} : node, (node, children) => {
|
|
16
|
+
ctx.setProperty(node, `children`, children);
|
|
17
|
+
}, (node, data) => {
|
|
18
|
+
ctx.setProperty(node, `data`, data);
|
|
19
|
+
});
|
|
20
|
+
processCaptions(tree, source);
|
|
21
|
+
writeBack(tree);
|
|
22
|
+
}
|
|
23
|
+
});
|
|
24
|
+
export { satteriCaption };
|
|
25
|
+
|
|
26
|
+
//# sourceMappingURL=index.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["// This plugin hands Sätteri's nodes to core's mdast recognition and back; the type assertions bridging Sätteri's `MdastTarget` and mdast are reviewed and intentional, so the rule is disabled file-wide, as in sat-tabs.\n/* oxlint-disable typescript/no-unsafe-type-assertion */\nimport { editableTree, processCaptions } from \"@mirrordown/core\";\nimport type { Root } from \"mdast\";\nimport {\n defineMdastPlugin,\n type MdastPluginInstance,\n type MdastTarget,\n type PluginFactoryContext\n} from \"satteri\";\n\ntype BeforeHook = NonNullable<MdastPluginInstance[\"before\"]>;\n\n/**\n * The plugin's definition: only the keys it defines, with a synchronous hook, so `markdownToHtml` returns its result directly.\n */\nexport interface CaptionPlugin {\n name: string;\n options: { position: boolean };\n before: (...args: Parameters<BeforeHook>) => void;\n}\n\n/**\n * Sätteri plugin that captions a block with a `~:` line right after it: the block goes in a `<figure class=\"markdown-caption\">` whose `<figcaption>` holds the caption, as `@mirrordown/remd-caption` and `@mirrordown/mdit-caption` render it. List it after the container plugins (tabs, steps, alerts): Sätteri reads attribute blocks itself, and those ending a caption go on the figure. Recognition is shared with the remark plugin through `@mirrordown/core`; the figures render through `hName` nodes.\n */\nexport const satteriCaption =\n (): ((ctx: PluginFactoryContext) => CaptionPlugin) =>\n ({ source }) =>\n defineMdastPlugin({\n name: `caption`,\n // Caption lines are found and placed by their source lines.\n options: { position: true },\n before(root, ctx) {\n if (!source.includes(`~:`)) return;\n const { tree, writeBack } = editableTree<MdastTarget>(\n root,\n // A node recognition created (a figure, its caption, a rebuilt line of text), with any copied nodes inside it written back.\n (node, back) =>\n `children` in node\n ? ({ ...node, children: node.children.map(back) } as MdastTarget)\n : node,\n (node, children) => {\n ctx.setProperty(node, `children`, children);\n },\n (node, data) => {\n ctx.setProperty(\n node,\n `data`,\n data as Record<string, unknown> | null\n );\n }\n );\n processCaptions(tree as unknown as Root, source);\n writeBack(tree);\n }\n });\n"],"mappings":";;;;;;AAyBA,MAAa,wBAEV,EAAE,aACD,kBAAkB;CAChB,MAAM;CAEN,SAAS,EAAE,UAAU,KAAK;CAC1B,OAAO,MAAM,KAAK;EAChB,IAAI,CAAC,OAAO,SAAS,IAAI,GAAG;EAC5B,MAAM,EAAE,MAAM,cAAc,aAC1B,OAEC,MAAM,SACL,cAAc,OACT;GAAE,GAAG;GAAM,UAAU,KAAK,SAAS,IAAI,IAAI;EAAE,IAC9C,OACL,MAAM,aAAa;GAClB,IAAI,YAAY,MAAM,YAAY,QAAQ;EAC5C,IACC,MAAM,SAAS;GACd,IAAI,YACF,MACA,QACA,IACF;EACF,CACF;EACA,gBAAgB,MAAyB,MAAM;EAC/C,UAAU,IAAI;CAChB;AACF,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,11 +1,43 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mirrordown/sat-caption",
|
|
3
|
-
"version": "0.0.0",
|
|
4
3
|
"description": "A Sätteri plugin to caption any block with a ~: line after it, wrapping it in <figure> with a <figcaption>.",
|
|
4
|
+
"version": "0.1.0",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Drake Costa <drake@saeris.io> (https://saeris.gg)",
|
|
7
7
|
"repository": {
|
|
8
8
|
"type": "git",
|
|
9
9
|
"url": "git+https://github.com/mirrordown/mirrordown.git"
|
|
10
|
+
},
|
|
11
|
+
"files": [
|
|
12
|
+
"dist"
|
|
13
|
+
],
|
|
14
|
+
"type": "module",
|
|
15
|
+
"exports": {
|
|
16
|
+
".": {
|
|
17
|
+
"development": "./src/index.ts",
|
|
18
|
+
"types": "./dist/index.d.mts",
|
|
19
|
+
"import": "./dist/index.mjs"
|
|
20
|
+
},
|
|
21
|
+
"./*.css": "./dist/*.css"
|
|
22
|
+
},
|
|
23
|
+
"dependencies": {
|
|
24
|
+
"@mirrordown/core": "^0.1.1"
|
|
25
|
+
},
|
|
26
|
+
"devDependencies": {
|
|
27
|
+
"satteri": "^0.11.5"
|
|
28
|
+
},
|
|
29
|
+
"peerDependencies": {
|
|
30
|
+
"satteri": "^0.10.5 || ^0.11.0"
|
|
31
|
+
},
|
|
32
|
+
"engines": {
|
|
33
|
+
"node": ">=24.0.0"
|
|
34
|
+
},
|
|
35
|
+
"bumpy": {
|
|
36
|
+
"publishCommand": [
|
|
37
|
+
"node ../../scripts/sync-jsr-version.mjs",
|
|
38
|
+
"node ../../scripts/npm-publish.mjs",
|
|
39
|
+
"node ../../scripts/jsr-resolve-deps.mjs",
|
|
40
|
+
"node ../../scripts/jsr-publish.mjs"
|
|
41
|
+
]
|
|
10
42
|
}
|
|
11
|
-
}
|
|
43
|
+
}
|