@graphql-markdown/formatters 1.0.2 → 1.1.1

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.
@@ -40,6 +40,14 @@ export declare const formatMDXDetails: ({ dataOpen, dataClose, }: CollapsibleOpt
40
40
  * @returns Formatted front matter block, or empty string if no lines provided
41
41
  */
42
42
  export declare const formatMDXFrontmatter: (_props: Maybe<FrontMatterOptions>, formatted: Maybe<string[]>) => MDXString;
43
+ /**
44
+ * Formats the page title as a visible H1 heading, for frameworks that render
45
+ * YAML front matter as literal page content and so must suppress it entirely.
46
+ * @param formatted - Pre-formatted front matter lines
47
+ * @param trailingEol - Whether to append a trailing end-of-line after the heading
48
+ * @returns `# Title` heading, or empty string if no title is available
49
+ */
50
+ export declare const formatMDXFrontmatterTitleOnly: (formatted: Maybe<string[]>, trailingEol?: boolean) => MDXString;
43
51
  /**
44
52
  * Formats a type link — returns the link unchanged (identity passthrough).
45
53
  * @param link - The `TypeLink` object to format
@@ -60,4 +68,31 @@ export declare const formatMDXNameEntity: (name: string, parentType?: Maybe<stri
60
68
  * @returns Formatted specification link string
61
69
  */
62
70
  export declare const formatMDXSpecifiedByLink: (url: string) => MDXString;
71
+ /**
72
+ * Formats a permalink for a section header using the classic `{#id}` syntax,
73
+ * escaped so that it stays valid MDX.
74
+ *
75
+ * MDX parses an unescaped `{` as the start of an expression, and `{#id}` is not
76
+ * a valid one, so presets generating `.mdx` pages must use this variant.
77
+ *
78
+ * @param id - The ID of the section header
79
+ * @returns Formatted permalink string
80
+ *
81
+ * @example
82
+ * ```js
83
+ * formatMDXEscapedPermalink("my-id"); // \{#my-id\}
84
+ * ```
85
+ */
86
+ export declare const formatMDXEscapedPermalink: (id: string) => MDXString;
87
+ /**
88
+ * Formats a permalink for a section header using the classic `{#id}` syntax.
89
+ *
90
+ * This is the syntax supported by most Markdown-based generators (Hugo,
91
+ * mdBook, DocFX, MkDocs with `attr_list`). Presets targeting a framework that
92
+ * expects another syntax override this function.
93
+ *
94
+ * @param id - The ID of the section header
95
+ * @returns Formatted permalink string
96
+ */
97
+ export declare const formatMDXPermalink: (id: string) => MDXString;
63
98
  //# sourceMappingURL=defaults.d.ts.map
@@ -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;AAQjC;;;;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;;;;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"}
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"}
package/dist/defaults.js CHANGED
@@ -8,7 +8,7 @@
8
8
  * @packageDocumentation
9
9
  */
10
10
  Object.defineProperty(exports, "__esModule", { value: true });
11
- exports.formatMDXSpecifiedByLink = exports.formatMDXNameEntity = exports.formatMDXLink = exports.formatMDXFrontmatter = exports.formatMDXDetails = exports.formatMDXBullet = exports.formatMDXAdmonition = exports.formatMDXBadge = void 0;
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
14
  /**
@@ -59,6 +59,21 @@ const formatMDXFrontmatter = (_props, formatted) => {
59
59
  return (0, helpers_1.formatMarkdownFrontmatter)(formatted, utils_1.FRONT_MATTER_DELIMITER, utils_1.MARKDOWN_EOL);
60
60
  };
61
61
  exports.formatMDXFrontmatter = formatMDXFrontmatter;
62
+ /**
63
+ * Formats the page title as a visible H1 heading, for frameworks that render
64
+ * YAML front matter as literal page content and so must suppress it entirely.
65
+ * @param formatted - Pre-formatted front matter lines
66
+ * @param trailingEol - Whether to append a trailing end-of-line after the heading
67
+ * @returns `# Title` heading, or empty string if no title is available
68
+ */
69
+ const formatMDXFrontmatterTitleOnly = (formatted, trailingEol = false) => {
70
+ const title = (0, helpers_1.extractFrontmatterTitle)(formatted);
71
+ if (!title) {
72
+ return "";
73
+ }
74
+ return `# ${title}${trailingEol ? utils_1.MARKDOWN_EOL : ""}`;
75
+ };
76
+ exports.formatMDXFrontmatterTitleOnly = formatMDXFrontmatterTitleOnly;
62
77
  /**
63
78
  * Formats a type link — returns the link unchanged (identity passthrough).
64
79
  * @param link - The `TypeLink` object to format
@@ -91,3 +106,36 @@ const formatMDXSpecifiedByLink = (url) => {
91
106
  return `<span class="gqlmd-mdx-specifiedby">Specification<a class="gqlmd-mdx-specifiedby-link" target="_blank" href="${url}" title="Specified by ${url}">⎘</a></span>`;
92
107
  };
93
108
  exports.formatMDXSpecifiedByLink = formatMDXSpecifiedByLink;
109
+ /**
110
+ * Formats a permalink for a section header using the classic `{#id}` syntax,
111
+ * escaped so that it stays valid MDX.
112
+ *
113
+ * MDX parses an unescaped `{` as the start of an expression, and `{#id}` is not
114
+ * a valid one, so presets generating `.mdx` pages must use this variant.
115
+ *
116
+ * @param id - The ID of the section header
117
+ * @returns Formatted permalink string
118
+ *
119
+ * @example
120
+ * ```js
121
+ * formatMDXEscapedPermalink("my-id"); // \{#my-id\}
122
+ * ```
123
+ */
124
+ const formatMDXEscapedPermalink = (id) => {
125
+ return String.raw `\{#${id}\}`;
126
+ };
127
+ exports.formatMDXEscapedPermalink = formatMDXEscapedPermalink;
128
+ /**
129
+ * Formats a permalink for a section header using the classic `{#id}` syntax.
130
+ *
131
+ * This is the syntax supported by most Markdown-based generators (Hugo,
132
+ * mdBook, DocFX, MkDocs with `attr_list`). Presets targeting a framework that
133
+ * expects another syntax override this function.
134
+ *
135
+ * @param id - The ID of the section header
136
+ * @returns Formatted permalink string
137
+ */
138
+ const formatMDXPermalink = (id) => {
139
+ return `{#${id}}`;
140
+ };
141
+ exports.formatMDXPermalink = formatMDXPermalink;
@@ -37,20 +37,16 @@ export declare const formatMDXFrontmatter: (props: Maybe<FrontMatterOptions>, fo
37
37
  * @returns The link unchanged
38
38
  */
39
39
  export declare const formatMDXLink: (link: TypeLink) => TypeLink;
40
- export { formatMDXBullet, formatMDXDetails, formatMDXNameEntity, formatMDXSpecifiedByLink, } from "../defaults";
40
+ export { formatMDXBullet, formatMDXDetails, formatMDXNameEntity, formatMDXPermalink, formatMDXSpecifiedByLink, } from "../defaults";
41
41
  /**
42
42
  * Creates a DocFX formatter.
43
43
  * @param _meta - Unused metadata parameter
44
44
  * @returns A complete {@link Formatter} implementation for DocFX output
45
45
  */
46
46
  export declare const createMDXFormatter: (_meta?: Maybe<MetaInfo>) => Formatter;
47
- export declare const mdxExtension: ".md";
48
47
  /**
49
- * Builds DocFX `toc.yml` navigation files as each entity page is written.
50
- *
51
- * Walks up from the generated file to the graphql output root (`outputDir`),
52
- * writing or updating a `toc.yml` at every directory level. Section index pages
53
- * are prepended as an "Overview" entry on first encounter.
48
+ * The file extension used for MDX files in DocFX output.
54
49
  */
50
+ export declare const mdxExtension: ".md";
55
51
  export declare const afterRenderTypeEntitiesHook: RenderTypeEntitiesHook;
56
52
  //# sourceMappingURL=index.d.ts.map
@@ -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,EACL,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,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAW5D,CAAC;AAEF,eAAO,MAAM,YAAY,EAAG,KAAc,CAAC;AAgI3C;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,sBA4DzC,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;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,aAAa,CAAC;AAErB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAY5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAG,KAAc,CAAC;AAsP3C,eAAO,MAAM,2BAA2B,EAAE,sBA0CzC,CAAC"}
@@ -9,11 +9,12 @@
9
9
  * @packageDocumentation
10
10
  */
11
11
  Object.defineProperty(exports, "__esModule", { value: true });
12
- exports.afterRenderTypeEntitiesHook = exports.mdxExtension = exports.createMDXFormatter = exports.formatMDXSpecifiedByLink = 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.formatMDXPermalink = exports.formatMDXNameEntity = exports.formatMDXDetails = exports.formatMDXBullet = exports.formatMDXLink = 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");
16
16
  const defaults_1 = require("../defaults");
17
+ const output_1 = require("../output");
17
18
  /** Maps graphql-markdown admonition types to DocFX alert types. */
18
19
  const ALERT_TYPE_MAP = {
19
20
  note: "NOTE",
@@ -90,6 +91,7 @@ var defaults_2 = require("../defaults");
90
91
  Object.defineProperty(exports, "formatMDXBullet", { enumerable: true, get: function () { return defaults_2.formatMDXBullet; } });
91
92
  Object.defineProperty(exports, "formatMDXDetails", { enumerable: true, get: function () { return defaults_2.formatMDXDetails; } });
92
93
  Object.defineProperty(exports, "formatMDXNameEntity", { enumerable: true, get: function () { return defaults_2.formatMDXNameEntity; } });
94
+ Object.defineProperty(exports, "formatMDXPermalink", { enumerable: true, get: function () { return defaults_2.formatMDXPermalink; } });
93
95
  Object.defineProperty(exports, "formatMDXSpecifiedByLink", { enumerable: true, get: function () { return defaults_2.formatMDXSpecifiedByLink; } });
94
96
  /**
95
97
  * Creates a DocFX formatter.
@@ -105,11 +107,18 @@ const createMDXFormatter = (_meta) => {
105
107
  formatMDXFrontmatter: exports.formatMDXFrontmatter,
106
108
  formatMDXLink: exports.formatMDXLink,
107
109
  formatMDXNameEntity: defaults_1.formatMDXNameEntity,
110
+ formatMDXPermalink: defaults_1.formatMDXPermalink,
108
111
  formatMDXSpecifiedByLink: defaults_1.formatMDXSpecifiedByLink,
109
112
  };
110
113
  };
111
114
  exports.createMDXFormatter = createMDXFormatter;
115
+ /**
116
+ * The file extension used for MDX files in DocFX output.
117
+ */
112
118
  exports.mdxExtension = ".md";
119
+ /**
120
+ * Determines if a link is an absolute internal link within the documentation.
121
+ */
113
122
  const isAbsoluteInternalLink = (content, urlStart) => {
114
123
  if (content[urlStart] !== "/")
115
124
  return null;
@@ -121,6 +130,9 @@ const isAbsoluteInternalLink = (content, urlStart) => {
121
130
  return null;
122
131
  return { closePos, urlWithHash };
123
132
  };
133
+ /**
134
+ * Resolves an internal link to its relative path within the generated documentation.
135
+ */
124
136
  const resolveLink = (urlWithHash, filePath, outputDir, normalizedBaseURL, baseSegment) => {
125
137
  const sepIdx = urlWithHash.indexOf("#");
126
138
  const [urlPath, hash] = sepIdx < 0
@@ -140,6 +152,10 @@ const resolveLink = (urlWithHash, filePath, outputDir, normalizedBaseURL, baseSe
140
152
  });
141
153
  return `](${relative ?? urlPath}${hash})`;
142
154
  };
155
+ /**
156
+ * Rewrites all absolute internal links in the content to relative links
157
+ * based on the file's location and the documentation structure.
158
+ */
143
159
  const rewriteInternalLinks = (content, filePath, outputDir, baseURL) => {
144
160
  const normalizedBaseURL = baseURL.split("/").filter(Boolean).join("/");
145
161
  const baseSegment = `/${normalizedBaseURL}/`;
@@ -159,37 +175,51 @@ const rewriteInternalLinks = (content, filePath, outputDir, baseURL) => {
159
175
  pos = urlStart;
160
176
  continue;
161
177
  }
162
- out.push(content.slice(pos, markerPos));
163
- out.push(resolveLink(match.urlWithHash, filePath, outputDir, normalizedBaseURL, baseSegment));
178
+ out.push(content.slice(pos, markerPos), resolveLink(match.urlWithHash, filePath, outputDir, normalizedBaseURL, baseSegment));
164
179
  pos = match.closePos + 1;
165
180
  }
166
181
  return out.join("");
167
182
  };
168
183
  // ─── toc.yml builder ────────────────────────────────────────────────────────
184
+ /**
185
+ * Map to track pending write operations for each file.
186
+ * Ensures that concurrent writes to the same file are executed sequentially.
187
+ */
169
188
  const writeQueue = new Map();
189
+ /**
190
+ * Queues a file update to ensure that multiple concurrent writes to the same file
191
+ * are executed sequentially.
192
+ */
170
193
  const queueFileUpdate = async (filePath, update) => {
171
194
  const previous = writeQueue.get(filePath) ?? Promise.resolve();
172
195
  const next = previous.catch(() => { }).then(update);
173
196
  writeQueue.set(filePath, next);
174
197
  return next;
175
198
  };
176
- const updateToc = async (tocFilePath, name, href) => {
199
+ /**
200
+ * Updates the `toc.yml` file for a given directory with a new entry.
201
+ * Ensures that multiple concurrent updates to the same file are queued.
202
+ */
203
+ const updateToc = async (tocFilePath, name, href, outputAdapter) => {
177
204
  await queueFileUpdate(tocFilePath, async () => {
178
205
  const entry = `- name: ${name}${utils_1.MARKDOWN_EOL} href: ${href}`;
179
- if (!(await (0, utils_1.fileExists)(tocFilePath))) {
180
- await (0, utils_1.saveFile)(tocFilePath, entry + utils_1.MARKDOWN_EOL);
206
+ const existing = await (0, output_1.readOptionalOutput)(tocFilePath, outputAdapter);
207
+ if (typeof existing !== "string") {
208
+ await (0, output_1.writeOutput)(tocFilePath, entry + utils_1.MARKDOWN_EOL, outputAdapter);
181
209
  return;
182
210
  }
183
- const existing = await (0, utils_1.readFile)(tocFilePath, "utf-8");
184
211
  if (existing.includes(`href: ${href}`)) {
185
212
  return;
186
213
  }
187
- await (0, utils_1.saveFile)(tocFilePath, existing.trimEnd() + utils_1.MARKDOWN_EOL + entry + utils_1.MARKDOWN_EOL);
214
+ await (0, output_1.writeOutput)(tocFilePath, existing.trimEnd() + utils_1.MARKDOWN_EOL + entry + utils_1.MARKDOWN_EOL, outputAdapter);
188
215
  });
189
216
  };
190
- // Tracks directories whose index.md has already been prepended to their toc.yml.
191
- // Module-level so it persists across all hook invocations within one generation run.
192
- const seenDirectories = new Set();
217
+ // Tracks directories whose index.md has already been prepended to their toc.yml,
218
+ // so the check runs once per directory rather than once per page. Keyed by
219
+ // destination: two adapters writing the same paths keep their own state, and a
220
+ // run with a fresh adapter starts over. `updateToc` skips an href it already
221
+ // holds, so a repeated attempt adds nothing.
222
+ const seenDirectories = new WeakMap();
193
223
  /**
194
224
  * Builds DocFX `toc.yml` navigation files as each entity page is written.
195
225
  *
@@ -197,44 +227,85 @@ const seenDirectories = new Set();
197
227
  * writing or updating a `toc.yml` at every directory level. Section index pages
198
228
  * are prepended as an "Overview" entry on first encounter.
199
229
  */
200
- const afterRenderTypeEntitiesHook = async (event) => {
201
- const { baseURL, filePath, name, outputDir } = event.data;
202
- const graphqlRoot = (0, node_path_1.resolve)(outputDir);
203
- // Rewrite uid as a path-derived value to guarantee uniqueness across the site.
204
- // e.g. operations/queries/continent.md → uid: operations-queries-continent
205
- const uid = (0, node_path_1.relative)(graphqlRoot, filePath)
206
- .replace(/\.mdx?$/, "")
207
- .replaceAll(/[/\\]/g, "-");
208
- const content = await (0, utils_1.readFile)(filePath, "utf-8");
209
- const withUid = content.replace(/^(\s*)uid:.*$/m, `$1uid: ${uid}`);
210
- const rewritten = rewriteInternalLinks(withUid, filePath, outputDir, baseURL);
211
- if (rewritten !== content) {
212
- await (0, utils_1.saveFile)(filePath, rewritten);
230
+ /**
231
+ * Adds the "Overview" entry for a directory, the first time it is reached.
232
+ *
233
+ * @param currentDir - Directory whose toc.yml is being built
234
+ * @param tocPath - Path of that toc.yml
235
+ * @param isRoot - Whether the directory is the generated documentation root
236
+ * @param outputAdapter - Destination the pages were written to
237
+ */
238
+ const addOverviewEntry = async (currentDir, tocPath, isRoot, outputAdapter) => {
239
+ if (isRoot) {
240
+ // Homepage is written after hooks run, so add Overview unconditionally.
241
+ await updateToc(tocPath, "Overview", "index.md", outputAdapter);
242
+ return;
243
+ }
244
+ // the section index lives wherever the pages were written, which is not the
245
+ // local filesystem when a custom adapter is configured
246
+ const indexPath = (0, node_path_1.join)(currentDir, "index.md");
247
+ if (typeof (await (0, output_1.readOptionalOutput)(indexPath, outputAdapter)) !== "string") {
248
+ return;
213
249
  }
214
- let currentDir = (0, node_path_1.resolve)((0, node_path_1.dirname)(filePath));
250
+ await updateToc(tocPath, `${(0, utils_1.capitalize)((0, node_path_1.basename)(currentDir))} Overview`, "index.md", outputAdapter);
251
+ };
252
+ /**
253
+ * Adds a page, and every directory above it, to the toc.yml chain.
254
+ *
255
+ * The walk goes up in the same path shape the page was written with: resolving
256
+ * here would hand an adapter an absolute `toc.yml` key next to a relative page
257
+ * key, and a key based destination would file them apart.
258
+ *
259
+ * @param page - The rendered page, its display name and the output root
260
+ * @param outputAdapter - Destination the pages were written to
261
+ */
262
+ const updateTocChain = async (page, outputAdapter) => {
263
+ const { filePath, name, outputDir, pagePath } = page;
264
+ const destination = outputAdapter ?? utils_1.fsOutputAdapter;
265
+ const seen = seenDirectories.get(destination) ?? new Set();
266
+ seenDirectories.set(destination, seen);
267
+ let currentRelativeDir = (0, node_path_1.dirname)(pagePath);
215
268
  let currentHref = (0, node_path_1.basename)(filePath);
216
269
  let currentName = name;
217
- while (currentDir.startsWith(graphqlRoot)) {
218
- const tocPath = (0, node_path_1.resolve)(currentDir, "toc.yml");
219
- if (!seenDirectories.has(currentDir)) {
220
- seenDirectories.add(currentDir);
221
- if (currentDir === graphqlRoot) {
222
- // Homepage is written after hooks run, so add Overview unconditionally.
223
- await updateToc(tocPath, "Overview", "index.md");
224
- }
225
- else {
226
- const indexPath = (0, node_path_1.resolve)(currentDir, "index.md");
227
- if (await (0, utils_1.fileExists)(indexPath)) {
228
- await updateToc(tocPath, `${(0, utils_1.capitalize)((0, node_path_1.basename)(currentDir))} Overview`, "index.md");
229
- }
230
- }
270
+ for (;;) {
271
+ const isRoot = currentRelativeDir === "." || currentRelativeDir === "";
272
+ const currentDir = isRoot ? outputDir : (0, node_path_1.join)(outputDir, currentRelativeDir);
273
+ const tocPath = (0, node_path_1.join)(currentDir, "toc.yml");
274
+ if (!seen.has(currentDir)) {
275
+ seen.add(currentDir);
276
+ await addOverviewEntry(currentDir, tocPath, isRoot, outputAdapter);
277
+ }
278
+ await updateToc(tocPath, currentName, currentHref, outputAdapter);
279
+ if (isRoot) {
280
+ return;
231
281
  }
232
- await updateToc(tocPath, currentName, currentHref);
233
- if (currentDir === graphqlRoot)
234
- break;
235
282
  currentHref = `${(0, node_path_1.basename)(currentDir)}/toc.yml`;
236
283
  currentName = (0, utils_1.capitalize)((0, node_path_1.basename)(currentDir));
237
- currentDir = (0, node_path_1.dirname)(currentDir);
284
+ currentRelativeDir = (0, node_path_1.dirname)(currentRelativeDir);
285
+ }
286
+ };
287
+ const afterRenderTypeEntitiesHook = async (event) => {
288
+ const { baseURL, filePath, name, outputAdapter, outputDir } = event.data;
289
+ const pagePath = (0, node_path_1.relative)(outputDir, filePath);
290
+ // Rewrite uid as a path-derived value to guarantee uniqueness across the site.
291
+ // e.g. operations/queries/continent.md → uid: operations-queries-continent
292
+ const uid = pagePath.replace(/\.mdx?$/, "").replaceAll(/[/\\]/g, "-");
293
+ const content = await (0, output_1.readOutput)(filePath, outputAdapter);
294
+ if (typeof content !== "string") {
295
+ return;
296
+ }
297
+ // [ \t]* rather than \s* keeps the match within a single line: \s also
298
+ // matches newlines, which would overlap with the `m`-flag line anchors and
299
+ // cause polynomial backtracking when no "uid:" line is present.
300
+ const withUid = content.replace(/^([ \t]*)uid:.*$/m, `$1uid: ${uid}`);
301
+ const rewritten = rewriteInternalLinks(withUid, filePath, outputDir, baseURL);
302
+ if (rewritten !== content) {
303
+ await (0, output_1.writeOutput)(filePath, rewritten, outputAdapter);
304
+ }
305
+ // A page outside the output root has no toc to belong to.
306
+ if (pagePath.startsWith("..")) {
307
+ return;
238
308
  }
309
+ await updateTocChain({ filePath, name, outputDir, pagePath }, outputAdapter);
239
310
  };
240
311
  exports.afterRenderTypeEntitiesHook = afterRenderTypeEntitiesHook;
@@ -66,6 +66,22 @@ export declare const formatMDXLink: ({ text, url }: TypeLink) => TypeLink;
66
66
  * @returns Formatted front matter block, or empty string if no lines provided
67
67
  */
68
68
  export declare const formatMDXFrontmatter: (_props: Maybe<FrontMatterOptions>, formatted: Maybe<string[]>) => MDXString;
69
+ /**
70
+ * Formats a permalink for a section header.
71
+ *
72
+ * Docusaurus 3.10 introduced a heading id syntax based on a native MDX comment,
73
+ * and deprecated the classic one. The braces of the comment must NOT be escaped:
74
+ * the heading id is extracted from a real MDX expression node, so an escaped
75
+ * token would be rendered as text. Older versions only support the classic
76
+ * syntax, whose braces must be escaped to remain valid MDX.
77
+ *
78
+ * @see https://docusaurus.io/blog/releases/3.10#strict-heading-ids
79
+ *
80
+ * @param id - The ID of the section header
81
+ * @param meta - Optional metadata used to detect the Docusaurus version
82
+ * @returns Formatted permalink string
83
+ */
84
+ export declare const formatMDXPermalink: (id: string, meta?: Maybe<MetaInfo>) => MDXString;
69
85
  /**
70
86
  * Creates a Docusaurus formatter.
71
87
  * Captures `meta` in closure so `formatMDXAdmonition` can detect the Docusaurus version.
@@ -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;AAejC,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,SAOF,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;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,UAAW,KAAK,CAAC,QAAQ,CAAC,KAAG,SAgB3D,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;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"}
@@ -8,10 +8,17 @@
8
8
  * @packageDocumentation
9
9
  */
10
10
  Object.defineProperty(exports, "__esModule", { value: true });
11
- exports.createMDXFormatter = exports.formatMDXFrontmatter = exports.formatMDXLink = exports.formatMDXNameEntity = exports.formatMDXSpecifiedByLink = exports.formatMDXDetails = exports.formatMDXBullet = exports.formatMDXAdmonition = exports.formatMDXBadge = exports.mdxDeclaration = void 0;
11
+ exports.createMDXFormatter = exports.formatMDXPermalink = exports.formatMDXFrontmatter = exports.formatMDXLink = exports.formatMDXNameEntity = exports.formatMDXSpecifiedByLink = exports.formatMDXDetails = exports.formatMDXBullet = exports.formatMDXAdmonition = exports.formatMDXBadge = exports.mdxDeclaration = void 0;
12
12
  const helpers_1 = require("@graphql-markdown/helpers");
13
13
  const utils_1 = require("@graphql-markdown/utils");
14
+ const defaults_1 = require("../defaults");
15
+ const version_1 = require("../version");
14
16
  const LINK_MDX_EXTENSION = ".mdx";
17
+ const DOCUSAURUS_FRAMEWORK = "docusaurus";
18
+ /** Docusaurus version using the legacy `:::caution` admonition syntax. */
19
+ const LEGACY_ADMONITION_VERSION = { major: 2 };
20
+ /** Docusaurus version introducing the MDX comment heading id syntax. */
21
+ const MDX_COMMENT_HEADING_ID_VERSION = { major: 3, minor: 10 };
15
22
  const DEFAULT_CSS_CLASSNAME = "badge--secondary";
16
23
  /** MDX component definitions prepended to every generated file. */
17
24
  exports.mdxDeclaration = `
@@ -42,8 +49,7 @@ exports.formatMDXBadge = formatMDXBadge;
42
49
  * @returns Formatted admonition string
43
50
  */
44
51
  const formatMDXAdmonition = ({ text, title, type }, meta) => {
45
- const isDocusaurus = meta?.generatorFrameworkName === "docusaurus";
46
- if (isDocusaurus && meta.generatorFrameworkVersion?.startsWith("2")) {
52
+ if ((0, version_1.isFrameworkVersion)(meta, DOCUSAURUS_FRAMEWORK, LEGACY_ADMONITION_VERSION)) {
47
53
  const oldType = type === "warning" ? "caution" : type;
48
54
  return `${utils_1.MARKDOWN_EOP}:::${oldType} ${title}${text}:::`;
49
55
  }
@@ -116,6 +122,28 @@ const formatMDXFrontmatter = (_props, formatted) => {
116
122
  return (0, helpers_1.formatMarkdownFrontmatter)(formatted, utils_1.FRONT_MATTER_DELIMITER, utils_1.MARKDOWN_EOL);
117
123
  };
118
124
  exports.formatMDXFrontmatter = formatMDXFrontmatter;
125
+ /**
126
+ * Formats a permalink for a section header.
127
+ *
128
+ * Docusaurus 3.10 introduced a heading id syntax based on a native MDX comment,
129
+ * and deprecated the classic one. The braces of the comment must NOT be escaped:
130
+ * the heading id is extracted from a real MDX expression node, so an escaped
131
+ * token would be rendered as text. Older versions only support the classic
132
+ * syntax, whose braces must be escaped to remain valid MDX.
133
+ *
134
+ * @see https://docusaurus.io/blog/releases/3.10#strict-heading-ids
135
+ *
136
+ * @param id - The ID of the section header
137
+ * @param meta - Optional metadata used to detect the Docusaurus version
138
+ * @returns Formatted permalink string
139
+ */
140
+ const formatMDXPermalink = (id, meta) => {
141
+ if ((0, version_1.isFrameworkVersionAtLeast)(meta, DOCUSAURUS_FRAMEWORK, MDX_COMMENT_HEADING_ID_VERSION)) {
142
+ return `{/* #${id} */}`;
143
+ }
144
+ return (0, defaults_1.formatMDXEscapedPermalink)(id);
145
+ };
146
+ exports.formatMDXPermalink = formatMDXPermalink;
119
147
  /**
120
148
  * Creates a Docusaurus formatter.
121
149
  * Captures `meta` in closure so `formatMDXAdmonition` can detect the Docusaurus version.
@@ -133,6 +161,9 @@ const createMDXFormatter = (meta) => {
133
161
  formatMDXFrontmatter: exports.formatMDXFrontmatter,
134
162
  formatMDXLink: exports.formatMDXLink,
135
163
  formatMDXNameEntity: exports.formatMDXNameEntity,
164
+ formatMDXPermalink: (id) => {
165
+ return (0, exports.formatMDXPermalink)(id, meta);
166
+ },
136
167
  formatMDXSpecifiedByLink: exports.formatMDXSpecifiedByLink,
137
168
  };
138
169
  };
@@ -7,6 +7,15 @@
7
7
  * @packageDocumentation
8
8
  */
9
9
  import type { AdmonitionType, Badge, Formatter, Maybe, MDXString, MetaInfo, TypeLink } from "@graphql-markdown/types";
10
+ /**
11
+ * Formats a permalink for a section header using the Fumadocs `[#id]` syntax.
12
+ *
13
+ * @see https://www.fumadocs.dev/docs/headless/mdx/headings
14
+ *
15
+ * @param id - The ID of the section header
16
+ * @returns Formatted permalink string
17
+ */
18
+ export declare const formatMDXPermalink: (id: string) => MDXString;
10
19
  /** File extension used for generated pages. */
11
20
  export declare const mdxExtension: ".mdx";
12
21
  /** MDX import statement prepended to every generated file to register Fumadocs and MUI components. */
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fumadocs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,SAAS,EACT,KAAK,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAUjC,+CAA+C;AAC/C,eAAO,MAAM,YAAY,EAAG,MAAe,CAAC;AAE5C,sGAAsG;AACtG,eAAO,MAAM,cAAc,EAAE,SAGf,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;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAAU,QAAQ,KAAG,QAE9C,CAAC;AAEF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAW5D,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fumadocs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,SAAS,EACT,KAAK,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAUjC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,OAAQ,MAAM,KAAG,SAE/C,CAAC;AAEF,+CAA+C;AAC/C,eAAO,MAAM,YAAY,EAAG,MAAe,CAAC;AAE5C,sGAAsG;AACtG,eAAO,MAAM,cAAc,EAAE,SAGf,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;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAAU,QAAQ,KAAG,QAE9C,CAAC;AAEF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAY5D,CAAC"}
@@ -8,9 +8,21 @@
8
8
  * @packageDocumentation
9
9
  */
10
10
  Object.defineProperty(exports, "__esModule", { value: true });
11
- exports.createMDXFormatter = exports.formatMDXSpecifiedByLink = exports.formatMDXNameEntity = exports.formatMDXFrontmatter = exports.formatMDXDetails = exports.formatMDXBullet = exports.formatMDXLink = exports.formatMDXAdmonition = exports.formatMDXBadge = exports.mdxDeclaration = exports.mdxExtension = void 0;
11
+ exports.createMDXFormatter = exports.formatMDXSpecifiedByLink = exports.formatMDXNameEntity = exports.formatMDXFrontmatter = exports.formatMDXDetails = exports.formatMDXBullet = exports.formatMDXLink = exports.formatMDXAdmonition = exports.formatMDXBadge = exports.mdxDeclaration = exports.mdxExtension = exports.formatMDXPermalink = void 0;
12
12
  const utils_1 = require("@graphql-markdown/utils");
13
13
  const defaults_1 = require("../defaults");
14
+ /**
15
+ * Formats a permalink for a section header using the Fumadocs `[#id]` syntax.
16
+ *
17
+ * @see https://www.fumadocs.dev/docs/headless/mdx/headings
18
+ *
19
+ * @param id - The ID of the section header
20
+ * @returns Formatted permalink string
21
+ */
22
+ const formatMDXPermalink = (id) => {
23
+ return `[#${id}]`;
24
+ };
25
+ exports.formatMDXPermalink = formatMDXPermalink;
14
26
  /** File extension used for generated pages. */
15
27
  exports.mdxExtension = ".mdx";
16
28
  /** MDX import statement prepended to every generated file to register Fumadocs and MUI components. */
@@ -71,6 +83,7 @@ const createMDXFormatter = (_meta) => {
71
83
  formatMDXFrontmatter: defaults_1.formatMDXFrontmatter,
72
84
  formatMDXLink: exports.formatMDXLink,
73
85
  formatMDXNameEntity: defaults_1.formatMDXNameEntity,
86
+ formatMDXPermalink: exports.formatMDXPermalink,
74
87
  formatMDXSpecifiedByLink: defaults_1.formatMDXSpecifiedByLink,
75
88
  };
76
89
  };
@@ -7,9 +7,11 @@
7
7
  * @packageDocumentation
8
8
  */
9
9
  import type { AdmonitionType, Badge, CollapsibleOption, Formatter, FrontMatterOptions, Maybe, MDXString, MetaInfo, TypeLink } from "@graphql-markdown/types";
10
- import { formatMDXBullet } from "../defaults";
10
+ import { formatMDXBullet, formatMDXPermalink } from "../defaults";
11
+ export { formatMDXPermalink } from "../defaults";
11
12
  export declare const __default: {
12
13
  formatMDXBullet: typeof formatMDXBullet;
14
+ formatMDXPermalink: typeof formatMDXPermalink;
13
15
  };
14
16
  /** File extension used for generated pages — HonKit renders plain Markdown to HTML. */
15
17
  export declare const mdxExtension: ".md";
@@ -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,MAAM,aAAa,CAAC;AAE9C,eAAO,MAAM,SAAS;;CAAsB,CAAC;AAE7C,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,SAW5D,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;AAQjC,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAElE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,eAAO,MAAM,SAAS;;;CAA0C,CAAC;AAEjE,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"}
@@ -8,11 +8,13 @@
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 = void 0;
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;
12
12
  const helpers_1 = require("@graphql-markdown/helpers");
13
13
  const utils_1 = require("@graphql-markdown/utils");
14
14
  const defaults_1 = require("../defaults");
15
- exports.__default = { formatMDXBullet: defaults_1.formatMDXBullet };
15
+ var defaults_2 = require("../defaults");
16
+ Object.defineProperty(exports, "formatMDXPermalink", { enumerable: true, get: function () { return defaults_2.formatMDXPermalink; } });
17
+ exports.__default = { formatMDXBullet: defaults_1.formatMDXBullet, formatMDXPermalink: defaults_1.formatMDXPermalink };
16
18
  /** File extension used for generated pages — HonKit renders plain Markdown to HTML. */
17
19
  exports.mdxExtension = ".md";
18
20
  /** Shared default badge theme used across this preset. */
@@ -129,6 +131,7 @@ const createMDXFormatter = (_meta) => {
129
131
  formatMDXFrontmatter: exports.formatMDXFrontmatter,
130
132
  formatMDXLink: exports.formatMDXLink,
131
133
  formatMDXNameEntity: exports.formatMDXNameEntity,
134
+ formatMDXPermalink: defaults_1.formatMDXPermalink,
132
135
  formatMDXSpecifiedByLink: exports.formatMDXSpecifiedByLink,
133
136
  };
134
137
  };
@@ -17,17 +17,14 @@ export declare const formatMDXBadge: ({ text }: Badge) => MDXString;
17
17
  /**
18
18
  * Formats an admonition using Hugo GitHub-style alert syntax (`> [!TYPE]`).
19
19
  * Requires Hugo 0.132 or later.
20
- * @param text - The admonition body text
21
- * @param title - Optional title rendered as bold text after the alert type line
22
- * @param type - Admonition type (e.g. `note`, `warning`, `danger`) mapped via {@link ALERT_TYPE_MAP}
20
+ * @param admonition - Admonition data with text, optional title, and type (e.g. `note`, `warning`, `danger`) mapped via {@link ALERT_TYPE_MAP}
23
21
  * @param _meta - Unused metadata parameter
24
22
  * @returns Formatted blockquote alert string
25
23
  */
26
24
  export declare const formatMDXAdmonition: ({ text, title, type }: AdmonitionType, _meta: Maybe<MetaInfo>) => MDXString;
27
25
  /**
28
26
  * Formats a collapsible block as an HTML `<details>` element.
29
- * @param dataOpen - Label shown when the section is collapsed (used as `<summary>` text)
30
- * @param dataClose - Label shown inside the expanded section
27
+ * @param option - Configuration for open/close label text
31
28
  * @returns HTML `<details>`/`<summary>` block string
32
29
  */
33
30
  export declare const formatMDXDetails: ({ dataOpen, dataClose, }: CollapsibleOption) => MDXString;
@@ -44,12 +41,11 @@ export declare const formatMDXFrontmatter: (props: Maybe<FrontMatterOptions>, fo
44
41
  /**
45
42
  * Strips the `.md` extension from internal links.
46
43
  * Hugo serves pages at extensionless URLs — links with `.md` would 404 in the built site.
47
- * @param text - Display text for the link
48
- * @param url - Link target URL, with `.md` extension removed if present
44
+ * @param link - Link data with text and URL; `.md` extension is removed from the URL if present
49
45
  * @returns Link object with the cleaned URL
50
46
  */
51
47
  export declare const formatMDXLink: ({ text, url }: TypeLink) => TypeLink;
52
- export { formatMDXBullet, formatMDXNameEntity, formatMDXSpecifiedByLink, } from "../defaults";
48
+ export { formatMDXBullet, formatMDXNameEntity, formatMDXPermalink, formatMDXSpecifiedByLink, } from "../defaults";
53
49
  /**
54
50
  * Creates a Hugo formatter.
55
51
  * @param _meta - Unused metadata parameter