satteri-comark 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/README.md +235 -0
- package/dist/2colons.d.mts +58 -0
- package/dist/2colons.mjs +96 -0
- package/dist/index.d.mts +93 -0
- package/dist/index.mjs +187 -0
- package/dist/util-ChyRgdb_.mjs +36 -0
- package/package.json +59 -0
package/README.md
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
# satteri-comark
|
|
2
|
+
|
|
3
|
+
`satteri-comark` is a [Satteri](https://satteri.bruits.org) plugin that adds support for most of [Comark](https://comark.dev)'s component syntax by transforming it into MDX.
|
|
4
|
+
|
|
5
|
+
## See an example
|
|
6
|
+
|
|
7
|
+
Take this scary example from Comark docs:
|
|
8
|
+
|
|
9
|
+
````md
|
|
10
|
+
::card{.featured}
|
|
11
|
+
```yaml [props]
|
|
12
|
+
variant: elevated
|
|
13
|
+
color: primary
|
|
14
|
+
actions:
|
|
15
|
+
- label: Read More
|
|
16
|
+
url: /article
|
|
17
|
+
- label: Share
|
|
18
|
+
icon: share
|
|
19
|
+
```
|
|
20
|
+
#header
|
|
21
|
+
## Article Title
|
|
22
|
+
*By Jane Doe*
|
|
23
|
+
|
|
24
|
+
#content
|
|
25
|
+
This is the main article content with **markdown** support.
|
|
26
|
+
|
|
27
|
+
#footer
|
|
28
|
+
Published on January 15, 2024
|
|
29
|
+
::
|
|
30
|
+
````
|
|
31
|
+
|
|
32
|
+
With `satteri-comark`, Satteri transforms it into the following JSX output:
|
|
33
|
+
|
|
34
|
+
```jsx
|
|
35
|
+
<Card
|
|
36
|
+
class="featured"
|
|
37
|
+
variant="elevated"
|
|
38
|
+
color="primary"
|
|
39
|
+
actions={[
|
|
40
|
+
{
|
|
41
|
+
label: "Read More",
|
|
42
|
+
url: "/article",
|
|
43
|
+
},
|
|
44
|
+
{
|
|
45
|
+
label: "Share",
|
|
46
|
+
icon: "share",
|
|
47
|
+
},
|
|
48
|
+
]}
|
|
49
|
+
>
|
|
50
|
+
<Fragment slot="header">
|
|
51
|
+
<h2>{"Article Title"}</h2>
|
|
52
|
+
<p>
|
|
53
|
+
<em>{"By Jane Doe"}</em>
|
|
54
|
+
</p>
|
|
55
|
+
</Fragment>
|
|
56
|
+
<Fragment slot="content">
|
|
57
|
+
{"This is the main article content with "}
|
|
58
|
+
<strong>{"markdown"}</strong>
|
|
59
|
+
{" support."}
|
|
60
|
+
</Fragment>
|
|
61
|
+
<Fragment slot="footer">{"Published on January 15, 2024"}</Fragment>
|
|
62
|
+
</Card>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Features
|
|
66
|
+
|
|
67
|
+
### What is supported
|
|
68
|
+
|
|
69
|
+
- Two-colon component syntax (`::component` can be a container)
|
|
70
|
+
- Translation of block components and inline components into MDX
|
|
71
|
+
- Data binding syntax (`:prop="expr"`)
|
|
72
|
+
- Block props inside code fences
|
|
73
|
+
- Named slots. You can customize what slots transform into, and this package includes an adapter for [Astro](https://astro.build).
|
|
74
|
+
|
|
75
|
+
### Extra features
|
|
76
|
+
|
|
77
|
+
- In addition to normal data bindings for props, you can specify an expression to spread by setting the prop with name `::` (more convenient for inline props) or `...` (more convenient for block props) to that expression. For example, `:component{::="\{prop: 'value'\}"}`.
|
|
78
|
+
|
|
79
|
+
- Block props support more languages by default, powered by [`confbox`](https://npmjs.com/package/confbox). Currently, in addition to YAML, JSON5, JSON with comments (JSONC), JSON, TOML, and INI are supported; just specify the language of the code block. You can also customize the behavior of prop blocks.
|
|
80
|
+
|
|
81
|
+
- You can embed MDX `import/export` statements with ```` ```jsx|tsx [script] ```` code blocks.
|
|
82
|
+
|
|
83
|
+
- You can embed JSX expressions with ```` ```jsx|tsx [embed] ```` code blocks.
|
|
84
|
+
|
|
85
|
+
### Divergences from Comark
|
|
86
|
+
|
|
87
|
+
In data bindings, values are just plain JS expressions (for example, you can do `:prop="arbitraryFunction()"`). This is more flexible than Comark.
|
|
88
|
+
|
|
89
|
+
On the other hand, the data binding namespaces that Comark provides (`frontmatter`, `meta`, `data`, `props`) aren't set up by this plugin, and you or your framework need to inject them into your MDX environment. For example, Astro provides the `frontmatter` variable to all MDX files.
|
|
90
|
+
|
|
91
|
+
### What is not supported
|
|
92
|
+
|
|
93
|
+
- Frontmatter-style block props are not supported because Satteri cannot parse them.
|
|
94
|
+
- Nesting components must each have a distinct number of colons, otherwise Satteri cannot parse them (bruits/satteri#203).
|
|
95
|
+
- You must escape curly braces in inline props. This is due to a Satteri bug (bruits/satteri#301).
|
|
96
|
+
- Other Comark extensions, such as admonitions (there are separate Satteri plugins you can use) or block attributes (planned: bruits/satteri#139).
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
## How to use
|
|
100
|
+
|
|
101
|
+
`satteri-comark` provides two Satteri plugins:
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
import directiveTwoColons from 'satteri-comark/2colons'
|
|
105
|
+
import comarkMdx from 'satteri-comark'
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
- `directiveTwoColons` parses two-colon directives `::component` into container directives.
|
|
109
|
+
- `comarkMdx` provides all other functionalities. It is possible to use this plugin without `directiveTwoColons`, it just means that two-colon directives will be parsed as leaf directives (Satteri's deafult behavior).
|
|
110
|
+
|
|
111
|
+
To use:
|
|
112
|
+
|
|
113
|
+
```ts
|
|
114
|
+
import { mdxToJs } from 'satteri'
|
|
115
|
+
|
|
116
|
+
const result = mdxToJs(mdxSource, {
|
|
117
|
+
features: {
|
|
118
|
+
directive: true, // Turn on baseline support for directive syntax
|
|
119
|
+
},
|
|
120
|
+
mdastPlugins: [
|
|
121
|
+
directiveTwoColons(), // must come before `comarkMdx`
|
|
122
|
+
comarkMdx(),
|
|
123
|
+
]
|
|
124
|
+
})
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
This will parse Comark syntax with the default handling for named slots: the slot names are simply discarded. To configure this, and other behaviors of `satteri-comark`, pass options to `directiveTwoColons` and `comarkMdx`:
|
|
128
|
+
|
|
129
|
+
### Options for `directiveTwoColons`
|
|
130
|
+
|
|
131
|
+
You can pass an object with the following signature to configure this plugin:
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
export interface Options {
|
|
135
|
+
/**
|
|
136
|
+
* Behavior when encoutering an unterminated 2-colon directive.
|
|
137
|
+
*
|
|
138
|
+
* - `'error'`: Throw an error.
|
|
139
|
+
* - `'greedy'`: Assume the directive extends as far as possible, until the next 2-colon
|
|
140
|
+
* directive or the end of its parent element.
|
|
141
|
+
* - `'self-closing'`: Treat the directive as self-closing; no content is contained inside. Note
|
|
142
|
+
* that this recovers the classical behavior of "leaf directives".
|
|
143
|
+
* @default 'self-closing'
|
|
144
|
+
*/
|
|
145
|
+
onUnterminated?: 'error' | 'greedy' | 'self-closing'
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### Options for `comarkMdx`
|
|
150
|
+
|
|
151
|
+
You can pass an object with the following signature to configure this plugin:
|
|
152
|
+
|
|
153
|
+
```ts
|
|
154
|
+
export interface Options {
|
|
155
|
+
/**
|
|
156
|
+
* Function for normalizing element names. Pass a no-op function to disable this behavior.
|
|
157
|
+
* @default htmlOrPascalCase
|
|
158
|
+
*/
|
|
159
|
+
normalizeCase?: (name: string) => string
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Support bindings (arbitrary expressions) in props via the `:prop="expr"` syntax, as well as
|
|
163
|
+
* the `::` and `...` prop names for expressions to be used as spread props.
|
|
164
|
+
* @default true
|
|
165
|
+
*/
|
|
166
|
+
bindings?: boolean
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* How to parse `[props]` code blocks in the given languages
|
|
170
|
+
* @default viaConfbox
|
|
171
|
+
*/
|
|
172
|
+
propsBlocks?: Record<string, (input: string) => unknown>
|
|
173
|
+
|
|
174
|
+
/**
|
|
175
|
+
* Enable `[script]` code blocks
|
|
176
|
+
* @default true
|
|
177
|
+
*/
|
|
178
|
+
scriptBlocks?: boolean
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* Enable `[embed]` code blocks
|
|
182
|
+
* @default true
|
|
183
|
+
*/
|
|
184
|
+
embedBlocks?: boolean
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* Define slot support in container directives
|
|
188
|
+
* @default passthrough
|
|
189
|
+
*/
|
|
190
|
+
slots?: (name: string, children: SlotContents) => BlockLevelContent | BlockLevelContent[]
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
export type BlockLevelContent = BlockContent | DefinitionContent
|
|
194
|
+
|
|
195
|
+
export type SlotContents =
|
|
196
|
+
{ type: 'inline'; contents: PhrasingContent[] } | { type: 'block'; contents: BlockLevelContent[] }
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
The default values `htmlOrPascalCase`, `viaConfbox`, and `passthrough` are as follows:
|
|
200
|
+
|
|
201
|
+
```ts
|
|
202
|
+
/**
|
|
203
|
+
* Default value for `Options.normalizeCase`. If element name is a valid HTML tag, it will be
|
|
204
|
+
* converted to lowercase. Otherwise, it will be converted to PascalCase.
|
|
205
|
+
*/
|
|
206
|
+
export function htmlOrPascalCase(name: string): string
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Default value for `Options.propsBlocks`. Uses the `confbox` library to parse the following
|
|
210
|
+
* languages: JSON5, JSON with comments (JSONC), YAML, JSON, TOML, and INI.
|
|
211
|
+
*/
|
|
212
|
+
export const viaConfbox: Record<string, (input: string) => unknown>
|
|
213
|
+
|
|
214
|
+
/**
|
|
215
|
+
* Default value for `Options.slots`. Passes through the slot contents as-is and discards the slot
|
|
216
|
+
* name.
|
|
217
|
+
*/
|
|
218
|
+
export function passthrough(_name: string, children: SlotContents): BlockLevelContent[]
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
`satteri-comark` additionally exports a named slot adapter suitable for use with Astro. You should `import { astroFragment } from 'satteri-comark'` and pass it to the `slots` fields of the `Options` object.
|
|
222
|
+
|
|
223
|
+
```ts
|
|
224
|
+
/**
|
|
225
|
+
* Value for `Options.slots` suitable for the Astro framework. Converts slots into slotted JSX
|
|
226
|
+
* fragments:
|
|
227
|
+
*
|
|
228
|
+
* ```jsx
|
|
229
|
+
* <Fragment slot="[slotName]">
|
|
230
|
+
* <... slot content ...>
|
|
231
|
+
* </Fragment>
|
|
232
|
+
* ```
|
|
233
|
+
*/
|
|
234
|
+
export function astroFragment(name: string, children: SlotContents): BlockLevelContent
|
|
235
|
+
```
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import { MdastPluginDefinition } from "satteri";
|
|
2
|
+
//#region src/2colons.d.ts
|
|
3
|
+
export interface Options {
|
|
4
|
+
/**
|
|
5
|
+
* Behavior when encoutering an unterminated 2-colon directive.
|
|
6
|
+
*
|
|
7
|
+
* - `'error'`: Throw an error.
|
|
8
|
+
* - `'greedy'`: Assume the directive extends as far as possible, until the next 2-colon
|
|
9
|
+
* directive or the end of its parent element.
|
|
10
|
+
* - `'self-closing'`: Treat the directive as self-closing; no content is contained inside. Note
|
|
11
|
+
* that this recovers the classical behavior of "leaf directives".
|
|
12
|
+
* @default 'self-closing'
|
|
13
|
+
*/
|
|
14
|
+
onUnterminated?: "error" | "greedy" | "self-closing";
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* This Satteri plugin allows for container directives using two colons, instead of three at
|
|
18
|
+
* minimum:
|
|
19
|
+
*
|
|
20
|
+
* ```md
|
|
21
|
+
* ::container
|
|
22
|
+
* ... content ...
|
|
23
|
+
* ::
|
|
24
|
+
* ```
|
|
25
|
+
*
|
|
26
|
+
* Note that this plugin doesn't change that each nesting level of container directives must have
|
|
27
|
+
* _distinct_ numbers of colons. This is a limitation of `pulldown-cmark` that we cannot work
|
|
28
|
+
* around. For example, the following input would still parse nonsensically:
|
|
29
|
+
*
|
|
30
|
+
* ```md
|
|
31
|
+
* ::container
|
|
32
|
+
* ::container-2
|
|
33
|
+
* :::container-3
|
|
34
|
+
* :::container-4
|
|
35
|
+
* :::
|
|
36
|
+
* :::
|
|
37
|
+
* ::
|
|
38
|
+
* ::
|
|
39
|
+
* ```
|
|
40
|
+
*
|
|
41
|
+
* As opposed to this, which parses correctly:
|
|
42
|
+
*
|
|
43
|
+
* ```md
|
|
44
|
+
* ::container
|
|
45
|
+
* :::::container-2
|
|
46
|
+
* :::container-3
|
|
47
|
+
* ::::container-4
|
|
48
|
+
* ::::
|
|
49
|
+
* :::
|
|
50
|
+
* :::::
|
|
51
|
+
* ::
|
|
52
|
+
* ```
|
|
53
|
+
*
|
|
54
|
+
* Of special note here is that the number of colons need not be strictly increasing or decreasing.
|
|
55
|
+
*/
|
|
56
|
+
declare const _default: (opts?: Options) => MdastPluginDefinition;
|
|
57
|
+
//#endregion
|
|
58
|
+
export { _default as default };
|
package/dist/2colons.mjs
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import { r as splitParagraph, t as omit } from "./util-ChyRgdb_.mjs";
|
|
2
|
+
import { defineMdastPlugin } from "satteri";
|
|
3
|
+
import { u } from "unist-builder";
|
|
4
|
+
//#region src/2colons.ts
|
|
5
|
+
const visit = ({ onUnterminated = "self-closing" }) => (node, ctx) => {
|
|
6
|
+
const newChildren = [];
|
|
7
|
+
let start = null;
|
|
8
|
+
let inside = [];
|
|
9
|
+
let commit = (terminated) => {
|
|
10
|
+
if (start) {
|
|
11
|
+
if (!terminated && onUnterminated === "error") throw new Error(`Unterminated directive: ${start.name}`);
|
|
12
|
+
else if (!terminated && onUnterminated === "self-closing") newChildren.push(start);
|
|
13
|
+
else {
|
|
14
|
+
newChildren.push(u("containerDirective", omit(start, "type"), [...start.children.length ? [u("paragraph", { data: { directiveLabel: true } }, start.children)] : [], ...inside]));
|
|
15
|
+
inside = [];
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
newChildren.push(...inside);
|
|
19
|
+
};
|
|
20
|
+
for (let blockIx = 0; blockIx < node.children.length; blockIx++) {
|
|
21
|
+
const block = node.children[blockIx];
|
|
22
|
+
if (block.type === "leafDirective") {
|
|
23
|
+
commit(false);
|
|
24
|
+
start = block;
|
|
25
|
+
inside = [];
|
|
26
|
+
} else if (start && block.type === "paragraph") {
|
|
27
|
+
const split = splitParagraph(block, (line) => line === "::");
|
|
28
|
+
if (!split) {
|
|
29
|
+
inside.push(block);
|
|
30
|
+
continue;
|
|
31
|
+
}
|
|
32
|
+
const [before, _, after] = split;
|
|
33
|
+
inside.push(...before.length ? [u("paragraph", before)] : []);
|
|
34
|
+
commit(true);
|
|
35
|
+
start = null;
|
|
36
|
+
inside = after.length ? [u("paragraph", after)] : [];
|
|
37
|
+
} else inside.push(block);
|
|
38
|
+
}
|
|
39
|
+
commit(false);
|
|
40
|
+
ctx.replaceNode(node, {
|
|
41
|
+
...node,
|
|
42
|
+
children: newChildren
|
|
43
|
+
});
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* This Satteri plugin allows for container directives using two colons, instead of three at
|
|
47
|
+
* minimum:
|
|
48
|
+
*
|
|
49
|
+
* ```md
|
|
50
|
+
* ::container
|
|
51
|
+
* ... content ...
|
|
52
|
+
* ::
|
|
53
|
+
* ```
|
|
54
|
+
*
|
|
55
|
+
* Note that this plugin doesn't change that each nesting level of container directives must have
|
|
56
|
+
* _distinct_ numbers of colons. This is a limitation of `pulldown-cmark` that we cannot work
|
|
57
|
+
* around. For example, the following input would still parse nonsensically:
|
|
58
|
+
*
|
|
59
|
+
* ```md
|
|
60
|
+
* ::container
|
|
61
|
+
* ::container-2
|
|
62
|
+
* :::container-3
|
|
63
|
+
* :::container-4
|
|
64
|
+
* :::
|
|
65
|
+
* :::
|
|
66
|
+
* ::
|
|
67
|
+
* ::
|
|
68
|
+
* ```
|
|
69
|
+
*
|
|
70
|
+
* As opposed to this, which parses correctly:
|
|
71
|
+
*
|
|
72
|
+
* ```md
|
|
73
|
+
* ::container
|
|
74
|
+
* :::::container-2
|
|
75
|
+
* :::container-3
|
|
76
|
+
* ::::container-4
|
|
77
|
+
* ::::
|
|
78
|
+
* :::
|
|
79
|
+
* :::::
|
|
80
|
+
* ::
|
|
81
|
+
* ```
|
|
82
|
+
*
|
|
83
|
+
* Of special note here is that the number of colons need not be strictly increasing or decreasing.
|
|
84
|
+
*/
|
|
85
|
+
var _2colons_default = (opts = {}) => defineMdastPlugin({
|
|
86
|
+
name: "directive-2-colons",
|
|
87
|
+
before: visit(opts),
|
|
88
|
+
blockquote: visit(opts),
|
|
89
|
+
listItem: visit(opts),
|
|
90
|
+
footnoteDefinition: visit(opts),
|
|
91
|
+
containerDirective: visit(opts),
|
|
92
|
+
descriptionDetails: visit(opts),
|
|
93
|
+
mdxJsxFlowElement: visit(opts)
|
|
94
|
+
});
|
|
95
|
+
//#endregion
|
|
96
|
+
export { _2colons_default as default };
|
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import { MdastPluginDefinition } from "satteri";
|
|
2
|
+
import { BlockContent, DefinitionContent, PhrasingContent } from "mdast";
|
|
3
|
+
//#region src/index.d.ts
|
|
4
|
+
export type BlockLevelContent = BlockContent | DefinitionContent;
|
|
5
|
+
export type SlotContents = {
|
|
6
|
+
type: "inline";
|
|
7
|
+
contents: PhrasingContent[];
|
|
8
|
+
} | {
|
|
9
|
+
type: "block";
|
|
10
|
+
contents: BlockLevelContent[];
|
|
11
|
+
};
|
|
12
|
+
export interface Options {
|
|
13
|
+
/**
|
|
14
|
+
* Function for normalizing element names. Pass a no-op function to disable this behavior.
|
|
15
|
+
* @default htmlOrPascalCase
|
|
16
|
+
*/
|
|
17
|
+
normalizeCase?: (name: string) => string;
|
|
18
|
+
/**
|
|
19
|
+
* Support bindings (arbitrary expressions) in props via the `:prop="expr"` syntax, as well as
|
|
20
|
+
* the `::` and `...` prop names for expressions to be used as spread props.
|
|
21
|
+
* @default true
|
|
22
|
+
*/
|
|
23
|
+
bindings?: boolean;
|
|
24
|
+
/**
|
|
25
|
+
* How to parse `[props]` code blocks in the given languages
|
|
26
|
+
* @default viaConfbox
|
|
27
|
+
*/
|
|
28
|
+
propsBlocks?: Record<string, (input: string) => unknown>;
|
|
29
|
+
/**
|
|
30
|
+
* Enable `[script]` code blocks
|
|
31
|
+
* @default true
|
|
32
|
+
*/
|
|
33
|
+
scriptBlocks?: boolean;
|
|
34
|
+
/**
|
|
35
|
+
* Enable `[embed]` code blocks
|
|
36
|
+
* @default true
|
|
37
|
+
*/
|
|
38
|
+
embedBlocks?: boolean;
|
|
39
|
+
/**
|
|
40
|
+
* Define slot support in container directives
|
|
41
|
+
* @default passthrough
|
|
42
|
+
*/
|
|
43
|
+
slots?: (name: string, children: SlotContents) => BlockLevelContent | BlockLevelContent[];
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Default value for `Options.normalizeCase`. If element name is a valid HTML tag, it will be
|
|
47
|
+
* converted to lowercase. Otherwise, it will be converted to PascalCase.
|
|
48
|
+
*/
|
|
49
|
+
export declare function htmlOrPascalCase(name: string): string;
|
|
50
|
+
/**
|
|
51
|
+
* Default value for `Options.propsBlocks`. Uses the `confbox` library to parse the following
|
|
52
|
+
* languages: JSON5, JSON with comments (JSONC), YAML, JSON, TOML, and INI.
|
|
53
|
+
*/
|
|
54
|
+
export declare const viaConfbox: Record<string, (input: string) => unknown>;
|
|
55
|
+
/**
|
|
56
|
+
* Default value for `Options.slots`. Passes through the slot contents as-is and discards the slot
|
|
57
|
+
* name.
|
|
58
|
+
*/
|
|
59
|
+
export declare function passthrough(_name: string, children: SlotContents): BlockLevelContent[];
|
|
60
|
+
/**
|
|
61
|
+
* Value for `Options.slots` suitable for the Astro framework. Converts slots into slotted JSX
|
|
62
|
+
* fragments:
|
|
63
|
+
*
|
|
64
|
+
* ```jsx
|
|
65
|
+
* <Fragment slot="[slotName]">
|
|
66
|
+
* <... slot content ...>
|
|
67
|
+
* </Fragment>
|
|
68
|
+
* ```
|
|
69
|
+
*/
|
|
70
|
+
export declare function astroFragment(name: string, children: SlotContents): BlockLevelContent;
|
|
71
|
+
/**
|
|
72
|
+
* This Satteri plugin provides support for most of the Comark components syntax by translating
|
|
73
|
+
* them into MDX.
|
|
74
|
+
*
|
|
75
|
+
* Note that the two-colon container syntax isn't provided by this plugin, but instead by
|
|
76
|
+
* `satteri-comark/2colons`, which must be placed _before_ this plugin if you wish to use
|
|
77
|
+
* two-colon containers.
|
|
78
|
+
*
|
|
79
|
+
* There are some divergences from Comark:
|
|
80
|
+
* - Prop bindings `:prop="value"` are arbitrary JavaScript expressions, which makes them more
|
|
81
|
+
* flexible than Comark's JSON values/property paths.
|
|
82
|
+
* - You can spread props by setting the `::` or `...` prop to a JavaScript expression evaluating
|
|
83
|
+
* to the object you wish to spread.
|
|
84
|
+
* - `[props]` blocks support more languages by default (JSON5, JSONC, YAML, JSON, TOML, and INI).
|
|
85
|
+
* - `[props]` blocks must be code blocks, not frontmatter.
|
|
86
|
+
* - You can embed MDX `import/export` statements with ```` ```jsx|tsx [script] ```` code blocks.
|
|
87
|
+
* - You can embed JSX expressions with ```` ```jsx|tsx [embed] ```` code blocks.
|
|
88
|
+
* - Curly braces in bindings need to be escaped. This is a Satteri bug.
|
|
89
|
+
* - This plugin doesn't handle the setup of binding namespaces like `frontmatter`, `data`, etc.
|
|
90
|
+
*/
|
|
91
|
+
declare const _default: ({ normalizeCase, bindings, propsBlocks, scriptBlocks, embedBlocks, slots }?: Options) => MdastPluginDefinition;
|
|
92
|
+
//#endregion
|
|
93
|
+
export { _default as default };
|
package/dist/index.mjs
ADDED
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
import { i as wrapOne, n as shouldBeEvalString, r as splitParagraph } from "./util-ChyRgdb_.mjs";
|
|
2
|
+
import * as Confbox from "confbox";
|
|
3
|
+
import htmlTagsArray from "html-tags";
|
|
4
|
+
import { defineMdastPlugin } from "satteri";
|
|
5
|
+
import { pascalCase } from "tiny-case";
|
|
6
|
+
import { u } from "unist-builder";
|
|
7
|
+
//#region src/index.ts
|
|
8
|
+
const htmlTags = new Set(htmlTagsArray);
|
|
9
|
+
/**
|
|
10
|
+
* Default value for `Options.normalizeCase`. If element name is a valid HTML tag, it will be
|
|
11
|
+
* converted to lowercase. Otherwise, it will be converted to PascalCase.
|
|
12
|
+
*/
|
|
13
|
+
function htmlOrPascalCase(name) {
|
|
14
|
+
if (htmlTags.has(name.toLowerCase())) return name.toLowerCase();
|
|
15
|
+
return pascalCase(name);
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Default value for `Options.propsBlocks`. Uses the `confbox` library to parse the following
|
|
19
|
+
* languages: JSON5, JSON with comments (JSONC), YAML, JSON, TOML, and INI.
|
|
20
|
+
*/
|
|
21
|
+
const viaConfbox = {
|
|
22
|
+
json5: Confbox.parseJSON5,
|
|
23
|
+
jsonc: Confbox.parseJSONC,
|
|
24
|
+
yaml: Confbox.parseYAML,
|
|
25
|
+
json: Confbox.parseJSON,
|
|
26
|
+
toml: Confbox.parseTOML,
|
|
27
|
+
ini: Confbox.parseINI
|
|
28
|
+
};
|
|
29
|
+
/**
|
|
30
|
+
* Default value for `Options.slots`. Passes through the slot contents as-is and discards the slot
|
|
31
|
+
* name.
|
|
32
|
+
*/
|
|
33
|
+
function passthrough(_name, children) {
|
|
34
|
+
if (children.type === "inline") return [u("paragraph", children.contents)];
|
|
35
|
+
else return children.contents;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Value for `Options.slots` suitable for the Astro framework. Converts slots into slotted JSX
|
|
39
|
+
* fragments:
|
|
40
|
+
*
|
|
41
|
+
* ```jsx
|
|
42
|
+
* <Fragment slot="[slotName]">
|
|
43
|
+
* <... slot content ...>
|
|
44
|
+
* </Fragment>
|
|
45
|
+
* ```
|
|
46
|
+
*/
|
|
47
|
+
function astroFragment(name, children) {
|
|
48
|
+
return u("mdxJsxFlowElement", {
|
|
49
|
+
name: "Fragment",
|
|
50
|
+
attributes: [u("mdxJsxAttribute", { name: "slot" }, name)]
|
|
51
|
+
}, children.contents);
|
|
52
|
+
}
|
|
53
|
+
function makeAttrs(attrs, bindings) {
|
|
54
|
+
return Object.entries(attrs ?? {}).map(([name, value]) => {
|
|
55
|
+
if (bindings && (name === "..." || name === "::")) return u("mdxJsxExpressionAttribute", `...(${shouldBeEvalString(value)})`);
|
|
56
|
+
if (bindings && name.startsWith(":")) return u("mdxJsxAttribute", {
|
|
57
|
+
name: name.slice(1),
|
|
58
|
+
value: u("mdxJsxAttributeValueExpression", shouldBeEvalString(value))
|
|
59
|
+
});
|
|
60
|
+
if (typeof value === "string") return u("mdxJsxAttribute", {
|
|
61
|
+
name,
|
|
62
|
+
value
|
|
63
|
+
});
|
|
64
|
+
return u("mdxJsxAttribute", {
|
|
65
|
+
name,
|
|
66
|
+
value: u("mdxJsxAttributeValueExpression", JSON.stringify(value))
|
|
67
|
+
});
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* This Satteri plugin provides support for most of the Comark components syntax by translating
|
|
72
|
+
* them into MDX.
|
|
73
|
+
*
|
|
74
|
+
* Note that the two-colon container syntax isn't provided by this plugin, but instead by
|
|
75
|
+
* `satteri-comark/2colons`, which must be placed _before_ this plugin if you wish to use
|
|
76
|
+
* two-colon containers.
|
|
77
|
+
*
|
|
78
|
+
* There are some divergences from Comark:
|
|
79
|
+
* - Prop bindings `:prop="value"` are arbitrary JavaScript expressions, which makes them more
|
|
80
|
+
* flexible than Comark's JSON values/property paths.
|
|
81
|
+
* - You can spread props by setting the `::` or `...` prop to a JavaScript expression evaluating
|
|
82
|
+
* to the object you wish to spread.
|
|
83
|
+
* - `[props]` blocks support more languages by default (JSON5, JSONC, YAML, JSON, TOML, and INI).
|
|
84
|
+
* - `[props]` blocks must be code blocks, not frontmatter.
|
|
85
|
+
* - You can embed MDX `import/export` statements with ```` ```jsx|tsx [script] ```` code blocks.
|
|
86
|
+
* - You can embed JSX expressions with ```` ```jsx|tsx [embed] ```` code blocks.
|
|
87
|
+
* - Curly braces in bindings need to be escaped. This is a Satteri bug.
|
|
88
|
+
* - This plugin doesn't handle the setup of binding namespaces like `frontmatter`, `data`, etc.
|
|
89
|
+
*/
|
|
90
|
+
var src_default = ({ normalizeCase = htmlOrPascalCase, bindings = true, propsBlocks = viaConfbox, scriptBlocks = true, embedBlocks = true, slots = passthrough } = {}) => defineMdastPlugin({
|
|
91
|
+
name: "comark-mdx",
|
|
92
|
+
code(node) {
|
|
93
|
+
if (scriptBlocks && node.meta?.trim() === "[script]") return u("mdxjsEsm", node.value);
|
|
94
|
+
if (embedBlocks && node.meta?.trim() === "[embed]") return u("mdxFlowExpression", node.value);
|
|
95
|
+
},
|
|
96
|
+
containerDirective(node, ctx) {
|
|
97
|
+
const label = node.children.find((child) => !!(child.data && "directiveLabel" in child.data));
|
|
98
|
+
let attributes = node.attributes;
|
|
99
|
+
const children = node.children.filter((child) => !(child.data && "directiveLabel" in child.data));
|
|
100
|
+
if (propsBlocks && children.length > 0 && children[0].type === "code" && children[0].meta?.trim() === "[props]" && children[0].lang && children[0].lang in propsBlocks) {
|
|
101
|
+
const props = children[0];
|
|
102
|
+
const parsed = propsBlocks[children[0].lang](props.value);
|
|
103
|
+
if (typeof parsed !== "object" || parsed === null) {
|
|
104
|
+
ctx.report({
|
|
105
|
+
node: props,
|
|
106
|
+
severity: "warning",
|
|
107
|
+
message: `Invalid parsed value for props block: ${props.value}. This is ignored.`
|
|
108
|
+
});
|
|
109
|
+
console.warn(`Invalid parsed value for props block: ${props.value}. This is ignored.`);
|
|
110
|
+
} else attributes = {
|
|
111
|
+
...attributes,
|
|
112
|
+
...parsed
|
|
113
|
+
};
|
|
114
|
+
children.shift();
|
|
115
|
+
}
|
|
116
|
+
const newChildren = [];
|
|
117
|
+
let slotName = null;
|
|
118
|
+
let inside = {
|
|
119
|
+
type: "inline",
|
|
120
|
+
contents: []
|
|
121
|
+
};
|
|
122
|
+
const pushBlock = (block) => {
|
|
123
|
+
if (inside.type === "block") inside.contents.push(block);
|
|
124
|
+
else inside = {
|
|
125
|
+
type: "block",
|
|
126
|
+
contents: [...inside.contents.length ? [u("paragraph", inside.contents)] : [], block]
|
|
127
|
+
};
|
|
128
|
+
};
|
|
129
|
+
const pushInlines = (content) => {
|
|
130
|
+
if (content.length === 0) return;
|
|
131
|
+
if (inside.type === "block") inside.contents.push(u("paragraph", content));
|
|
132
|
+
else inside.contents.push(...content);
|
|
133
|
+
};
|
|
134
|
+
const commitSlot = () => {
|
|
135
|
+
if (inside.contents.length === 0) return;
|
|
136
|
+
if (slotName) newChildren.push(...wrapOne(slots(slotName, inside)));
|
|
137
|
+
else newChildren.push(...passthrough("", inside));
|
|
138
|
+
};
|
|
139
|
+
for (let blockIx = 0; blockIx < children.length; blockIx++) {
|
|
140
|
+
const block = children[blockIx];
|
|
141
|
+
if (block.type !== "paragraph") {
|
|
142
|
+
pushBlock(block);
|
|
143
|
+
continue;
|
|
144
|
+
}
|
|
145
|
+
const split = splitParagraph(block, (line) => /^#\S/.test(line));
|
|
146
|
+
if (!split) {
|
|
147
|
+
pushBlock(block);
|
|
148
|
+
continue;
|
|
149
|
+
}
|
|
150
|
+
const [before, target, after] = split;
|
|
151
|
+
pushInlines(before);
|
|
152
|
+
commitSlot();
|
|
153
|
+
slotName = target.slice(1);
|
|
154
|
+
inside = {
|
|
155
|
+
type: "inline",
|
|
156
|
+
contents: []
|
|
157
|
+
};
|
|
158
|
+
pushInlines(after);
|
|
159
|
+
}
|
|
160
|
+
commitSlot();
|
|
161
|
+
if (label) newChildren.unshift(...wrapOne(slots("label", {
|
|
162
|
+
type: "inline",
|
|
163
|
+
contents: label.children
|
|
164
|
+
})));
|
|
165
|
+
return u("mdxJsxFlowElement", {
|
|
166
|
+
name: normalizeCase(node.name),
|
|
167
|
+
attributes: makeAttrs(attributes, bindings),
|
|
168
|
+
data: node.data
|
|
169
|
+
}, newChildren);
|
|
170
|
+
},
|
|
171
|
+
leafDirective(node) {
|
|
172
|
+
return u("mdxJsxFlowElement", {
|
|
173
|
+
name: normalizeCase(node.name),
|
|
174
|
+
attributes: makeAttrs(node.attributes, bindings),
|
|
175
|
+
data: node.data
|
|
176
|
+
}, node.children);
|
|
177
|
+
},
|
|
178
|
+
textDirective(node) {
|
|
179
|
+
return u("mdxJsxTextElement", {
|
|
180
|
+
name: normalizeCase(node.name),
|
|
181
|
+
attributes: makeAttrs(node.attributes, bindings),
|
|
182
|
+
data: node.data
|
|
183
|
+
}, node.children);
|
|
184
|
+
}
|
|
185
|
+
});
|
|
186
|
+
//#endregion
|
|
187
|
+
export { astroFragment, src_default as default, htmlOrPascalCase, passthrough, viaConfbox };
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { u } from "unist-builder";
|
|
2
|
+
//#region src/util.ts
|
|
3
|
+
function omit(obj, ...keys) {
|
|
4
|
+
return Object.fromEntries(Object.entries(obj).filter(([key]) => !keys.includes(key)));
|
|
5
|
+
}
|
|
6
|
+
function wrapOne(x) {
|
|
7
|
+
return Array.isArray(x) ? x : [x];
|
|
8
|
+
}
|
|
9
|
+
function shouldBeEvalString(x) {
|
|
10
|
+
return typeof x === "string" ? x.replaceAll("\\{", "{").replaceAll("\\}", "}") : JSON.stringify(x);
|
|
11
|
+
}
|
|
12
|
+
function splitParagraph(node, test) {
|
|
13
|
+
const before = [];
|
|
14
|
+
for (let inlineIx = 0; inlineIx < node.children.length; inlineIx++) {
|
|
15
|
+
const inline = node.children[inlineIx];
|
|
16
|
+
if (inline.type === "text") {
|
|
17
|
+
const lines = inline.value.split("\n");
|
|
18
|
+
const splitIdx = lines.map((line) => line.trim()).findIndex(test);
|
|
19
|
+
if (splitIdx === -1) {
|
|
20
|
+
before.push(inline);
|
|
21
|
+
continue;
|
|
22
|
+
}
|
|
23
|
+
if (splitIdx !== 0) before.push(u("text", lines.slice(0, splitIdx).join("\n")));
|
|
24
|
+
const after = [...splitIdx === lines.length - 1 ? [] : [u("text", lines.slice(splitIdx + 1).join("\n"))], ...node.children.slice(inlineIx + 1)];
|
|
25
|
+
return [
|
|
26
|
+
before,
|
|
27
|
+
lines[splitIdx].trim(),
|
|
28
|
+
after
|
|
29
|
+
];
|
|
30
|
+
}
|
|
31
|
+
before.push(inline);
|
|
32
|
+
}
|
|
33
|
+
return null;
|
|
34
|
+
}
|
|
35
|
+
//#endregion
|
|
36
|
+
export { wrapOne as i, shouldBeEvalString as n, splitParagraph as r, omit as t };
|
package/package.json
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "satteri-comark",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"author": "daylily <i@dayli.ly>",
|
|
5
|
+
"license": "BSD-3-Clause",
|
|
6
|
+
"description": "Support for Comark syntax in Sätteri",
|
|
7
|
+
"homepage": "https://github.com/coclique/satteri-comark",
|
|
8
|
+
"bugs": "https://github.com/coclique/satteri-comark/issues",
|
|
9
|
+
"repository": {
|
|
10
|
+
"type": "git",
|
|
11
|
+
"url": "github:coclique/satteri-comark"
|
|
12
|
+
},
|
|
13
|
+
"keywords": [
|
|
14
|
+
"satteri",
|
|
15
|
+
"markdown",
|
|
16
|
+
"mdast",
|
|
17
|
+
"directive",
|
|
18
|
+
"mdx",
|
|
19
|
+
"comark"
|
|
20
|
+
],
|
|
21
|
+
"type": "module",
|
|
22
|
+
"sideEffects": false,
|
|
23
|
+
"files": [
|
|
24
|
+
"dist"
|
|
25
|
+
],
|
|
26
|
+
"exports": {
|
|
27
|
+
".": {
|
|
28
|
+
"import": "./dist/index.mjs",
|
|
29
|
+
"types": "./dist/index.d.mts"
|
|
30
|
+
},
|
|
31
|
+
"./2colons": {
|
|
32
|
+
"import": "./dist/2colons.mjs",
|
|
33
|
+
"types": "./dist/2colons.d.mts"
|
|
34
|
+
}
|
|
35
|
+
},
|
|
36
|
+
"devDependencies": {
|
|
37
|
+
"@ianvs/prettier-plugin-sort-imports": "^4.7.1",
|
|
38
|
+
"prettier": "^3.9.6",
|
|
39
|
+
"satteri": "^0.10.5",
|
|
40
|
+
"tsdown": "^0.23.0",
|
|
41
|
+
"typescript": "^6.0.3",
|
|
42
|
+
"vitest": "^5.0.0"
|
|
43
|
+
},
|
|
44
|
+
"dependencies": {
|
|
45
|
+
"@types/mdast": "^4.0.4",
|
|
46
|
+
"confbox": "^0.3.1",
|
|
47
|
+
"html-tags": "^5.1.0",
|
|
48
|
+
"tiny-case": "^1.0.3",
|
|
49
|
+
"unist-builder": "^4.0.0"
|
|
50
|
+
},
|
|
51
|
+
"peerDependencies": {
|
|
52
|
+
"satteri": "^0.10.5"
|
|
53
|
+
},
|
|
54
|
+
"scripts": {
|
|
55
|
+
"build": "tsdown",
|
|
56
|
+
"check": "tsc --noEmit",
|
|
57
|
+
"test": "vitest"
|
|
58
|
+
}
|
|
59
|
+
}
|