@kubb/parser-md 5.20.0 → 5.20.2

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/dist/index.cjs CHANGED
@@ -33,7 +33,7 @@ const parserMd = (0, _kubb_core.defineExtension)({
33
33
  kind: "parser",
34
34
  meta: {
35
35
  name: "markdown",
36
- version: "5.20.0",
36
+ version: "5.20.2",
37
37
  compatibility: {
38
38
  "kubb": ">=5.8.3",
39
39
  "node": ">=22.22"
package/dist/index.js CHANGED
@@ -32,7 +32,7 @@ const parserMd = defineExtension({
32
32
  kind: "parser",
33
33
  meta: {
34
34
  name: "markdown",
35
- version: "5.20.0",
35
+ version: "5.20.2",
36
36
  compatibility: {
37
37
  "kubb": ">=5.8.3",
38
38
  "node": ">=22.22"
package/docs/options.md CHANGED
@@ -1,18 +1,16 @@
1
1
  # Options
2
2
 
3
- `parserMd()` takes no options. You control its output through file metadata, such as the YAML frontmatter at the top of a generated page.
3
+ `parserMd()` takes no options. A plugin controls each Markdown file through its metadata, such as the YAML frontmatter.
4
4
 
5
5
  ## Frontmatter
6
6
 
7
- Set `file.meta.frontmatter` inside a plugin. Any serializable object becomes a YAML block at the top of the generated page.
7
+ Set `meta.frontmatter` on a file a plugin creates. Kubb writes any serializable object as a YAML block at the top of the page.
8
8
 
9
- ::field-group
10
-
11
- :::field{name="meta.frontmatter" type="Record<string, unknown> | null"}
12
- YAML frontmatter prepended to the generated Markdown file.
13
- :::
14
-
15
- ::
9
+ | | |
10
+ | -------- | --------------------------------- |
11
+ | Field | `file.meta.frontmatter` |
12
+ | Type | `Record<string, unknown> \| null` |
13
+ | Required | `false` |
16
14
 
17
15
  ::code-group
18
16
 
@@ -40,6 +38,9 @@ Endpoints generated from the OpenAPI spec.
40
38
 
41
39
  ::
42
40
 
43
- An empty object or `null` writes no frontmatter. A file banner, when set, goes above the frontmatter.
41
+ - `null` or an empty object writes no frontmatter.
42
+ - A file `banner` goes above the frontmatter, and a `footer` goes below the content. Tools such as Jekyll read frontmatter only at the top of the file, so leave `banner` unset on a file with frontmatter.
43
+
44
+ ## print
44
45
 
45
46
  `parserMd().print(...parts)` joins Markdown strings with blank lines and skips empty ones. It takes strings only, so frontmatter always comes from `meta.frontmatter`.
package/docs/overview.md CHANGED
@@ -1,20 +1,31 @@
1
1
  # Markdown
2
2
 
3
- The Markdown parser joins a file's source blocks as plain Markdown, separated by blank lines. When a file sets `meta.frontmatter`, the parser writes that object as YAML frontmatter above the content, after the file banner if one is set.
3
+ The Markdown parser writes the `.md` and `.markdown` files that plugins generate, with YAML frontmatter from each file's `meta.frontmatter`.
4
+
5
+ It joins each file's source blocks with blank lines and writes the frontmatter above the content.
4
6
 
5
7
  ## Setup
6
8
 
7
- Kubb registers the parser by default, next to `parserTs` and `parserTsx`, in `defineConfig` and in the bundler integrations, so no setup is needed. Add it yourself only when you set a custom `parsers` array, because that array replaces the default set. List every parser your plugins need. Files that no parser claims are written as their source text only, without imports, exports, banner, or footer.
9
+ No setup is needed. `defineConfig` and the bundler integrations register `parserMd()` by default, next to `parserTs()` and `parserTsx()`.
10
+
11
+ > [!WARNING]
12
+ > A custom `parsers` array replaces the default set, so add `parserMd()` to it yourself and list every parser your plugins need. A file that no parser claims is written as its source text only, without imports, exports, banner, or footer.
8
13
 
9
14
  ## Options worth knowing
10
15
 
11
- The parser takes no options. Plugins control the output through `meta.frontmatter` on each file, and an empty object writes none.
16
+ The parser takes no options. A plugin controls the output per file:
12
17
 
13
- See [Options](https://kubb.dev/extensions/kubb-labs/parser-md/options) for how a plugin sets frontmatter.
18
+ | File setting | Default | What it does |
19
+ | ----------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------ |
20
+ | [`meta.frontmatter`](https://kubb.dev/extensions/kubb-labs/parser-md/options#frontmatter) | None | Writes the object as YAML frontmatter. `null` or `{}` writes none. |
21
+ | `banner` | None | Goes above the frontmatter. |
22
+ | `footer` | None | Goes below the content. |
14
23
 
15
24
  ## Example
16
25
 
17
- The config below sets a custom `parsers` array and keeps the Markdown parser in it.
26
+ This config sets a custom `parsers` array that keeps the Markdown parser. A plugin file with `meta.frontmatter` then prints like this:
27
+
28
+ ::code-group
18
29
 
19
30
  ```typescript [kubb.config.ts]
20
31
  import { defineConfig } from 'kubb/config'
@@ -25,13 +36,18 @@ import { pluginTs } from '@kubb/plugin-ts'
25
36
  export default defineConfig({
26
37
  input: './petStore.yaml',
27
38
  output: { path: './src/gen' },
28
- parsers: [
29
- parserTs(),
30
- parserTsx(),
31
- parserMd(),
32
- ],
33
- plugins: [
34
- pluginTs(),
35
- ],
39
+ parsers: [parserTs(), parserTsx(), parserMd()],
40
+ plugins: [pluginTs()],
36
41
  })
37
42
  ```
43
+
44
+ ```md [src/gen/README.md]
45
+ ---
46
+ title: API Reference
47
+ layout: doc
48
+ ---
49
+
50
+ Endpoints generated from the OpenAPI spec.
51
+ ```
52
+
53
+ ::
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubb/parser-md",
3
- "version": "5.20.0",
3
+ "version": "5.20.2",
4
4
  "description": "Markdown source file parser for Kubb. Converts the universal AST to `.md` source and prepends YAML frontmatter from the file meta.",
5
5
  "keywords": [
6
6
  "codegen",
@@ -65,8 +65,8 @@
65
65
  "registry": "https://registry.npmjs.org/"
66
66
  },
67
67
  "dependencies": {
68
- "@kubb/ast": "^5.20.0",
69
- "@kubb/core": "^5.20.0",
68
+ "@kubb/ast": "^5.20.2",
69
+ "@kubb/core": "^5.20.2",
70
70
  "yaml": "^2.9.1"
71
71
  },
72
72
  "engines": {