@graphql-markdown/formatters 1.2.2 → 1.2.3

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 CHANGED
@@ -83,7 +83,7 @@ For frameworks not listed above, create a custom MDX module. See the [Integratio
83
83
 
84
84
  ### Formatter contract
85
85
 
86
- A formatter module exports `createMDXFormatter` and any subset of the standard formatter functions (`formatMDXBadge`, `formatMDXAdmonition`, `formatMDXBullet`, `formatMDXDetails`, `formatMDXFrontmatter`, `formatMDXLink`, `formatMDXNameEntity`, `formatMDXSpecifiedByLink`). Optional exports include `mdxDeclaration`, `mdxExtension`, and lifecycle hooks.
86
+ A formatter module exports `createMDXFormatter` and any subset of the standard formatter functions (`formatMDXBadge`, `formatMDXAdmonition`, `formatMDXBullet`, `formatMDXDetails`, `formatMDXFrontmatter`, `formatMDXLink`, `formatMDXNameEntity`, `formatMDXPermalink`, `formatMDXSpecifiedByLink`). Optional exports include `formatMDXTitle` (a visible page title printed after the front matter), `mdxDeclaration`, `mdxExtension`, and lifecycle hooks.
87
87
 
88
88
  See the [Integration Guide](https://graphql-markdown.dev/docs/advanced/integration-with-frameworks#custom-mdx-formatter) for the full contract, type signatures, and the `formatMDXDetails` `\r` delimiter invariant.
89
89
 
@@ -64,6 +64,7 @@ export declare const formatMDXNameEntity: (name: string, parentType?: Maybe<stri
64
64
  /**
65
65
  * Formats a "specified by" link as an HTML `<span>` with a `gqlmd-mdx-specifiedby` CSS class
66
66
  * containing an anchor that opens in a new tab.
67
+ * The URL is encoded as HTML character references for the `href` and `title` attributes.
67
68
  * @param url - URL to the specification
68
69
  * @returns Formatted specification link string
69
70
  */
@@ -88,7 +89,7 @@ export declare const formatMDXEscapedPermalink: (id: string) => MDXString;
88
89
  * Formats a permalink for a section header using the classic `{#id}` syntax.
89
90
  *
90
91
  * This is the syntax supported by most Markdown-based generators (Hugo,
91
- * mdBook, DocFX, MkDocs with `attr_list`). Presets targeting a framework that
92
+ * mdBook, MkDocs with `attr_list`). Presets targeting a framework that
92
93
  * expects another syntax override this function.
93
94
  *
94
95
  * @param id - The ID of the section header
@@ -1 +1 @@
1
- {"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAWjC;;;;GAIG;AACH,eAAO,MAAM,cAAc,UAAW,KAAK,KAAG,SAE7C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,gCACD,cAAc,SACpC,KAAK,CAAC,QAAQ,CAAC,KACrB,SAEF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,qBAAgB,SAE3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,6BAG1B,iBAAiB,KAAG,SAEtB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,WACvB,KAAK,CAAC,kBAAkB,CAAC,aACtB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAMF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,cAC7B,KAAK,CAAC,MAAM,EAAE,CAAC,4BAEzB,SAMF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAU,QAAQ,KAAG,QAE9C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,SACxB,MAAM,eACC,KAAK,CAAC,MAAM,CAAC,KACzB,SAKF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAS,MAAM,KAAG,SAEtD,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB,OAAQ,MAAM,KAAG,SAEtD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,OAAQ,MAAM,KAAG,SAE/C,CAAC"}
1
+ {"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAajC;;;;GAIG;AACH,eAAO,MAAM,cAAc,UAAW,KAAK,KAAG,SAE7C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,gCACD,cAAc,SACpC,KAAK,CAAC,QAAQ,CAAC,KACrB,SAEF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,qBAAgB,SAE3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,6BAG1B,iBAAiB,KAAG,SAEtB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,WACvB,KAAK,CAAC,kBAAkB,CAAC,aACtB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAMF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,cAC7B,KAAK,CAAC,MAAM,EAAE,CAAC,4BAEzB,SAMF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAU,QAAQ,KAAG,QAE9C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,SACxB,MAAM,eACC,KAAK,CAAC,MAAM,CAAC,KACzB,SAKF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,QAAS,MAAM,KAAG,SAGtD,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB,OAAQ,MAAM,KAAG,SAEtD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,OAAQ,MAAM,KAAG,SAE/C,CAAC"}
package/dist/defaults.js CHANGED
@@ -11,6 +11,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
11
11
  exports.formatMDXPermalink = exports.formatMDXEscapedPermalink = exports.formatMDXSpecifiedByLink = exports.formatMDXNameEntity = exports.formatMDXLink = exports.formatMDXFrontmatterTitleOnly = exports.formatMDXFrontmatter = exports.formatMDXDetails = exports.formatMDXBullet = exports.formatMDXAdmonition = exports.formatMDXBadge = void 0;
12
12
  const helpers_1 = require("@graphql-markdown/helpers");
13
13
  const utils_1 = require("@graphql-markdown/utils");
14
+ const escape_ts_1 = require("./escape.js");
14
15
  /**
15
16
  * Formats a badge using an HTML `<mark>` element with a `gqlmd-mdx-badge` CSS class.
16
17
  * @param badge - Badge data containing the text to display
@@ -99,11 +100,13 @@ exports.formatMDXNameEntity = formatMDXNameEntity;
99
100
  /**
100
101
  * Formats a "specified by" link as an HTML `<span>` with a `gqlmd-mdx-specifiedby` CSS class
101
102
  * containing an anchor that opens in a new tab.
103
+ * The URL is encoded as HTML character references for the `href` and `title` attributes.
102
104
  * @param url - URL to the specification
103
105
  * @returns Formatted specification link string
104
106
  */
105
107
  const formatMDXSpecifiedByLink = (url) => {
106
- return `<span class="gqlmd-mdx-specifiedby">Specification<a class="gqlmd-mdx-specifiedby-link" target="_blank" href="${url}" title="Specified by ${url}">⎘</a></span>`;
108
+ const safeURL = (0, escape_ts_1.escapeHTMLAttribute)(url);
109
+ return `<span class="gqlmd-mdx-specifiedby">Specification<a class="gqlmd-mdx-specifiedby-link" target="_blank" href="${safeURL}" title="Specified by ${safeURL}">⎘</a></span>`;
107
110
  };
108
111
  exports.formatMDXSpecifiedByLink = formatMDXSpecifiedByLink;
109
112
  /**
@@ -129,7 +132,7 @@ exports.formatMDXEscapedPermalink = formatMDXEscapedPermalink;
129
132
  * Formats a permalink for a section header using the classic `{#id}` syntax.
130
133
  *
131
134
  * This is the syntax supported by most Markdown-based generators (Hugo,
132
- * mdBook, DocFX, MkDocs with `attr_list`). Presets targeting a framework that
135
+ * mdBook, MkDocs with `attr_list`). Presets targeting a framework that
133
136
  * expects another syntax override this function.
134
137
  *
135
138
  * @param id - The ID of the section header
@@ -18,11 +18,19 @@ export declare const BADGE_CLASS_MAP: Record<string, string>;
18
18
  export declare const formatMDXBadge: ({ text, classname }: Badge) => MDXString;
19
19
  /**
20
20
  * Formats an admonition using DocFX alert syntax (`> [!TYPE]`).
21
- * @param admonition - Admonition data with text, title, and type
21
+ *
22
+ * DocFX renders its own heading for each alert type (Note, Warning, ...), and
23
+ * the syntax has no slot for a custom title, so the admonition title is not
24
+ * printed. Blank lines around the text are dropped and blank lines within it
25
+ * collapse to a single `>` paragraph separator.
26
+ *
27
+ * @see https://dotnet.github.io/docfx/docs/markdown.html#alerts
28
+ *
29
+ * @param admonition - Admonition data with text and type
22
30
  * @param _meta - Unused metadata parameter
23
31
  * @returns Formatted admonition string
24
32
  */
25
- export declare const formatMDXAdmonition: ({ text, title, type }: AdmonitionType, _meta: Maybe<MetaInfo>) => MDXString;
33
+ export declare const formatMDXAdmonition: ({ text, type }: AdmonitionType, _meta: Maybe<MetaInfo>) => MDXString;
26
34
  /**
27
35
  * Formats YAML front matter, injecting a `uid` field required by DocFX
28
36
  * for cross-reference resolution between pages.
@@ -31,13 +39,38 @@ export declare const formatMDXAdmonition: ({ text, title, type }: AdmonitionType
31
39
  * @returns Formatted front matter block, or empty string if no lines provided
32
40
  */
33
41
  export declare const formatMDXFrontmatter: (props: Maybe<FrontMatterOptions>, formatted: Maybe<string[]>) => MDXString;
42
+ /**
43
+ * Formats the page title as a visible `# Title` heading.
44
+ *
45
+ * DocFX only uses the front matter `title` for the document `<title>`; the
46
+ * page heading comes from the Markdown H1, so without it generated pages
47
+ * have no visible title.
48
+ *
49
+ * @see https://dotnet.github.io/docfx/docs/markdown.html
50
+ *
51
+ * @param title - The page title
52
+ * @returns `# Title` heading
53
+ */
54
+ export declare const formatMDXTitle: (title: string) => MDXString;
34
55
  /**
35
56
  * Returns the link unchanged — DocFX resolves `.md` links natively.
36
57
  * @param link - Link data with URL and text
37
58
  * @returns The link unchanged
38
59
  */
39
60
  export declare const formatMDXLink: (link: TypeLink) => TypeLink;
40
- export { formatMDXBullet, formatMDXDetails, formatMDXNameEntity, formatMDXPermalink, formatMDXSpecifiedByLink, } from "../defaults.ts";
61
+ /**
62
+ * Formats a permalink for a section header as an empty HTML anchor.
63
+ *
64
+ * DocFX does not support the `{#id}` heading id syntax unless the Markdig
65
+ * `attributes` extension is enabled: the braces are printed as text, and the
66
+ * heading id is generated from the whole heading, badges included. An inline
67
+ * anchor gives every field and argument a stable id derived from its name only.
68
+ *
69
+ * @param id - The ID of the section header
70
+ * @returns Formatted permalink string
71
+ */
72
+ export declare const formatMDXPermalink: (id: string) => MDXString;
73
+ export { formatMDXBullet, formatMDXDetails, formatMDXNameEntity, formatMDXSpecifiedByLink, } from "../defaults.ts";
41
74
  /**
42
75
  * Creates a DocFX formatter.
43
76
  * @param _meta - Unused metadata parameter
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docfx/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,SAAS,EACT,kBAAkB,EAClB,KAAK,EAEL,SAAS,EACT,QAAQ,EACR,sBAAsB,EACtB,QAAQ,EACT,MAAM,yBAAyB,CAAC;AA+BjC,sFAAsF;AACtF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAIlD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,wBAAyB,KAAK,KAAG,SAI3D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAIF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,UACxB,KAAK,CAAC,kBAAkB,CAAC,aACrB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAgBF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAU,QAAQ,KAAG,QAE9C,CAAC;AAEF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAY5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAG,KAAc,CAAC;AA0P3C,eAAO,MAAM,2BAA2B,EAAE,sBAiDzC,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docfx/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,SAAS,EACT,kBAAkB,EAClB,KAAK,EAEL,SAAS,EACT,QAAQ,EACR,sBAAsB,EACtB,QAAQ,EACT,MAAM,yBAAyB,CAAC;AA8BjC,sFAAsF;AACtF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAIlD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,wBAAyB,KAAK,KAAG,SAI3D,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,mBACd,cAAc,SACvB,KAAK,CAAC,QAAQ,CAAC,KACrB,SAYF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,UACxB,KAAK,CAAC,kBAAkB,CAAC,aACrB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAgBF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,UAAW,MAAM,KAAG,SAE9C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAU,QAAQ,KAAG,QAE9C,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,OAAQ,MAAM,KAAG,SAE/C,CAAC;AAEF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAa5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAG,KAAc,CAAC;AAyS3C,eAAO,MAAM,2BAA2B,EAAE,sBAiDzC,CAAC"}
@@ -9,7 +9,7 @@
9
9
  * @packageDocumentation
10
10
  */
11
11
  Object.defineProperty(exports, "__esModule", { value: true });
12
- exports.afterRenderTypeEntitiesHook = exports.mdxExtension = exports.createMDXFormatter = exports.formatMDXSpecifiedByLink = exports.formatMDXPermalink = exports.formatMDXNameEntity = exports.formatMDXDetails = exports.formatMDXBullet = exports.formatMDXLink = exports.formatMDXFrontmatter = exports.formatMDXAdmonition = exports.formatMDXBadge = exports.BADGE_CLASS_MAP = void 0;
12
+ exports.afterRenderTypeEntitiesHook = exports.mdxExtension = exports.createMDXFormatter = exports.formatMDXSpecifiedByLink = exports.formatMDXNameEntity = exports.formatMDXDetails = exports.formatMDXBullet = exports.formatMDXPermalink = exports.formatMDXLink = exports.formatMDXTitle = exports.formatMDXFrontmatter = exports.formatMDXAdmonition = exports.formatMDXBadge = exports.BADGE_CLASS_MAP = void 0;
13
13
  const node_path_1 = require("node:path");
14
14
  const helpers_1 = require("@graphql-markdown/helpers");
15
15
  const utils_1 = require("@graphql-markdown/utils");
@@ -45,14 +45,30 @@ const formatMDXBadge = ({ text, classname }) => {
45
45
  exports.formatMDXBadge = formatMDXBadge;
46
46
  /**
47
47
  * Formats an admonition using DocFX alert syntax (`> [!TYPE]`).
48
- * @param admonition - Admonition data with text, title, and type
48
+ *
49
+ * DocFX renders its own heading for each alert type (Note, Warning, ...), and
50
+ * the syntax has no slot for a custom title, so the admonition title is not
51
+ * printed. Blank lines around the text are dropped and blank lines within it
52
+ * collapse to a single `>` paragraph separator.
53
+ *
54
+ * @see https://dotnet.github.io/docfx/docs/markdown.html#alerts
55
+ *
56
+ * @param admonition - Admonition data with text and type
49
57
  * @param _meta - Unused metadata parameter
50
58
  * @returns Formatted admonition string
51
59
  */
52
- const formatMDXAdmonition = ({ text, title, type }, _meta) => {
60
+ const formatMDXAdmonition = ({ text, type }, _meta) => {
53
61
  const alertType = ALERT_TYPE_MAP[type.toLowerCase()] ?? "NOTE";
54
- const titleLine = title ? `${utils_1.MARKDOWN_EOL}> **${title}**` : "";
55
- return `${utils_1.MARKDOWN_EOP}> [!${alertType}]${titleLine}${utils_1.MARKDOWN_EOL}${(0, helpers_1.quoteMarkdownLines)(text, utils_1.MARKDOWN_EOL)}${utils_1.MARKDOWN_EOL}`;
62
+ const paragraphs = text
63
+ .split(/(?:\r?\n[ \t]*){2,}/)
64
+ .map((paragraph) => {
65
+ return paragraph.trim();
66
+ })
67
+ .filter(Boolean);
68
+ const body = paragraphs.length
69
+ ? `${utils_1.MARKDOWN_EOL}${(0, helpers_1.quoteMarkdownLines)(paragraphs.join(utils_1.MARKDOWN_EOP), utils_1.MARKDOWN_EOL).replaceAll(/^> $/gm, ">")}`
70
+ : "";
71
+ return `${utils_1.MARKDOWN_EOP}> [!${alertType}]${body}${utils_1.MARKDOWN_EOP}`;
56
72
  };
57
73
  exports.formatMDXAdmonition = formatMDXAdmonition;
58
74
  /**
@@ -78,6 +94,22 @@ const formatMDXFrontmatter = (props, formatted) => {
78
94
  ].join(utils_1.MARKDOWN_EOL);
79
95
  };
80
96
  exports.formatMDXFrontmatter = formatMDXFrontmatter;
97
+ /**
98
+ * Formats the page title as a visible `# Title` heading.
99
+ *
100
+ * DocFX only uses the front matter `title` for the document `<title>`; the
101
+ * page heading comes from the Markdown H1, so without it generated pages
102
+ * have no visible title.
103
+ *
104
+ * @see https://dotnet.github.io/docfx/docs/markdown.html
105
+ *
106
+ * @param title - The page title
107
+ * @returns `# Title` heading
108
+ */
109
+ const formatMDXTitle = (title) => {
110
+ return `# ${title}`;
111
+ };
112
+ exports.formatMDXTitle = formatMDXTitle;
81
113
  /**
82
114
  * Returns the link unchanged — DocFX resolves `.md` links natively.
83
115
  * @param link - Link data with URL and text
@@ -87,11 +119,25 @@ const formatMDXLink = (link) => {
87
119
  return link;
88
120
  };
89
121
  exports.formatMDXLink = formatMDXLink;
122
+ /**
123
+ * Formats a permalink for a section header as an empty HTML anchor.
124
+ *
125
+ * DocFX does not support the `{#id}` heading id syntax unless the Markdig
126
+ * `attributes` extension is enabled: the braces are printed as text, and the
127
+ * heading id is generated from the whole heading, badges included. An inline
128
+ * anchor gives every field and argument a stable id derived from its name only.
129
+ *
130
+ * @param id - The ID of the section header
131
+ * @returns Formatted permalink string
132
+ */
133
+ const formatMDXPermalink = (id) => {
134
+ return `<a id="${id}"></a>`;
135
+ };
136
+ exports.formatMDXPermalink = formatMDXPermalink;
90
137
  var defaults_ts_2 = require("../defaults.js");
91
138
  Object.defineProperty(exports, "formatMDXBullet", { enumerable: true, get: function () { return defaults_ts_2.formatMDXBullet; } });
92
139
  Object.defineProperty(exports, "formatMDXDetails", { enumerable: true, get: function () { return defaults_ts_2.formatMDXDetails; } });
93
140
  Object.defineProperty(exports, "formatMDXNameEntity", { enumerable: true, get: function () { return defaults_ts_2.formatMDXNameEntity; } });
94
- Object.defineProperty(exports, "formatMDXPermalink", { enumerable: true, get: function () { return defaults_ts_2.formatMDXPermalink; } });
95
141
  Object.defineProperty(exports, "formatMDXSpecifiedByLink", { enumerable: true, get: function () { return defaults_ts_2.formatMDXSpecifiedByLink; } });
96
142
  /**
97
143
  * Creates a DocFX formatter.
@@ -107,8 +153,9 @@ const createMDXFormatter = (_meta) => {
107
153
  formatMDXFrontmatter: exports.formatMDXFrontmatter,
108
154
  formatMDXLink: exports.formatMDXLink,
109
155
  formatMDXNameEntity: defaults_ts_1.formatMDXNameEntity,
110
- formatMDXPermalink: defaults_ts_1.formatMDXPermalink,
156
+ formatMDXPermalink: exports.formatMDXPermalink,
111
157
  formatMDXSpecifiedByLink: defaults_ts_1.formatMDXSpecifiedByLink,
158
+ formatMDXTitle: exports.formatMDXTitle,
112
159
  };
113
160
  };
114
161
  exports.createMDXFormatter = createMDXFormatter;
@@ -197,22 +244,63 @@ const queueFileUpdate = async (filePath, update) => {
197
244
  writeQueue.set(filePath, next);
198
245
  return next;
199
246
  };
247
+ /** Href of a section index page, always listed first as its "Overview". */
248
+ const TOC_OVERVIEW_HREF = "index.md";
249
+ /**
250
+ * Parses the entries of a `toc.yml` written by {@link updateToc}.
251
+ */
252
+ const parseTocEntries = (content) => {
253
+ const entries = [];
254
+ for (const line of content.split(/\r?\n/)) {
255
+ if (line.startsWith("- name: ")) {
256
+ entries.push({ name: line.slice("- name: ".length), href: "" });
257
+ }
258
+ else if (line.startsWith(" href: ") && entries.length > 0) {
259
+ entries[entries.length - 1].href = line.slice(" href: ".length);
260
+ }
261
+ }
262
+ return entries;
263
+ };
264
+ /**
265
+ * Orders `toc.yml` entries deterministically: the section "Overview" first,
266
+ * then by name (case-insensitive), then by href.
267
+ *
268
+ * Pages are rendered concurrently, so the order in which entries are added
269
+ * changes from one build to the next.
270
+ */
271
+ const compareTocEntries = (a, b) => {
272
+ const aOverview = a.href === TOC_OVERVIEW_HREF;
273
+ const bOverview = b.href === TOC_OVERVIEW_HREF;
274
+ if (aOverview !== bOverview) {
275
+ return aOverview ? -1 : 1;
276
+ }
277
+ const byName = a.name.toLowerCase().localeCompare(b.name.toLowerCase(), "en");
278
+ if (byName !== 0) {
279
+ return byName;
280
+ }
281
+ return a.href.localeCompare(b.href, "en");
282
+ };
200
283
  /**
201
284
  * Updates the `toc.yml` file for a given directory with a new entry.
202
- * Ensures that multiple concurrent updates to the same file are queued.
285
+ * Ensures that multiple concurrent updates to the same file are queued, and
286
+ * keeps the entries sorted so the file does not depend on completion order.
203
287
  */
204
288
  const updateToc = async (tocFilePath, name, href, outputAdapter) => {
205
289
  await queueFileUpdate(tocFilePath, async () => {
206
- const entry = `- name: ${name}${utils_1.MARKDOWN_EOL} href: ${href}`;
207
290
  const existing = await (0, output_ts_1.readOptionalOutput)(tocFilePath, outputAdapter);
208
- if (typeof existing !== "string") {
209
- await (0, output_ts_1.writeOutput)(tocFilePath, entry + utils_1.MARKDOWN_EOL, outputAdapter);
210
- return;
211
- }
212
- if (existing.includes(`href: ${href}`)) {
291
+ const entries = typeof existing === "string" ? parseTocEntries(existing) : [];
292
+ if (entries.some((entry) => {
293
+ return entry.href === href;
294
+ })) {
213
295
  return;
214
296
  }
215
- await (0, output_ts_1.writeOutput)(tocFilePath, existing.trimEnd() + utils_1.MARKDOWN_EOL + entry + utils_1.MARKDOWN_EOL, outputAdapter);
297
+ const content = [...entries, { name, href }]
298
+ .sort(compareTocEntries)
299
+ .map((entry) => {
300
+ return `- name: ${entry.name}${utils_1.MARKDOWN_EOL} href: ${entry.href}${utils_1.MARKDOWN_EOL}`;
301
+ })
302
+ .join("");
303
+ await (0, output_ts_1.writeOutput)(tocFilePath, content, outputAdapter);
216
304
  });
217
305
  };
218
306
  // Tracks directories whose index.md has already been prepended to their toc.yml,
@@ -40,6 +40,7 @@ export declare const formatMDXBullet: (text?: string) => MDXString;
40
40
  export declare const formatMDXDetails: ({ dataOpen, dataClose, }: CollapsibleOption) => MDXString;
41
41
  /**
42
42
  * Formats a "specified by" link using the inline `<SpecifiedBy>` component.
43
+ * The URL is encoded as HTML character references for the `url` attribute.
43
44
  * @param url - URL to the specification
44
45
  * @returns Formatted SpecifiedBy component string
45
46
  */
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docusaurus/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,KAAK,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAsBjC,mEAAmE;AACnE,eAAO,MAAM,cAAc,EAAE,SAQf,CAAC;AAEf;;;;;GAKG;AACH,eAAO,MAAM,cAAc,wBAAyB,KAAK,KAAG,SAI3D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,QAC/B,KAAK,CAAC,QAAQ,CAAC,KACpB,SAQF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,UAAU,MAAM,KAAQ,SAEnD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,6BAG1B,iBAAiB,KAAG,SAItB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAAS,MAAM,KAAG,SAEtD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,SACxB,MAAM,eACC,KAAK,CAAC,MAAM,CAAC,KACzB,SAGF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,kBAAmB,QAAQ,KAAG,QAKvD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,WACvB,KAAK,CAAC,kBAAkB,CAAC,aACtB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAMF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,OACzB,MAAM,SACH,KAAK,CAAC,QAAQ,CAAC,KACrB,SAWF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,UAAW,KAAK,CAAC,QAAQ,CAAC,KAAG,SAmB3D,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docusaurus/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,KAAK,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAuBjC,mEAAmE;AACnE,eAAO,MAAM,cAAc,EAAE,SAQf,CAAC;AAEf;;;;;GAKG;AACH,eAAO,MAAM,cAAc,wBAAyB,KAAK,KAAG,SAI3D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,QAC/B,KAAK,CAAC,QAAQ,CAAC,KACpB,SAQF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,UAAU,MAAM,KAAQ,SAEnD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,6BAG1B,iBAAiB,KAAG,SAItB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAS,MAAM,KAAG,SAEtD,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,SACxB,MAAM,eACC,KAAK,CAAC,MAAM,CAAC,KACzB,SAGF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,kBAAmB,QAAQ,KAAG,QAKvD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,WACvB,KAAK,CAAC,kBAAkB,CAAC,aACtB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAMF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,OACzB,MAAM,SACH,KAAK,CAAC,QAAQ,CAAC,KACrB,SAWF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,UAAW,KAAK,CAAC,QAAQ,CAAC,KAAG,SAmB3D,CAAC"}
@@ -12,6 +12,7 @@ exports.createMDXFormatter = exports.formatMDXPermalink = exports.formatMDXFront
12
12
  const helpers_1 = require("@graphql-markdown/helpers");
13
13
  const utils_1 = require("@graphql-markdown/utils");
14
14
  const defaults_ts_1 = require("../defaults.js");
15
+ const escape_ts_1 = require("../escape.js");
15
16
  const version_ts_1 = require("../version.js");
16
17
  const LINK_MDX_EXTENSION = ".mdx";
17
18
  const DOCUSAURUS_FRAMEWORK = "docusaurus";
@@ -80,11 +81,12 @@ const formatMDXDetails = ({ dataOpen, dataClose, }) => {
80
81
  exports.formatMDXDetails = formatMDXDetails;
81
82
  /**
82
83
  * Formats a "specified by" link using the inline `<SpecifiedBy>` component.
84
+ * The URL is encoded as HTML character references for the `url` attribute.
83
85
  * @param url - URL to the specification
84
86
  * @returns Formatted SpecifiedBy component string
85
87
  */
86
88
  const formatMDXSpecifiedByLink = (url) => {
87
- return `<SpecifiedBy url="${url}"/>`;
89
+ return `<SpecifiedBy url="${(0, escape_ts_1.escapeHTMLAttribute)(url)}"/>`;
88
90
  };
89
91
  exports.formatMDXSpecifiedByLink = formatMDXSpecifiedByLink;
90
92
  /**
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Escaping helpers for values interpolated into generated markup.
3
+ *
4
+ * Each helper encodes a value for one output context. They are internal to
5
+ * the formatters package and are not part of the public API.
6
+ *
7
+ * @packageDocumentation
8
+ */
9
+ /**
10
+ * Escapes a value for use inside a double-quoted HTML attribute or an MDX/JSX
11
+ * string attribute. Both contexts decode character references, so the encoded
12
+ * value is read back unchanged while quotes, angle brackets, and curly braces
13
+ * cannot end the attribute or start markup. `&` is encoded first so that the
14
+ * other replacements are not double-encoded.
15
+ * @param value - Raw value to escape
16
+ * @returns Value with HTML-significant characters replaced by character references
17
+ */
18
+ export declare const escapeHTMLAttribute: (value: string) => string;
19
+ /**
20
+ * Percent-encodes characters that could end a Markdown link destination or
21
+ * start markup when the value is written as plain text. Whitespace is encoded
22
+ * as well, which keeps the value a single link destination. ASCII characters
23
+ * are encoded as `%XX` with uppercase hex; non-ASCII whitespace is encoded as
24
+ * UTF-8 percent sequences.
25
+ * @param value - Raw value to escape
26
+ * @returns Value with Markdown-significant characters percent-encoded
27
+ */
28
+ export declare const escapeMarkdownURL: (value: string) => string;
29
+ //# sourceMappingURL=escape.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"escape.d.ts","sourceRoot":"","sources":["../src/escape.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,UAAW,MAAM,KAAG,MASnD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,UAAW,MAAM,KAAG,MAOjD,CAAC"}
package/dist/escape.js ADDED
@@ -0,0 +1,50 @@
1
+ "use strict";
2
+ /**
3
+ * Escaping helpers for values interpolated into generated markup.
4
+ *
5
+ * Each helper encodes a value for one output context. They are internal to
6
+ * the formatters package and are not part of the public API.
7
+ *
8
+ * @packageDocumentation
9
+ */
10
+ Object.defineProperty(exports, "__esModule", { value: true });
11
+ exports.escapeMarkdownURL = exports.escapeHTMLAttribute = void 0;
12
+ const MARKDOWN_URL_UNSAFE_CHARS = /[\s"'()<>\\`[\]{}|^]/g;
13
+ /**
14
+ * Escapes a value for use inside a double-quoted HTML attribute or an MDX/JSX
15
+ * string attribute. Both contexts decode character references, so the encoded
16
+ * value is read back unchanged while quotes, angle brackets, and curly braces
17
+ * cannot end the attribute or start markup. `&` is encoded first so that the
18
+ * other replacements are not double-encoded.
19
+ * @param value - Raw value to escape
20
+ * @returns Value with HTML-significant characters replaced by character references
21
+ */
22
+ const escapeHTMLAttribute = (value) => {
23
+ return value
24
+ .replace(/&/g, "&amp;")
25
+ .replace(/"/g, "&quot;")
26
+ .replace(/'/g, "&#39;")
27
+ .replace(/</g, "&lt;")
28
+ .replace(/>/g, "&gt;")
29
+ .replace(/{/g, "&#123;")
30
+ .replace(/}/g, "&#125;");
31
+ };
32
+ exports.escapeHTMLAttribute = escapeHTMLAttribute;
33
+ /**
34
+ * Percent-encodes characters that could end a Markdown link destination or
35
+ * start markup when the value is written as plain text. Whitespace is encoded
36
+ * as well, which keeps the value a single link destination. ASCII characters
37
+ * are encoded as `%XX` with uppercase hex; non-ASCII whitespace is encoded as
38
+ * UTF-8 percent sequences.
39
+ * @param value - Raw value to escape
40
+ * @returns Value with Markdown-significant characters percent-encoded
41
+ */
42
+ const escapeMarkdownURL = (value) => {
43
+ return value.replace(MARKDOWN_URL_UNSAFE_CHARS, (char) => {
44
+ if (char.charCodeAt(0) > 0x7f) {
45
+ return encodeURIComponent(char);
46
+ }
47
+ return `%${char.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`;
48
+ });
49
+ };
50
+ exports.escapeMarkdownURL = escapeMarkdownURL;
@@ -37,15 +37,23 @@ export declare const formatMDXAdmonition: ({ text, title, type }: AdmonitionType
37
37
  */
38
38
  export declare const formatMDXDetails: ({ dataOpen, dataClose, }: CollapsibleOption) => MDXString;
39
39
  /**
40
- * Formats YAML front matter and appends an H1 heading derived from the `title` prop.
40
+ * Formats YAML front matter.
41
41
  * Merges `props` entries with `formatted` lines (formatted lines take precedence).
42
42
  * Returns empty string if `props` is empty or absent — HonKit renders front matter
43
43
  * without a title as literal YAML content.
44
- * @param props - Front matter options; `title` is used to generate the H1 heading
44
+ * @param props - Front matter options
45
45
  * @param formatted - Pre-formatted front matter lines that override props values
46
- * @returns Formatted front matter block with optional H1, or empty string
46
+ * @returns Formatted front matter block, or empty string
47
47
  */
48
48
  export declare const formatMDXFrontmatter: (props: Maybe<FrontMatterOptions>, formatted: Maybe<string[]>) => MDXString;
49
+ /**
50
+ * Formats the page title as a visible H1 heading.
51
+ * Line breaks are collapsed to spaces and surrounding whitespace is trimmed,
52
+ * so the heading stays on a single line.
53
+ * @param title - The page title
54
+ * @returns `# Title` heading, or empty string if the title is blank
55
+ */
56
+ export declare const formatMDXTitle: (title: string) => MDXString;
49
57
  /**
50
58
  * Converts internal link URLs to `.html` paths for HonKit static output.
51
59
  * Absolute paths without an `.html` extension are suffixed with `.html`.
@@ -63,7 +71,7 @@ export declare const formatMDXLink: ({ text, url }: TypeLink) => TypeLink;
63
71
  */
64
72
  export declare const formatMDXNameEntity: (name: string, parentType?: Maybe<string>) => MDXString;
65
73
  /**
66
- * Formats a "specified by" link as plain text with the raw URL.
74
+ * Formats a "specified by" link as plain text with the URL percent-encoded.
67
75
  * HonKit does not render custom JSX components.
68
76
  * @param url - URL to the specification
69
77
  * @returns Formatted specification text string
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/honkit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,KAAK,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAQjC,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,eAAO,MAAM,SAAS,EAAE;IACtB,eAAe,EAAE,OAAO,eAAe,CAAC;IACxC,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;CACL,CAAC;AAE5C,uFAAuF;AACvF,eAAO,MAAM,YAAY,EAAG,KAAc,CAAC;AAS3C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,aAAc,KAAK,KAAG,SAKhD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAGF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6BAG1B,iBAAiB,KAAG,SAEtB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,UACxB,KAAK,CAAC,kBAAkB,CAAC,aACrB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAiBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,kBAAmB,QAAQ,KAAG,QAoBvD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,SACxB,MAAM,eACC,KAAK,CAAC,MAAM,CAAC,KACzB,SAEF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAS,MAAM,KAAG,SAEtD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAY5D,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/honkit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,KAAK,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAOjC,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAGrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,eAAO,MAAM,SAAS,EAAE;IACtB,eAAe,EAAE,OAAO,eAAe,CAAC;IACxC,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;CACL,CAAC;AAE5C,uFAAuF;AACvF,eAAO,MAAM,YAAY,EAAG,KAAc,CAAC;AAS3C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,aAAc,KAAK,KAAG,SAKhD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAGF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6BAG1B,iBAAiB,KAAG,SAEtB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,UACxB,KAAK,CAAC,kBAAkB,CAAC,aACrB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAYF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,UAAW,MAAM,KAAG,SAG9C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,kBAAmB,QAAQ,KAAG,QAoBvD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,SACxB,MAAM,eACC,KAAK,CAAC,MAAM,CAAC,KACzB,SAEF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAS,MAAM,KAAG,SAEtD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAa5D,CAAC"}
@@ -8,10 +8,11 @@
8
8
  * @packageDocumentation
9
9
  */
10
10
  Object.defineProperty(exports, "__esModule", { value: true });
11
- exports.createMDXFormatter = exports.formatMDXSpecifiedByLink = exports.formatMDXNameEntity = exports.formatMDXLink = exports.formatMDXFrontmatter = exports.formatMDXDetails = exports.formatMDXAdmonition = exports.formatMDXBadge = exports.mdxExtension = exports.__default = exports.formatMDXPermalink = void 0;
11
+ exports.createMDXFormatter = exports.formatMDXSpecifiedByLink = exports.formatMDXNameEntity = exports.formatMDXLink = exports.formatMDXTitle = exports.formatMDXFrontmatter = exports.formatMDXDetails = exports.formatMDXAdmonition = exports.formatMDXBadge = exports.mdxExtension = exports.__default = exports.formatMDXPermalink = void 0;
12
12
  const helpers_1 = require("@graphql-markdown/helpers");
13
13
  const utils_1 = require("@graphql-markdown/utils");
14
14
  const defaults_ts_1 = require("../defaults.js");
15
+ const escape_ts_1 = require("../escape.js");
15
16
  var defaults_ts_2 = require("../defaults.js");
16
17
  Object.defineProperty(exports, "formatMDXPermalink", { enumerable: true, get: function () { return defaults_ts_2.formatMDXPermalink; } });
17
18
  exports.__default = { formatMDXBullet: defaults_ts_1.formatMDXBullet, formatMDXPermalink: defaults_ts_1.formatMDXPermalink };
@@ -56,25 +57,34 @@ const formatMDXDetails = ({ dataOpen, dataClose, }) => {
56
57
  };
57
58
  exports.formatMDXDetails = formatMDXDetails;
58
59
  /**
59
- * Formats YAML front matter and appends an H1 heading derived from the `title` prop.
60
+ * Formats YAML front matter.
60
61
  * Merges `props` entries with `formatted` lines (formatted lines take precedence).
61
62
  * Returns empty string if `props` is empty or absent — HonKit renders front matter
62
63
  * without a title as literal YAML content.
63
- * @param props - Front matter options; `title` is used to generate the H1 heading
64
+ * @param props - Front matter options
64
65
  * @param formatted - Pre-formatted front matter lines that override props values
65
- * @returns Formatted front matter block with optional H1, or empty string
66
+ * @returns Formatted front matter block, or empty string
66
67
  */
67
68
  const formatMDXFrontmatter = (props, formatted) => {
68
69
  if (!props || typeof props !== "object" || Object.keys(props).length === 0) {
69
70
  return "";
70
71
  }
71
72
  const lines = (0, helpers_1.mergeFrontmatterLines)(props, formatted ?? null);
72
- const frontmatter = (0, helpers_1.formatMarkdownFrontmatter)(lines, utils_1.FRONT_MATTER_DELIMITER, utils_1.MARKDOWN_EOL);
73
- const title = (0, helpers_1.extractFrontmatterTitle)(lines).replaceAll(/\r?\n/g, " ").trim();
74
- const heading = title ? `\n\n# ${title}` : "";
75
- return `${frontmatter}${heading}`;
73
+ return (0, helpers_1.formatMarkdownFrontmatter)(lines, utils_1.FRONT_MATTER_DELIMITER, utils_1.MARKDOWN_EOL);
76
74
  };
77
75
  exports.formatMDXFrontmatter = formatMDXFrontmatter;
76
+ /**
77
+ * Formats the page title as a visible H1 heading.
78
+ * Line breaks are collapsed to spaces and surrounding whitespace is trimmed,
79
+ * so the heading stays on a single line.
80
+ * @param title - The page title
81
+ * @returns `# Title` heading, or empty string if the title is blank
82
+ */
83
+ const formatMDXTitle = (title) => {
84
+ const heading = title.replaceAll(/\r?\n/g, " ").trim();
85
+ return (heading ? `# ${heading}` : "");
86
+ };
87
+ exports.formatMDXTitle = formatMDXTitle;
78
88
  /**
79
89
  * Converts internal link URLs to `.html` paths for HonKit static output.
80
90
  * Absolute paths without an `.html` extension are suffixed with `.html`.
@@ -108,13 +118,13 @@ const formatMDXNameEntity = (name, parentType) => {
108
118
  };
109
119
  exports.formatMDXNameEntity = formatMDXNameEntity;
110
120
  /**
111
- * Formats a "specified by" link as plain text with the raw URL.
121
+ * Formats a "specified by" link as plain text with the URL percent-encoded.
112
122
  * HonKit does not render custom JSX components.
113
123
  * @param url - URL to the specification
114
124
  * @returns Formatted specification text string
115
125
  */
116
126
  const formatMDXSpecifiedByLink = (url) => {
117
- return `\n\nSpecified by: ${url}`;
127
+ return `\n\nSpecified by: ${(0, escape_ts_1.escapeMarkdownURL)(url)}`;
118
128
  };
119
129
  exports.formatMDXSpecifiedByLink = formatMDXSpecifiedByLink;
120
130
  /**
@@ -133,6 +143,7 @@ const createMDXFormatter = (_meta) => {
133
143
  formatMDXNameEntity: exports.formatMDXNameEntity,
134
144
  formatMDXPermalink: defaults_ts_1.formatMDXPermalink,
135
145
  formatMDXSpecifiedByLink: exports.formatMDXSpecifiedByLink,
146
+ formatMDXTitle: exports.formatMDXTitle,
136
147
  };
137
148
  };
138
149
  exports.createMDXFormatter = createMDXFormatter;
@@ -37,12 +37,19 @@ export declare const formatMDXAdmonition: ({ text, title, type }: AdmonitionType
37
37
  */
38
38
  export declare const formatMDXDetails: ({ dataOpen, }: CollapsibleOption) => MDXString;
39
39
  /**
40
- * Replaces front matter with an H1 title heading.
40
+ * Suppresses front matter.
41
41
  * mdBook renders `---` YAML blocks as literal content, so front matter is
42
- * suppressed entirely. The page title is emitted as `# Title` instead.
43
- * @returns `# Title\n` when a title is available, otherwise an empty string
42
+ * suppressed entirely. The page title is printed by {@link formatMDXTitle}.
43
+ * @returns An empty string
44
44
  */
45
- export declare const formatMDXFrontmatter: (_props: Maybe<FrontMatterOptions>, formatted: Maybe<string[]>) => MDXString;
45
+ export declare const formatMDXFrontmatter: (_props: Maybe<FrontMatterOptions>, _formatted: Maybe<string[]>) => MDXString;
46
+ /**
47
+ * Formats the page title as a visible `# Title` heading, since front matter
48
+ * is suppressed.
49
+ * @param title - The page title
50
+ * @returns `# Title` heading
51
+ */
52
+ export declare const formatMDXTitle: (title: string) => MDXString;
46
53
  /** mdBook expects `.md` files; override the default `.mdx` extension. */
47
54
  export declare const mdxExtension = ".md";
48
55
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mdbook/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,KAAK,EAEL,SAAS,EACT,QAAQ,EACR,eAAe,EACf,sBAAsB,EACtB,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAuBjC;;;;GAIG;AACH,eAAO,MAAM,cAAc,aAAc,KAAK,KAAG,SAEhD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAIF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,kBAE1B,iBAAiB,KAAG,SAEtB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,WACvB,KAAK,CAAC,kBAAkB,CAAC,aACtB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAEF,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,YAAY,QAAQ,CAAC;AAElC;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAU,QAAQ,KAAG,QAU9C,CAAC;AAEF,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AAIxB;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,EAAE,sBAIzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAY5D,CAAC;AAeF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,eAkFlC,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mdbook/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,KAAK,EAEL,SAAS,EACT,QAAQ,EACR,eAAe,EACf,sBAAsB,EACtB,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAsBjC;;;;GAIG;AACH,eAAO,MAAM,cAAc,aAAc,KAAK,KAAG,SAEhD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAIF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,kBAE1B,iBAAiB,KAAG,SAEtB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,WACvB,KAAK,CAAC,kBAAkB,CAAC,cACrB,KAAK,CAAC,MAAM,EAAE,CAAC,KAC1B,SAEF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,UAAW,MAAM,KAAG,SAE9C,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,YAAY,QAAQ,CAAC;AAElC;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAU,QAAQ,KAAG,QAU9C,CAAC;AAEF,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AAIxB;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,EAAE,sBAIzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAa5D,CAAC;AAeF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,eAkFlC,CAAC"}
@@ -10,7 +10,7 @@
10
10
  * @packageDocumentation
11
11
  */
12
12
  Object.defineProperty(exports, "__esModule", { value: true });
13
- exports.afterRenderFilesHook = exports.createMDXFormatter = exports.afterRenderTypeEntitiesHook = exports.formatMDXSpecifiedByLink = exports.formatMDXPermalink = exports.formatMDXNameEntity = exports.formatMDXBullet = exports.formatMDXLink = exports.mdxExtension = exports.formatMDXFrontmatter = exports.formatMDXDetails = exports.formatMDXAdmonition = exports.formatMDXBadge = void 0;
13
+ exports.afterRenderFilesHook = exports.createMDXFormatter = exports.afterRenderTypeEntitiesHook = exports.formatMDXSpecifiedByLink = exports.formatMDXPermalink = exports.formatMDXNameEntity = exports.formatMDXBullet = exports.formatMDXLink = exports.mdxExtension = exports.formatMDXTitle = exports.formatMDXFrontmatter = exports.formatMDXDetails = exports.formatMDXAdmonition = exports.formatMDXBadge = void 0;
14
14
  const node_path_1 = require("node:path");
15
15
  const helpers_1 = require("@graphql-markdown/helpers");
16
16
  const utils_1 = require("@graphql-markdown/utils");
@@ -55,15 +55,25 @@ const formatMDXDetails = ({ dataOpen, }) => {
55
55
  };
56
56
  exports.formatMDXDetails = formatMDXDetails;
57
57
  /**
58
- * Replaces front matter with an H1 title heading.
58
+ * Suppresses front matter.
59
59
  * mdBook renders `---` YAML blocks as literal content, so front matter is
60
- * suppressed entirely. The page title is emitted as `# Title` instead.
61
- * @returns `# Title\n` when a title is available, otherwise an empty string
60
+ * suppressed entirely. The page title is printed by {@link formatMDXTitle}.
61
+ * @returns An empty string
62
62
  */
63
- const formatMDXFrontmatter = (_props, formatted) => {
64
- return (0, defaults_ts_1.formatMDXFrontmatterTitleOnly)(formatted, true);
63
+ const formatMDXFrontmatter = (_props, _formatted) => {
64
+ return "";
65
65
  };
66
66
  exports.formatMDXFrontmatter = formatMDXFrontmatter;
67
+ /**
68
+ * Formats the page title as a visible `# Title` heading, since front matter
69
+ * is suppressed.
70
+ * @param title - The page title
71
+ * @returns `# Title` heading
72
+ */
73
+ const formatMDXTitle = (title) => {
74
+ return `# ${title}`;
75
+ };
76
+ exports.formatMDXTitle = formatMDXTitle;
67
77
  /** mdBook expects `.md` files; override the default `.mdx` extension. */
68
78
  exports.mdxExtension = ".md";
69
79
  /**
@@ -118,6 +128,7 @@ const createMDXFormatter = (_meta) => {
118
128
  formatMDXNameEntity: defaults_ts_1.formatMDXNameEntity,
119
129
  formatMDXPermalink: defaults_ts_1.formatMDXPermalink,
120
130
  formatMDXSpecifiedByLink: defaults_ts_1.formatMDXSpecifiedByLink,
131
+ formatMDXTitle: exports.formatMDXTitle,
121
132
  };
122
133
  };
123
134
  exports.createMDXFormatter = createMDXFormatter;
@@ -49,6 +49,7 @@ export declare const formatMDXFrontmatter: (_props: Maybe<FrontMatterOptions>, f
49
49
  export declare const formatMDXNameEntity: (name: string, parentType?: Maybe<string>) => MDXString;
50
50
  /**
51
51
  * Formats a "specified by" link as a standard Markdown link.
52
+ * The URL is percent-encoded so it stays a single Markdown link destination.
52
53
  * @param url - URL to the specification
53
54
  * @returns Formatted specification link string
54
55
  */
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mkdocs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,KAAK,EACL,SAAS,EACT,QAAQ,EACR,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,eAAe,EAEf,aAAa,EACb,kBAAkB,EACnB,MAAM,gBAAgB,CAAC;AAGxB,eAAO,MAAM,SAAS,EAAE;IACtB,eAAe,EAAE,OAAO,eAAe,CAAC;IACxC,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;CAK/C,CAAC;AAeF;;;;GAIG;AACH,eAAO,MAAM,cAAc,aAAc,KAAK,KAAG,SAEhD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAIF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6BAG1B,iBAAiB,KAAG,SAEtB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,WACvB,KAAK,CAAC,kBAAkB,CAAC,aACtB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAEF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,SACxB,MAAM,eACC,KAAK,CAAC,MAAM,CAAC,KACzB,SAGF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAAS,MAAM,KAAG,SAEtD,CAAC;AAEF,2FAA2F;AAC3F,eAAO,MAAM,YAAY,EAAG,KAAc,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,sBAIzC,CAAC;AAEF,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAErE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAY5D,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mkdocs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,KAAK,EACL,SAAS,EACT,QAAQ,EACR,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,eAAe,EAEf,aAAa,EACb,kBAAkB,EACnB,MAAM,gBAAgB,CAAC;AAIxB,eAAO,MAAM,SAAS,EAAE;IACtB,eAAe,EAAE,OAAO,eAAe,CAAC;IACxC,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;CAK/C,CAAC;AAeF;;;;GAIG;AACH,eAAO,MAAM,cAAc,aAAc,KAAK,KAAG,SAEhD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAIF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6BAG1B,iBAAiB,KAAG,SAEtB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,WACvB,KAAK,CAAC,kBAAkB,CAAC,aACtB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAEF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,SACxB,MAAM,eACC,KAAK,CAAC,MAAM,CAAC,KACzB,SAGF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAS,MAAM,KAAG,SAEtD,CAAC;AAEF,2FAA2F;AAC3F,eAAO,MAAM,YAAY,EAAG,KAAc,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,sBAIzC,CAAC;AAEF,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAErE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAY5D,CAAC"}
@@ -12,6 +12,7 @@ exports.createMDXFormatter = exports.formatMDXPermalink = exports.formatMDXBulle
12
12
  const helpers_1 = require("@graphql-markdown/helpers");
13
13
  const utils_1 = require("@graphql-markdown/utils");
14
14
  const defaults_ts_1 = require("../defaults.js");
15
+ const escape_ts_1 = require("../escape.js");
15
16
  const output_ts_1 = require("../output.js");
16
17
  exports.__default = {
17
18
  formatMDXBullet: defaults_ts_1.formatMDXBullet,
@@ -83,11 +84,12 @@ const formatMDXNameEntity = (name, parentType) => {
83
84
  exports.formatMDXNameEntity = formatMDXNameEntity;
84
85
  /**
85
86
  * Formats a "specified by" link as a standard Markdown link.
87
+ * The URL is percent-encoded so it stays a single Markdown link destination.
86
88
  * @param url - URL to the specification
87
89
  * @returns Formatted specification link string
88
90
  */
89
91
  const formatMDXSpecifiedByLink = (url) => {
90
- return `[Specification ⎘](${url})`;
92
+ return `[Specification ⎘](${(0, escape_ts_1.escapeMarkdownURL)(url)})`;
91
93
  };
92
94
  exports.formatMDXSpecifiedByLink = formatMDXSpecifiedByLink;
93
95
  /** File extension used for generated pages — MkDocs uses standard Markdown (.md) files. */
@@ -5,7 +5,7 @@
5
5
  *
6
6
  * @packageDocumentation
7
7
  */
8
- import type { AdmonitionType, Badge, Formatter, FrontMatterOptions, Maybe, MDXString, MetaInfo, TypeLink } from "@graphql-markdown/types";
8
+ import type { AdmonitionType, Badge, Formatter, Maybe, MDXString, MetaInfo, TypeLink } from "@graphql-markdown/types";
9
9
  import { formatMDXEscapedPermalink } from "../defaults.ts";
10
10
  /**
11
11
  * Formats a permalink for a section header, using the classic `{#id}` syntax
@@ -26,7 +26,7 @@ export declare const mdxDeclaration: MDXString;
26
26
  /** File extension used for generated pages. */
27
27
  export declare const mdxExtension: ".mdx";
28
28
  /**
29
- * Formats YAML front matter followed by a visible `# Title` heading.
29
+ * Formats the page title as a visible `# Title` heading.
30
30
  *
31
31
  * Vocs only uses the front matter `title` for the document `<title>`; the
32
32
  * page heading must be written in Markdown, so without it generated pages
@@ -34,11 +34,10 @@ export declare const mdxExtension: ".mdx";
34
34
  *
35
35
  * @see https://vocs.dev/docs/markdown
36
36
  *
37
- * @param props - Front matter options
38
- * @param formatted - Pre-formatted front matter lines
39
- * @returns Front matter block and title heading, or empty string if no lines provided
37
+ * @param title - The page title
38
+ * @returns `# Title` heading
40
39
  */
41
- export declare const formatMDXFrontmatter: (props: Maybe<FrontMatterOptions>, formatted: Maybe<string[]>) => MDXString;
40
+ export declare const formatMDXTitle: (title: string) => MDXString;
42
41
  /**
43
42
  * Formats a badge using Vocs native text directive (`:badge[...]`).
44
43
  * Maps `DEPRECATED` classname to `warning` color; all others use default.
@@ -73,7 +72,7 @@ export declare const formatMDXLink: ({ text, url }: TypeLink) => TypeLink;
73
72
  * @returns Formatted JSX entity reference string
74
73
  */
75
74
  export declare const formatMDXNameEntity: (name: string, parentType?: Maybe<string>) => MDXString;
76
- export { formatMDXDetails, formatMDXSpecifiedByLink } from "../defaults.ts";
75
+ export { formatMDXDetails, formatMDXFrontmatter, formatMDXSpecifiedByLink, } from "../defaults.ts";
77
76
  /**
78
77
  * Creates a Vocs formatter.
79
78
  * @param _meta - Unused metadata parameter
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vocs/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,SAAS,EACT,kBAAkB,EAClB,KAAK,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAEL,yBAAyB,EAI1B,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,OAAO,yBACb,CAAC;AAE5B,+FAA+F;AAC/F,eAAO,MAAM,cAAc,EAAE,SAEf,CAAC;AAEf,+CAA+C;AAC/C,eAAO,MAAM,YAAY,EAAG,MAAe,CAAC;AAE5C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,UACxB,KAAK,CAAC,kBAAkB,CAAC,aACrB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAOF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,wBAAyB,KAAK,KAAG,SAG3D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAGF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,qBAAgB,SAE3C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,kBAAmB,QAAQ,KAAG,QAKvD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,SACxB,MAAM,eACC,KAAK,CAAC,MAAM,CAAC,KACzB,SAKF,CAAC;AAEF,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAY5D,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vocs/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,SAAS,EACT,KAAK,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAEL,yBAAyB,EAG1B,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,OAAO,yBACb,CAAC;AAE5B,+FAA+F;AAC/F,eAAO,MAAM,cAAc,EAAE,SAEf,CAAC;AAEf,+CAA+C;AAC/C,eAAO,MAAM,YAAY,EAAG,MAAe,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,UAAW,MAAM,KAAG,SAE9C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,wBAAyB,KAAK,KAAG,SAG3D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAGF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,qBAAgB,SAE3C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,kBAAmB,QAAQ,KAAG,QAKvD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,SACxB,MAAM,eACC,KAAK,CAAC,MAAM,CAAC,KACzB,SAKF,CAAC;AAEF,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAa5D,CAAC"}
@@ -7,7 +7,7 @@
7
7
  * @packageDocumentation
8
8
  */
9
9
  Object.defineProperty(exports, "__esModule", { value: true });
10
- exports.createMDXFormatter = exports.formatMDXSpecifiedByLink = exports.formatMDXDetails = exports.formatMDXNameEntity = exports.formatMDXLink = exports.formatMDXBullet = exports.formatMDXAdmonition = exports.formatMDXBadge = exports.formatMDXFrontmatter = exports.mdxExtension = exports.mdxDeclaration = exports.formatMDXPermalink = void 0;
10
+ exports.createMDXFormatter = exports.formatMDXSpecifiedByLink = exports.formatMDXFrontmatter = exports.formatMDXDetails = exports.formatMDXNameEntity = exports.formatMDXLink = exports.formatMDXBullet = exports.formatMDXAdmonition = exports.formatMDXBadge = exports.formatMDXTitle = exports.mdxExtension = exports.mdxDeclaration = exports.formatMDXPermalink = void 0;
11
11
  const helpers_1 = require("@graphql-markdown/helpers");
12
12
  const utils_1 = require("@graphql-markdown/utils");
13
13
  const defaults_ts_1 = require("../defaults.js");
@@ -32,7 +32,7 @@ export const Bullet = () => <><span style={{ fontWeight: 'normal', fontSize: '.5
32
32
  /** File extension used for generated pages. */
33
33
  exports.mdxExtension = ".mdx";
34
34
  /**
35
- * Formats YAML front matter followed by a visible `# Title` heading.
35
+ * Formats the page title as a visible `# Title` heading.
36
36
  *
37
37
  * Vocs only uses the front matter `title` for the document `<title>`; the
38
38
  * page heading must be written in Markdown, so without it generated pages
@@ -40,19 +40,13 @@ exports.mdxExtension = ".mdx";
40
40
  *
41
41
  * @see https://vocs.dev/docs/markdown
42
42
  *
43
- * @param props - Front matter options
44
- * @param formatted - Pre-formatted front matter lines
45
- * @returns Front matter block and title heading, or empty string if no lines provided
43
+ * @param title - The page title
44
+ * @returns `# Title` heading
46
45
  */
47
- const formatMDXFrontmatter = (props, formatted) => {
48
- const frontMatter = (0, defaults_ts_1.formatMDXFrontmatter)(props, formatted);
49
- const heading = (0, defaults_ts_1.formatMDXFrontmatterTitleOnly)(formatted);
50
- if (!frontMatter || !heading) {
51
- return frontMatter;
52
- }
53
- return `${frontMatter}${utils_1.MARKDOWN_EOP}${heading}`;
46
+ const formatMDXTitle = (title) => {
47
+ return `# ${title}`;
54
48
  };
55
- exports.formatMDXFrontmatter = formatMDXFrontmatter;
49
+ exports.formatMDXTitle = formatMDXTitle;
56
50
  /**
57
51
  * Formats a badge using Vocs native text directive (`:badge[...]`).
58
52
  * Maps `DEPRECATED` classname to `warning` color; all others use default.
@@ -112,6 +106,7 @@ const formatMDXNameEntity = (name, parentType) => {
112
106
  exports.formatMDXNameEntity = formatMDXNameEntity;
113
107
  var defaults_ts_2 = require("../defaults.js");
114
108
  Object.defineProperty(exports, "formatMDXDetails", { enumerable: true, get: function () { return defaults_ts_2.formatMDXDetails; } });
109
+ Object.defineProperty(exports, "formatMDXFrontmatter", { enumerable: true, get: function () { return defaults_ts_2.formatMDXFrontmatter; } });
115
110
  Object.defineProperty(exports, "formatMDXSpecifiedByLink", { enumerable: true, get: function () { return defaults_ts_2.formatMDXSpecifiedByLink; } });
116
111
  /**
117
112
  * Creates a Vocs formatter.
@@ -124,11 +119,12 @@ const createMDXFormatter = (_meta) => {
124
119
  formatMDXAdmonition: exports.formatMDXAdmonition,
125
120
  formatMDXBullet: exports.formatMDXBullet,
126
121
  formatMDXDetails: defaults_ts_1.formatMDXDetails,
127
- formatMDXFrontmatter: exports.formatMDXFrontmatter,
122
+ formatMDXFrontmatter: defaults_ts_1.formatMDXFrontmatter,
128
123
  formatMDXLink: exports.formatMDXLink,
129
124
  formatMDXNameEntity: exports.formatMDXNameEntity,
130
125
  formatMDXPermalink: exports.formatMDXPermalink,
131
126
  formatMDXSpecifiedByLink: defaults_ts_1.formatMDXSpecifiedByLink,
127
+ formatMDXTitle: exports.formatMDXTitle,
132
128
  };
133
129
  };
134
130
  exports.createMDXFormatter = createMDXFormatter;
package/package.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "bugs": {
6
6
  "url": "https://github.com/graphql-markdown/graphql-markdown/issues"
7
7
  },
8
- "version": "1.2.2",
8
+ "version": "1.2.3",
9
9
  "license": "MIT",
10
10
  "repository": {
11
11
  "type": "git",
@@ -221,9 +221,9 @@
221
221
  "test:watch": "vitest --watch"
222
222
  },
223
223
  "dependencies": {
224
- "@graphql-markdown/helpers": "^1.2.5",
225
- "@graphql-markdown/types": "^1.17.1",
226
- "@graphql-markdown/utils": "^1.14.2"
224
+ "@graphql-markdown/helpers": "^1.2.6",
225
+ "@graphql-markdown/types": "^1.18.0",
226
+ "@graphql-markdown/utils": "^1.14.3"
227
227
  },
228
228
  "devDependencies": {
229
229
  "@graphql-markdown/tooling-config": "^1.0.0"