@graphql-markdown/formatters 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/README.md +106 -0
  2. package/dist/defaults.d.ts +63 -0
  3. package/dist/defaults.d.ts.map +1 -0
  4. package/dist/defaults.js +93 -0
  5. package/dist/docfx/index.d.ts +56 -0
  6. package/dist/docfx/index.d.ts.map +1 -0
  7. package/dist/docfx/index.js +184 -0
  8. package/dist/docfx.d.ts +20 -0
  9. package/dist/docfx.d.ts.map +1 -0
  10. package/dist/docfx.js +71 -0
  11. package/dist/docusaurus/index.d.ts +76 -0
  12. package/dist/docusaurus/index.d.ts.map +1 -0
  13. package/dist/docusaurus/index.js +139 -0
  14. package/dist/docusaurus.d.ts +20 -0
  15. package/dist/docusaurus.d.ts.map +1 -0
  16. package/dist/docusaurus.js +72 -0
  17. package/dist/fumadocs/index.d.ts +42 -0
  18. package/dist/fumadocs/index.d.ts.map +1 -0
  19. package/dist/fumadocs/index.js +80 -0
  20. package/dist/honkit/index.d.ts +75 -0
  21. package/dist/honkit/index.d.ts.map +1 -0
  22. package/dist/honkit/index.js +135 -0
  23. package/dist/hugo/index.d.ts +70 -0
  24. package/dist/hugo/index.d.ts.map +1 -0
  25. package/dist/hugo/index.js +143 -0
  26. package/dist/hugo.d.ts +20 -0
  27. package/dist/hugo.d.ts.map +1 -0
  28. package/dist/hugo.js +68 -0
  29. package/dist/index.d.ts +26 -0
  30. package/dist/index.d.ts.map +1 -0
  31. package/dist/index.js +61 -0
  32. package/dist/mdbook/index.d.ts +69 -0
  33. package/dist/mdbook/index.d.ts.map +1 -0
  34. package/dist/mdbook/index.js +176 -0
  35. package/dist/mdbook.d.ts +20 -0
  36. package/dist/mdbook.d.ts.map +1 -0
  37. package/dist/mdbook.js +51 -0
  38. package/dist/mkdocs/index.d.ts +69 -0
  39. package/dist/mkdocs/index.d.ts.map +1 -0
  40. package/dist/mkdocs/index.js +138 -0
  41. package/dist/mkdocs.d.ts +19 -0
  42. package/dist/mkdocs.d.ts.map +1 -0
  43. package/dist/mkdocs.js +65 -0
  44. package/dist/starlight/index.d.ts +65 -0
  45. package/dist/starlight/index.d.ts.map +1 -0
  46. package/dist/starlight/index.js +113 -0
  47. package/dist/vocs/index.d.ts +55 -0
  48. package/dist/vocs/index.d.ts.map +1 -0
  49. package/dist/vocs/index.js +101 -0
  50. package/package.json +231 -0
@@ -0,0 +1,176 @@
1
+ "use strict";
2
+ /**
3
+ * mdBook formatter for GraphQL documentation output.
4
+ *
5
+ * Produces Markdown compatible with Rust's mdBook static site generator.
6
+ * Front matter is suppressed because mdBook renders it as literal content.
7
+ * Admonitions use mdBook's native `> [!TYPE]` syntax.
8
+ * Exports `afterRenderFilesHook` to build `SUMMARY.md` after all pages are written.
9
+ *
10
+ * @packageDocumentation
11
+ */
12
+ Object.defineProperty(exports, "__esModule", { value: true });
13
+ exports.afterRenderFilesHook = exports.createMDXFormatter = exports.formatMDXSpecifiedByLink = exports.formatMDXNameEntity = exports.formatMDXBullet = exports.formatMDXLink = exports.mdxExtension = exports.formatMDXFrontmatter = exports.formatMDXDetails = exports.formatMDXAdmonition = exports.formatMDXBadge = void 0;
14
+ const node_path_1 = require("node:path");
15
+ const helpers_1 = require("@graphql-markdown/helpers");
16
+ const utils_1 = require("@graphql-markdown/utils");
17
+ const defaults_1 = require("../defaults");
18
+ /**
19
+ * Formats a badge as Markdown bold text — mdBook has no badge component.
20
+ * @param badge - Badge data containing text
21
+ * @returns Formatted bold text string
22
+ */
23
+ const formatMDXBadge = ({ text }) => {
24
+ return `**${text}**`;
25
+ };
26
+ exports.formatMDXBadge = formatMDXBadge;
27
+ /**
28
+ * Formats an admonition using mdBook's native admonition syntax (`> [!TYPE]`).
29
+ * Uses `type` for the admonition tag and `title` as an optional override label.
30
+ * @param admonition - Admonition data with text, title, and type
31
+ * @param _meta - Unused metadata parameter
32
+ * @returns Formatted admonition string
33
+ */
34
+ const formatMDXAdmonition = ({ text, title, type }, _meta) => {
35
+ const tag = type.toUpperCase();
36
+ const titleLine = title?.trim() ? `> ${title.trim()}${utils_1.MARKDOWN_EOL}` : "";
37
+ return `${utils_1.MARKDOWN_EOP}> [!${tag}]${utils_1.MARKDOWN_EOL}${titleLine}${(0, helpers_1.quoteMarkdownLines)(text, utils_1.MARKDOWN_EOL)}${utils_1.MARKDOWN_EOL}`;
38
+ };
39
+ exports.formatMDXAdmonition = formatMDXAdmonition;
40
+ /**
41
+ * Renders a deprecated section as a bold inline label.
42
+ *
43
+ * A fixed heading level would break hierarchy when this section is nested
44
+ * inside field entries at varying depths. Bold text is CommonMark-safe and
45
+ * works at any nesting level without affecting the heading outline.
46
+ *
47
+ * The output is split on `\r` to produce [openSection, closeSection] as the
48
+ * printer expects — the deprecated items are inserted between the two halves.
49
+ * @param option - Configuration for the section label
50
+ * @returns Bold label + split marker
51
+ */
52
+ const formatMDXDetails = ({ dataOpen, }) => {
53
+ return `${utils_1.MARKDOWN_EOP}**${(0, utils_1.firstUppercase)(dataOpen.toLowerCase())}**${utils_1.MARKDOWN_EOL}\r${utils_1.MARKDOWN_EOP}`;
54
+ };
55
+ exports.formatMDXDetails = formatMDXDetails;
56
+ /**
57
+ * Replaces front matter with an H1 title heading.
58
+ * mdBook renders `---` YAML blocks as literal content, so front matter is
59
+ * suppressed entirely. The page title is emitted as `# Title` instead.
60
+ * @returns `# Title\n` when a title is available, otherwise an empty string
61
+ */
62
+ const formatMDXFrontmatter = (_props, formatted) => {
63
+ const title = (0, helpers_1.extractFrontmatterTitle)(formatted);
64
+ return (title ? `# ${title}${utils_1.MARKDOWN_EOL}` : "");
65
+ };
66
+ exports.formatMDXFrontmatter = formatMDXFrontmatter;
67
+ /** mdBook expects `.md` files; override the default `.mdx` extension. */
68
+ exports.mdxExtension = ".md";
69
+ /**
70
+ * Returns the link unchanged — mdBook resolves `.md` links natively.
71
+ * @param link - Link data with URL and text
72
+ * @returns The link with `.md` appended to extensionless absolute paths
73
+ */
74
+ const formatMDXLink = (link) => {
75
+ const { url } = link;
76
+ if (!url) {
77
+ return link;
78
+ }
79
+ return {
80
+ ...link,
81
+ url: (0, helpers_1.appendExtensionToAbsolutePathWithoutExtension)(url, exports.mdxExtension),
82
+ };
83
+ };
84
+ exports.formatMDXLink = formatMDXLink;
85
+ var defaults_2 = require("../defaults");
86
+ Object.defineProperty(exports, "formatMDXBullet", { enumerable: true, get: function () { return defaults_2.formatMDXBullet; } });
87
+ Object.defineProperty(exports, "formatMDXNameEntity", { enumerable: true, get: function () { return defaults_2.formatMDXNameEntity; } });
88
+ Object.defineProperty(exports, "formatMDXSpecifiedByLink", { enumerable: true, get: function () { return defaults_2.formatMDXSpecifiedByLink; } });
89
+ /**
90
+ * Creates an mdBook formatter.
91
+ * @param _meta - Unused metadata parameter
92
+ * @returns A complete {@link Formatter} implementation for mdBook output
93
+ */
94
+ const createMDXFormatter = (_meta) => {
95
+ return {
96
+ formatMDXBadge: exports.formatMDXBadge,
97
+ formatMDXAdmonition: exports.formatMDXAdmonition,
98
+ formatMDXBullet: defaults_1.formatMDXBullet,
99
+ formatMDXDetails: exports.formatMDXDetails,
100
+ formatMDXFrontmatter: exports.formatMDXFrontmatter,
101
+ formatMDXLink: exports.formatMDXLink,
102
+ formatMDXNameEntity: defaults_1.formatMDXNameEntity,
103
+ formatMDXSpecifiedByLink: defaults_1.formatMDXSpecifiedByLink,
104
+ };
105
+ };
106
+ exports.createMDXFormatter = createMDXFormatter;
107
+ const SECTION_ORDER = [
108
+ "Queries",
109
+ "Mutations",
110
+ "Subscriptions",
111
+ "Directives",
112
+ "Objects",
113
+ "Interfaces",
114
+ "Unions",
115
+ "Inputs",
116
+ "Enums",
117
+ "Scalars",
118
+ ];
119
+ /**
120
+ * Builds `src/SUMMARY.md` after all pages have been written.
121
+ *
122
+ * mdBook requires every page to be listed in `SUMMARY.md` before the site can
123
+ * be built. This hook collects all rendered pages from the event, groups them
124
+ * by top-level section (Operations / Types) and category, then writes the file.
125
+ */
126
+ const afterRenderFilesHook = async (event) => {
127
+ const { baseURL, outputDir, rootDir, pages } = event.data;
128
+ const summaryPath = (0, node_path_1.join)(rootDir, "SUMMARY.md");
129
+ const allPages = pages
130
+ .flat()
131
+ .filter((p) => {
132
+ return p !== null && typeof p === "object";
133
+ });
134
+ const grouped = new Map();
135
+ for (const { category, filePath, name } of allPages) {
136
+ const topSegment = (0, node_path_1.relative)(outputDir, (0, node_path_1.dirname)(filePath)).split(/[\\/]/)[0];
137
+ const topSection = (0, utils_1.firstUppercase)(topSegment);
138
+ const key = `${topSection}/${category}`;
139
+ if (!grouped.has(key)) {
140
+ grouped.set(key, { topSection, category, entries: [] });
141
+ }
142
+ grouped.get(key).entries.push({ filePath, name });
143
+ }
144
+ const sorted = [...grouped.values()].sort((a, b) => {
145
+ if (a.topSection !== b.topSection) {
146
+ return a.topSection === "Operations" ? -1 : 1;
147
+ }
148
+ return (SECTION_ORDER.indexOf(a.category) -
149
+ SECTION_ORDER.indexOf(b.category));
150
+ });
151
+ const lines = [
152
+ "# Summary",
153
+ "",
154
+ "[Introduction](introduction.md)",
155
+ "",
156
+ "---",
157
+ "",
158
+ `[GraphQL API Reference](${baseURL}/index${exports.mdxExtension}})`,
159
+ "",
160
+ ];
161
+ let lastTopSection = null;
162
+ for (const { topSection, category, entries } of sorted) {
163
+ if (topSection !== lastTopSection) {
164
+ lines.push(`# ${topSection}`, "");
165
+ lastTopSection = topSection;
166
+ }
167
+ lines.push(`- [${category}]()`);
168
+ for (const { filePath, name: pageName } of entries) {
169
+ const relPath = (0, node_path_1.relative)(rootDir, filePath).replaceAll("\\", "/");
170
+ lines.push(` - [${pageName}](${relPath})`);
171
+ }
172
+ lines.push("");
173
+ }
174
+ await (0, utils_1.saveFile)(summaryPath, lines.join("\n"));
175
+ };
176
+ exports.afterRenderFilesHook = afterRenderFilesHook;
@@ -0,0 +1,20 @@
1
+ /**
2
+ * mdBook formatter for GraphQL documentation output.
3
+ *
4
+ * Produces Markdown compatible with Rust's mdBook static site generator.
5
+ * Front matter is suppressed because mdBook renders it as literal content.
6
+ * Admonitions fall back to blockquote style as mdBook has no native support.
7
+ *
8
+ * @packageDocumentation
9
+ */
10
+ import type { AdmonitionType, Badge, CollapsibleOption, Formatter, FrontMatterOptions, Maybe, MDXString, MetaInfo, TypeLink } from "@graphql-markdown/types";
11
+ export declare const formatMDXBadge: ({ text }: Badge) => MDXString;
12
+ export declare const formatMDXAdmonition: ({ text, title, type }: AdmonitionType, _meta: Maybe<MetaInfo>) => MDXString;
13
+ export declare const formatMDXBullet: (text?: string) => MDXString;
14
+ export declare const formatMDXDetails: ({ dataOpen, dataClose, }: CollapsibleOption) => MDXString;
15
+ export declare const formatMDXFrontmatter: (_props: Maybe<FrontMatterOptions>, _formatted: Maybe<string[]>) => MDXString;
16
+ export declare const formatMDXLink: (link: TypeLink) => TypeLink;
17
+ export declare const formatMDXNameEntity: (name: string, parentType?: Maybe<string>) => MDXString;
18
+ export declare const formatMDXSpecifiedByLink: (url: string) => MDXString;
19
+ export declare const createMDXFormatter: (_meta?: Maybe<MetaInfo>) => Formatter;
20
+ //# sourceMappingURL=mdbook.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"mdbook.d.ts","sourceRoot":"","sources":["../src/mdbook.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;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;AASjC,eAAO,MAAM,cAAc,aAAc,KAAK,KAAG,SACX,CAAC;AAEvC,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAGF,CAAC;AAEF,eAAO,MAAM,eAAe,qBAAgB,SACR,CAAC;AAErC,eAAO,MAAM,gBAAgB,6BAG1B,iBAAiB,KAAG,SAC0L,CAAC;AAGlN,eAAO,MAAM,oBAAoB,WACvB,KAAK,CAAC,kBAAkB,CAAC,cACrB,KAAK,CAAC,MAAM,EAAE,CAAC,KAC1B,SAA4B,CAAC;AAEhC,eAAO,MAAM,aAAa,SAAU,QAAQ,KAAG,QAAgB,CAAC;AAEhE,eAAO,MAAM,mBAAmB,SACxB,MAAM,eACC,KAAK,CAAC,MAAM,CAAC,KACzB,SAGF,CAAC;AAEF,eAAO,MAAM,wBAAwB,QAAS,MAAM,KAAG,SACb,CAAC;AAE3C,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAS3D,CAAC"}
package/dist/mdbook.js ADDED
@@ -0,0 +1,51 @@
1
+ "use strict";
2
+ /**
3
+ * mdBook formatter for GraphQL documentation output.
4
+ *
5
+ * Produces Markdown compatible with Rust's mdBook static site generator.
6
+ * Front matter is suppressed because mdBook renders it as literal content.
7
+ * Admonitions fall back to blockquote style as mdBook has no native support.
8
+ *
9
+ * @packageDocumentation
10
+ */
11
+ Object.defineProperty(exports, "__esModule", { value: true });
12
+ exports.createMDXFormatter = exports.formatMDXSpecifiedByLink = exports.formatMDXNameEntity = exports.formatMDXLink = exports.formatMDXFrontmatter = exports.formatMDXDetails = exports.formatMDXBullet = exports.formatMDXAdmonition = exports.formatMDXBadge = void 0;
13
+ const utils_1 = require("@graphql-markdown/utils");
14
+ const quoteLines = (text) => text
15
+ .split(utils_1.MARKDOWN_EOL)
16
+ .map((line) => `> ${line}`)
17
+ .join(utils_1.MARKDOWN_EOL);
18
+ const formatMDXBadge = ({ text }) => `**${text}**`;
19
+ exports.formatMDXBadge = formatMDXBadge;
20
+ const formatMDXAdmonition = ({ text, title, type }, _meta) => {
21
+ const label = (title ?? type).toUpperCase();
22
+ return `${utils_1.MARKDOWN_EOP}> **${label}**${utils_1.MARKDOWN_EOL}${quoteLines(text)}${utils_1.MARKDOWN_EOL}`;
23
+ };
24
+ exports.formatMDXAdmonition = formatMDXAdmonition;
25
+ const formatMDXBullet = (text = "") => `&bull;&nbsp;${text}`;
26
+ exports.formatMDXBullet = formatMDXBullet;
27
+ const formatMDXDetails = ({ dataOpen, dataClose, }) => `${utils_1.MARKDOWN_EOP}<details>${utils_1.MARKDOWN_EOL}<summary>${dataOpen}</summary>${utils_1.MARKDOWN_EOL}${utils_1.MARKDOWN_EOL}\r${utils_1.MARKDOWN_EOL}${utils_1.MARKDOWN_EOL}<em>${dataClose}</em>${utils_1.MARKDOWN_EOL}</details>${utils_1.MARKDOWN_EOP}`;
28
+ exports.formatMDXDetails = formatMDXDetails;
29
+ // mdBook does not support front matter — rendering it would produce literal --- and YAML as content
30
+ const formatMDXFrontmatter = (_props, _formatted) => "";
31
+ exports.formatMDXFrontmatter = formatMDXFrontmatter;
32
+ const formatMDXLink = (link) => link;
33
+ exports.formatMDXLink = formatMDXLink;
34
+ const formatMDXNameEntity = (name, parentType) => {
35
+ const parentName = parentType ? `${parentType}.` : "";
36
+ return `\`${parentName}${name}\``;
37
+ };
38
+ exports.formatMDXNameEntity = formatMDXNameEntity;
39
+ const formatMDXSpecifiedByLink = (url) => `[Specification ⎘](${url})`;
40
+ exports.formatMDXSpecifiedByLink = formatMDXSpecifiedByLink;
41
+ const createMDXFormatter = (_meta) => ({
42
+ formatMDXBadge: exports.formatMDXBadge,
43
+ formatMDXAdmonition: exports.formatMDXAdmonition,
44
+ formatMDXBullet: exports.formatMDXBullet,
45
+ formatMDXDetails: exports.formatMDXDetails,
46
+ formatMDXFrontmatter: exports.formatMDXFrontmatter,
47
+ formatMDXLink: exports.formatMDXLink,
48
+ formatMDXNameEntity: exports.formatMDXNameEntity,
49
+ formatMDXSpecifiedByLink: exports.formatMDXSpecifiedByLink,
50
+ });
51
+ exports.createMDXFormatter = createMDXFormatter;
@@ -0,0 +1,69 @@
1
+ /**
2
+ * MkDocs formatter for GraphQL documentation output.
3
+ *
4
+ * Produces Markdown compatible with MkDocs admonitions, HTML details blocks,
5
+ * and visible page headings.
6
+ *
7
+ * @packageDocumentation
8
+ */
9
+ import type { AdmonitionType, Badge, CollapsibleOption, Formatter, FrontMatterOptions, Maybe, MDXString, MetaInfo, RenderTypeEntitiesHook } from "@graphql-markdown/types";
10
+ export declare const __default: {
11
+ formatMDXBullet: (text?: string) => MDXString;
12
+ formatMDXLink: (link: import("@graphql-markdown/types").TypeLink) => import("@graphql-markdown/types").TypeLink;
13
+ };
14
+ /**
15
+ * Formats a badge as an inline HTML mark element.
16
+ * @param badge - Badge data containing text and optional classname
17
+ * @returns Formatted badge string
18
+ */
19
+ export declare const formatMDXBadge: ({ text }: Badge) => MDXString;
20
+ /**
21
+ * Formats an admonition using MkDocs Material `!!!` block syntax.
22
+ * Content is indented by 4 spaces as required by the spec.
23
+ * @param admonition - Admonition data with text, title, and type
24
+ * @param _meta - Unused metadata parameter
25
+ * @returns Formatted admonition string
26
+ */
27
+ export declare const formatMDXAdmonition: ({ text, title, type }: AdmonitionType, _meta: Maybe<MetaInfo>) => MDXString;
28
+ /**
29
+ * Formats a collapsible block as an HTML `<details>` element.
30
+ * @param option - Configuration for open/close label text
31
+ * @returns Formatted collapsible string
32
+ */
33
+ export declare const formatMDXDetails: ({ dataOpen, dataClose, }: CollapsibleOption) => MDXString;
34
+ /**
35
+ * Formats page title as a visible H1 heading.
36
+ * @param _props - Front matter options (unused)
37
+ * @param formatted - Pre-formatted front matter lines
38
+ * @returns Visible heading string, or empty string if no title is available
39
+ */
40
+ export declare const formatMDXFrontmatter: (_props: Maybe<FrontMatterOptions>, formatted: Maybe<string[]>) => MDXString;
41
+ /**
42
+ * Formats a named entity as a backtick code span.
43
+ * @param name - Entity name
44
+ * @param parentType - Optional parent type name for qualified references
45
+ * @returns Formatted entity reference string
46
+ */
47
+ export declare const formatMDXNameEntity: (name: string, parentType?: Maybe<string>) => MDXString;
48
+ /**
49
+ * Formats a "specified by" link as a standard Markdown link.
50
+ * @param url - URL to the specification
51
+ * @returns Formatted specification link string
52
+ */
53
+ export declare const formatMDXSpecifiedByLink: (url: string) => MDXString;
54
+ /** File extension used for generated pages — MkDocs uses standard Markdown (.md) files. */
55
+ export declare const mdxExtension: ".md";
56
+ /**
57
+ * Lifecycle hook that rewrites generated absolute GraphQL-Markdown links
58
+ * into page-relative `.md` links compatible with MkDocs validation.
59
+ * @param event - Hook payload containing the current file path and renderer output context
60
+ */
61
+ export declare const afterRenderTypeEntitiesHook: RenderTypeEntitiesHook;
62
+ export { formatMDXBullet } from "../defaults";
63
+ /**
64
+ * Creates an MkDocs Material formatter.
65
+ * @param _meta - Unused metadata parameter
66
+ * @returns A complete {@link Formatter} implementation for MkDocs Material output
67
+ */
68
+ export declare const createMDXFormatter: (_meta?: Maybe<MetaInfo>) => Formatter;
69
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +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;AAcjC,eAAO,MAAM,SAAS;;;CAGrB,CAAC;AAmCF;;;;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,SAGF,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,sBAoBzC,CAAC;AAEF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAW5D,CAAC"}
@@ -0,0 +1,138 @@
1
+ "use strict";
2
+ /**
3
+ * MkDocs formatter for GraphQL documentation output.
4
+ *
5
+ * Produces Markdown compatible with MkDocs admonitions, HTML details blocks,
6
+ * and visible page headings.
7
+ *
8
+ * @packageDocumentation
9
+ */
10
+ Object.defineProperty(exports, "__esModule", { value: true });
11
+ exports.createMDXFormatter = exports.formatMDXBullet = exports.afterRenderTypeEntitiesHook = exports.mdxExtension = exports.formatMDXSpecifiedByLink = exports.formatMDXNameEntity = exports.formatMDXFrontmatter = exports.formatMDXDetails = exports.formatMDXAdmonition = exports.formatMDXBadge = exports.__default = void 0;
12
+ const helpers_1 = require("@graphql-markdown/helpers");
13
+ const utils_1 = require("@graphql-markdown/utils");
14
+ const defaults_1 = require("../defaults");
15
+ exports.__default = {
16
+ formatMDXBullet: defaults_1.formatMDXBullet,
17
+ formatMDXLink: defaults_1.formatMDXLink,
18
+ };
19
+ const ADMONITION_TYPE_MAP = {
20
+ note: "note",
21
+ tip: "tip",
22
+ info: "info",
23
+ warning: "warning",
24
+ danger: "danger",
25
+ deprecated: "warning",
26
+ caution: "warning",
27
+ success: "success",
28
+ };
29
+ const rewriteInternalLinks = (content, filePath, outputDir, baseURL) => {
30
+ return content.replaceAll(/\]\((\/[^)\s#]+)(#[^)\s]+)?\)/g, (_match, urlPath, hash = "") => {
31
+ const relativePath = (0, utils_1.toRelativeGeneratedDocLink)({
32
+ baseURL,
33
+ currentFilePath: filePath,
34
+ outputDir,
35
+ targetUrlPath: urlPath,
36
+ });
37
+ const target = relativePath ?? urlPath;
38
+ return `](${target}${hash})`;
39
+ });
40
+ };
41
+ /**
42
+ * Formats a badge as an inline HTML mark element.
43
+ * @param badge - Badge data containing text and optional classname
44
+ * @returns Formatted badge string
45
+ */
46
+ const formatMDXBadge = ({ text }) => {
47
+ return `<mark class="gqlmd-mkdocs-badge">${text}</mark>`;
48
+ };
49
+ exports.formatMDXBadge = formatMDXBadge;
50
+ /**
51
+ * Formats an admonition using MkDocs Material `!!!` block syntax.
52
+ * Content is indented by 4 spaces as required by the spec.
53
+ * @param admonition - Admonition data with text, title, and type
54
+ * @param _meta - Unused metadata parameter
55
+ * @returns Formatted admonition string
56
+ */
57
+ const formatMDXAdmonition = ({ text, title, type }, _meta) => {
58
+ const mkdocsType = ADMONITION_TYPE_MAP[type.toLowerCase()] ?? "note";
59
+ const titleAttr = title ? ` "${title}"` : "";
60
+ return `${utils_1.MARKDOWN_EOP}!!! ${mkdocsType}${titleAttr}${utils_1.MARKDOWN_EOL}${(0, helpers_1.indentMarkdownLines)(text, 4, utils_1.MARKDOWN_EOL)}${utils_1.MARKDOWN_EOL}`;
61
+ };
62
+ exports.formatMDXAdmonition = formatMDXAdmonition;
63
+ /**
64
+ * Formats a collapsible block as an HTML `<details>` element.
65
+ * @param option - Configuration for open/close label text
66
+ * @returns Formatted collapsible string
67
+ */
68
+ const formatMDXDetails = ({ dataOpen, dataClose, }) => {
69
+ return `${utils_1.MARKDOWN_EOP}<details>${utils_1.MARKDOWN_EOL}<summary>${dataOpen}</summary>${utils_1.MARKDOWN_EOL}${utils_1.MARKDOWN_EOL}\r${utils_1.MARKDOWN_EOL}${utils_1.MARKDOWN_EOL}<em>${dataClose}</em>${utils_1.MARKDOWN_EOL}</details>${utils_1.MARKDOWN_EOP}`;
70
+ };
71
+ exports.formatMDXDetails = formatMDXDetails;
72
+ /**
73
+ * Formats page title as a visible H1 heading.
74
+ * @param _props - Front matter options (unused)
75
+ * @param formatted - Pre-formatted front matter lines
76
+ * @returns Visible heading string, or empty string if no title is available
77
+ */
78
+ const formatMDXFrontmatter = (_props, formatted) => {
79
+ const title = (0, helpers_1.extractFrontmatterTitle)(formatted);
80
+ return title ? `# ${title}` : "";
81
+ };
82
+ exports.formatMDXFrontmatter = formatMDXFrontmatter;
83
+ /**
84
+ * Formats a named entity as a backtick code span.
85
+ * @param name - Entity name
86
+ * @param parentType - Optional parent type name for qualified references
87
+ * @returns Formatted entity reference string
88
+ */
89
+ const formatMDXNameEntity = (name, parentType) => {
90
+ const parentName = parentType ? `${parentType}.` : "";
91
+ return `\`${parentName}${name}\``;
92
+ };
93
+ exports.formatMDXNameEntity = formatMDXNameEntity;
94
+ /**
95
+ * Formats a "specified by" link as a standard Markdown link.
96
+ * @param url - URL to the specification
97
+ * @returns Formatted specification link string
98
+ */
99
+ const formatMDXSpecifiedByLink = (url) => {
100
+ return `[Specification ⎘](${url})`;
101
+ };
102
+ exports.formatMDXSpecifiedByLink = formatMDXSpecifiedByLink;
103
+ /** File extension used for generated pages — MkDocs uses standard Markdown (.md) files. */
104
+ exports.mdxExtension = ".md";
105
+ /**
106
+ * Lifecycle hook that rewrites generated absolute GraphQL-Markdown links
107
+ * into page-relative `.md` links compatible with MkDocs validation.
108
+ * @param event - Hook payload containing the current file path and renderer output context
109
+ */
110
+ const afterRenderTypeEntitiesHook = async (event) => {
111
+ const { baseURL, filePath, outputDir } = event.data;
112
+ const content = await (0, utils_1.readFile)(filePath, "utf-8");
113
+ const rewrittenContent = rewriteInternalLinks(content, filePath, outputDir, baseURL);
114
+ if (rewrittenContent !== content) {
115
+ await (0, utils_1.saveFile)(filePath, rewrittenContent);
116
+ }
117
+ };
118
+ exports.afterRenderTypeEntitiesHook = afterRenderTypeEntitiesHook;
119
+ var defaults_2 = require("../defaults");
120
+ Object.defineProperty(exports, "formatMDXBullet", { enumerable: true, get: function () { return defaults_2.formatMDXBullet; } });
121
+ /**
122
+ * Creates an MkDocs Material formatter.
123
+ * @param _meta - Unused metadata parameter
124
+ * @returns A complete {@link Formatter} implementation for MkDocs Material output
125
+ */
126
+ const createMDXFormatter = (_meta) => {
127
+ return {
128
+ formatMDXBadge: exports.formatMDXBadge,
129
+ formatMDXAdmonition: exports.formatMDXAdmonition,
130
+ formatMDXBullet: defaults_1.formatMDXBullet,
131
+ formatMDXDetails: exports.formatMDXDetails,
132
+ formatMDXFrontmatter: exports.formatMDXFrontmatter,
133
+ formatMDXLink: defaults_1.formatMDXLink,
134
+ formatMDXNameEntity: exports.formatMDXNameEntity,
135
+ formatMDXSpecifiedByLink: exports.formatMDXSpecifiedByLink,
136
+ };
137
+ };
138
+ exports.createMDXFormatter = createMDXFormatter;
@@ -0,0 +1,19 @@
1
+ /**
2
+ * MkDocs Material formatter for GraphQL documentation output.
3
+ *
4
+ * Produces Markdown compatible with MkDocs Material theme admonitions,
5
+ * collapsible blocks, and standard YAML front matter.
6
+ *
7
+ * @packageDocumentation
8
+ */
9
+ import type { AdmonitionType, Badge, CollapsibleOption, Formatter, FrontMatterOptions, Maybe, MDXString, MetaInfo, TypeLink } from "@graphql-markdown/types";
10
+ export declare const formatMDXBadge: ({ text }: Badge) => MDXString;
11
+ export declare const formatMDXAdmonition: ({ text, title, type }: AdmonitionType, _meta: Maybe<MetaInfo>) => MDXString;
12
+ export declare const formatMDXBullet: (text?: string) => MDXString;
13
+ export declare const formatMDXDetails: ({ dataOpen, dataClose, }: CollapsibleOption) => MDXString;
14
+ export declare const formatMDXFrontmatter: (_props: Maybe<FrontMatterOptions>, formatted: Maybe<string[]>) => MDXString;
15
+ export declare const formatMDXLink: (link: TypeLink) => TypeLink;
16
+ export declare const formatMDXNameEntity: (name: string, parentType?: Maybe<string>) => MDXString;
17
+ export declare const formatMDXSpecifiedByLink: (url: string) => MDXString;
18
+ export declare const createMDXFormatter: (_meta?: Maybe<MetaInfo>) => Formatter;
19
+ //# sourceMappingURL=mkdocs.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"mkdocs.d.ts","sourceRoot":"","sources":["../src/mkdocs.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;AA0BjC,eAAO,MAAM,cAAc,aAAc,KAAK,KAAG,SACyB,CAAC;AAE3E,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAIF,CAAC;AAEF,eAAO,MAAM,eAAe,qBAAgB,SACR,CAAC;AAErC,eAAO,MAAM,gBAAgB,6BAG1B,iBAAiB,KAAG,SACkI,CAAC;AAE1J,eAAO,MAAM,oBAAoB,WACvB,KAAK,CAAC,kBAAkB,CAAC,aACtB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAKoB,CAAC;AAExB,eAAO,MAAM,aAAa,SAAU,QAAQ,KAAG,QAAgB,CAAC;AAEhE,eAAO,MAAM,mBAAmB,SACxB,MAAM,eACC,KAAK,CAAC,MAAM,CAAC,KACzB,SAGF,CAAC;AAEF,eAAO,MAAM,wBAAwB,QAAS,MAAM,KAAG,SACb,CAAC;AAE3C,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAS3D,CAAC"}
package/dist/mkdocs.js ADDED
@@ -0,0 +1,65 @@
1
+ "use strict";
2
+ /**
3
+ * MkDocs Material formatter for GraphQL documentation output.
4
+ *
5
+ * Produces Markdown compatible with MkDocs Material theme admonitions,
6
+ * collapsible blocks, and standard YAML front matter.
7
+ *
8
+ * @packageDocumentation
9
+ */
10
+ Object.defineProperty(exports, "__esModule", { value: true });
11
+ exports.createMDXFormatter = exports.formatMDXSpecifiedByLink = exports.formatMDXNameEntity = exports.formatMDXLink = exports.formatMDXFrontmatter = exports.formatMDXDetails = exports.formatMDXBullet = exports.formatMDXAdmonition = exports.formatMDXBadge = void 0;
12
+ const utils_1 = require("@graphql-markdown/utils");
13
+ const ADMONITION_TYPE_MAP = {
14
+ note: "note",
15
+ tip: "tip",
16
+ info: "info",
17
+ warning: "warning",
18
+ danger: "danger",
19
+ deprecated: "warning",
20
+ caution: "warning",
21
+ success: "success",
22
+ };
23
+ const indentLines = (text, spaces) => {
24
+ const indent = " ".repeat(spaces);
25
+ return text
26
+ .split(utils_1.MARKDOWN_EOL)
27
+ .map((line) => (line.trim() ? `${indent}${line}` : ""))
28
+ .join(utils_1.MARKDOWN_EOL);
29
+ };
30
+ const formatMDXBadge = ({ text }) => `<mark class="gqlmd-mkdocs-badge">${text}</mark>`;
31
+ exports.formatMDXBadge = formatMDXBadge;
32
+ const formatMDXAdmonition = ({ text, title, type }, _meta) => {
33
+ const mkdocsType = ADMONITION_TYPE_MAP[type.toLowerCase()] ?? "note";
34
+ const titleAttr = title ? ` "${title}"` : "";
35
+ return `${utils_1.MARKDOWN_EOP}!!! ${mkdocsType}${titleAttr}${utils_1.MARKDOWN_EOL}${indentLines(text, 4)}${utils_1.MARKDOWN_EOL}`;
36
+ };
37
+ exports.formatMDXAdmonition = formatMDXAdmonition;
38
+ const formatMDXBullet = (text = "") => `&bull;&nbsp;${text}`;
39
+ exports.formatMDXBullet = formatMDXBullet;
40
+ const formatMDXDetails = ({ dataOpen, dataClose, }) => `${utils_1.MARKDOWN_EOP}??? note "${dataOpen}"${utils_1.MARKDOWN_EOL}${utils_1.MARKDOWN_EOL} \r${utils_1.MARKDOWN_EOL}${utils_1.MARKDOWN_EOL} *${dataClose}*${utils_1.MARKDOWN_EOL}`;
41
+ exports.formatMDXDetails = formatMDXDetails;
42
+ const formatMDXFrontmatter = (_props, formatted) => formatted
43
+ ? [utils_1.FRONT_MATTER_DELIMITER, ...formatted, utils_1.FRONT_MATTER_DELIMITER].join(utils_1.MARKDOWN_EOL)
44
+ : "";
45
+ exports.formatMDXFrontmatter = formatMDXFrontmatter;
46
+ const formatMDXLink = (link) => link;
47
+ exports.formatMDXLink = formatMDXLink;
48
+ const formatMDXNameEntity = (name, parentType) => {
49
+ const parentName = parentType ? `${parentType}.` : "";
50
+ return `\`${parentName}${name}\``;
51
+ };
52
+ exports.formatMDXNameEntity = formatMDXNameEntity;
53
+ const formatMDXSpecifiedByLink = (url) => `[Specification ⎘](${url})`;
54
+ exports.formatMDXSpecifiedByLink = formatMDXSpecifiedByLink;
55
+ const createMDXFormatter = (_meta) => ({
56
+ formatMDXBadge: exports.formatMDXBadge,
57
+ formatMDXAdmonition: exports.formatMDXAdmonition,
58
+ formatMDXBullet: exports.formatMDXBullet,
59
+ formatMDXDetails: exports.formatMDXDetails,
60
+ formatMDXFrontmatter: exports.formatMDXFrontmatter,
61
+ formatMDXLink: exports.formatMDXLink,
62
+ formatMDXNameEntity: exports.formatMDXNameEntity,
63
+ formatMDXSpecifiedByLink: exports.formatMDXSpecifiedByLink,
64
+ });
65
+ exports.createMDXFormatter = createMDXFormatter;
@@ -0,0 +1,65 @@
1
+ /**
2
+ * Astro Starlight formatter for GraphQL documentation output.
3
+ *
4
+ * Produces MDX compatible with Astro Starlight using its native
5
+ * Aside and Badge components. Includes lifecycle hooks for generating
6
+ * index files for each category directory.
7
+ *
8
+ * @packageDocumentation
9
+ */
10
+ import type { AdmonitionType, Badge, Formatter, Maybe, MDXString, MetaInfo, TypeLink } from "@graphql-markdown/types";
11
+ /** File extension used for generated pages. */
12
+ export declare const mdxExtension: ".mdx";
13
+ /** MDX import statement prepended to every generated file to register Starlight components. */
14
+ export declare const mdxDeclaration: MDXString;
15
+ /**
16
+ * Formats a badge using the Starlight `<Badge>` component.
17
+ * Maps `DEPRECATED` classname to the `caution` variant; all others use `default`.
18
+ * @param badge - Badge data containing text and optional classname
19
+ * @returns Formatted Starlight Badge component string
20
+ */
21
+ export declare const formatMDXBadge: ({ text, classname }: Badge) => MDXString;
22
+ /**
23
+ * Formats an admonition using the Starlight `<Aside>` component.
24
+ * Maps `warning` type to `caution`; all other types use `note`.
25
+ * @param admonition - Admonition data with text, title, and type
26
+ * @param _meta - Unused metadata parameter
27
+ * @returns Formatted Starlight Aside component string
28
+ */
29
+ export declare const formatMDXAdmonition: ({ text, title, type }: AdmonitionType, _meta: Maybe<MetaInfo>) => MDXString;
30
+ /**
31
+ * Appends `.mdx` to internal link URLs.
32
+ * @param link - Link data with URL and text
33
+ * @returns Link with `.mdx` extension appended to the URL
34
+ */
35
+ export declare const formatMDXLink: ({ text, url }: TypeLink) => TypeLink;
36
+ export { formatMDXBullet, formatMDXDetails, formatMDXFrontmatter, formatMDXNameEntity, formatMDXSpecifiedByLink, } from "../defaults";
37
+ /**
38
+ * Lifecycle hook that creates an `index.md` file for a category directory
39
+ * before Starlight indexes it. Skips creation if the file already exists.
40
+ * @param event - Hook payload containing the target directory and category name
41
+ */
42
+ export declare const beforeGenerateIndexMetafileHook: (event: {
43
+ data: {
44
+ dirPath: string;
45
+ category: string;
46
+ };
47
+ }) => Promise<void>;
48
+ /**
49
+ * Lifecycle hook that appends a link entry to the category `index.md`
50
+ * after each type entity page is rendered.
51
+ * @param event - Hook payload containing the entity name and its output file path
52
+ */
53
+ export declare const afterRenderTypeEntitiesHook: (event: {
54
+ data: {
55
+ name: string;
56
+ filePath: string;
57
+ };
58
+ }) => Promise<void>;
59
+ /**
60
+ * Creates an Astro Starlight formatter.
61
+ * @param _meta - Unused metadata parameter
62
+ * @returns A complete {@link Formatter} implementation for Starlight MDX output
63
+ */
64
+ export declare const createMDXFormatter: (_meta?: Maybe<MetaInfo>) => Formatter;
65
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/starlight/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,SAAS,EACT,KAAK,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAiBjC,+CAA+C;AAC/C,eAAO,MAAM,YAAY,EAAG,MAAe,CAAC;AAE5C,+FAA+F;AAC/F,eAAO,MAAM,cAAc,EAAE,SAEf,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,aAAa,kBAAmB,QAAQ,KAAG,QAKvD,CAAC;AAEF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAIrB;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,UAAiB;IAC3D,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C,KAAG,OAAO,CAAC,IAAI,CAWf,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,UAAiB;IACvD,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1C,KAAG,OAAO,CAAC,IAAI,CAQf,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAW5D,CAAC"}