@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,135 @@
1
+ "use strict";
2
+ /**
3
+ * HonKit formatter for GraphQL documentation output.
4
+ *
5
+ * Produces plain Markdown compatible with HonKit static site generator.
6
+ * Internal links are converted to .html paths.
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.formatMDXAdmonition = exports.formatMDXBadge = exports.mdxExtension = 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 = { formatMDXBullet: defaults_1.formatMDXBullet };
16
+ /** File extension used for generated pages — HonKit renders plain Markdown to HTML. */
17
+ exports.mdxExtension = ".md";
18
+ /** Shared default badge theme used across this preset. */
19
+ const DEFAULT_BADGE_THEME = {
20
+ bg: "#f6f7f9",
21
+ border: "#d1d5db",
22
+ color: "#374151",
23
+ };
24
+ /**
25
+ * Formats a badge as an inline HTML `<span>` with a shared default style.
26
+ * Users can customize badge colors by providing their own `formatMDXBadge` implementation.
27
+ * @param badge - Badge data containing text
28
+ * @returns Formatted inline HTML span string
29
+ */
30
+ const formatMDXBadge = ({ text }) => {
31
+ const label = (typeof text === "string" ? String(text) : String(text.singular)).trim();
32
+ return `<span style="display:inline-block;padding:0.12rem 0.5rem;margin-right:0.35rem;border:1px solid ${DEFAULT_BADGE_THEME.border};border-radius:999px;background:${DEFAULT_BADGE_THEME.bg};color:${DEFAULT_BADGE_THEME.color};font-size:1.15rem;font-weight:600;line-height:1.2;vertical-align:middle;">${label}</span>`;
33
+ };
34
+ exports.formatMDXBadge = formatMDXBadge;
35
+ /**
36
+ * Formats an admonition as a Markdown blockquote with a bold prefix label.
37
+ * Maps `warning` type to `WARNING`; all other types use `INFO`.
38
+ * @param admonition - Admonition data with text, title, and type
39
+ * @param _meta - Unused metadata parameter
40
+ * @returns Formatted blockquote string
41
+ */
42
+ const formatMDXAdmonition = ({ text, title, type }, _meta) => {
43
+ const prefix = type === "warning" ? "WARNING" : "INFO";
44
+ return `> **${prefix} - ${title}**\n>\n> ${text}`;
45
+ };
46
+ exports.formatMDXAdmonition = formatMDXAdmonition;
47
+ /**
48
+ * Formats a collapsible block as an HTML `<details>` element.
49
+ * @param option - Configuration for open/close label text
50
+ * @returns Formatted details element string
51
+ */
52
+ const formatMDXDetails = ({ dataOpen, dataClose, }) => {
53
+ return `${utils_1.MARKDOWN_EOL}<details>${utils_1.MARKDOWN_EOL}<summary>${dataOpen}</summary>${utils_1.MARKDOWN_EOL}\r${dataClose}${utils_1.MARKDOWN_EOL}</details>${utils_1.MARKDOWN_EOL}`;
54
+ };
55
+ exports.formatMDXDetails = formatMDXDetails;
56
+ /**
57
+ * Formats YAML front matter and appends an H1 heading derived from the `title` prop.
58
+ * Merges `props` entries with `formatted` lines (formatted lines take precedence).
59
+ * Returns empty string if `props` is empty or absent — HonKit renders front matter
60
+ * without a title as literal YAML content.
61
+ * @param props - Front matter options; `title` is used to generate the H1 heading
62
+ * @param formatted - Pre-formatted front matter lines that override props values
63
+ * @returns Formatted front matter block with optional H1, or empty string
64
+ */
65
+ const formatMDXFrontmatter = (props, formatted) => {
66
+ if (!props || typeof props !== "object" || Object.keys(props).length === 0) {
67
+ return "";
68
+ }
69
+ const lines = (0, helpers_1.mergeFrontmatterLines)(props, formatted ?? null);
70
+ const frontmatter = (0, helpers_1.formatMarkdownFrontmatter)(lines, utils_1.FRONT_MATTER_DELIMITER, utils_1.MARKDOWN_EOL);
71
+ const title = (0, helpers_1.extractFrontmatterTitle)(lines).replaceAll(/\r?\n/g, " ").trim();
72
+ const heading = title ? `\n\n# ${title}` : "";
73
+ return `${frontmatter}${heading}`;
74
+ };
75
+ exports.formatMDXFrontmatter = formatMDXFrontmatter;
76
+ /**
77
+ * Converts internal link URLs to `.html` paths for HonKit static output.
78
+ * Absolute paths without an `.html` extension are suffixed with `.html`.
79
+ * External URLs and fragment-only links are returned unchanged.
80
+ * @param link - Link data with URL and text
81
+ * @returns Link with `.html` extension applied to absolute internal paths
82
+ */
83
+ const formatMDXLink = ({ text, url }) => {
84
+ if (!url || /^(https?:|mailto:|tel:)/i.test(url) || url.startsWith("#"))
85
+ return { text, url };
86
+ const href = String(url).trim();
87
+ const match = /^([^?#]*)([?#].*)?$/.exec(href);
88
+ const pathname = match?.[1] ?? href;
89
+ const suffix = match?.[2] ?? "";
90
+ if (pathname === "/") {
91
+ return { text, url: href };
92
+ }
93
+ const updatedPath = (0, helpers_1.appendExtensionToAbsolutePathWithoutExtension)(pathname, ".html");
94
+ return { text, url: `${updatedPath}${suffix}` };
95
+ };
96
+ exports.formatMDXLink = formatMDXLink;
97
+ /**
98
+ * Formats a named entity as plain text (no markup).
99
+ * HonKit renders plain Markdown — no JSX or code spans needed.
100
+ * @param name - Entity name
101
+ * @param parentType - Optional parent type name for qualified references
102
+ * @returns Formatted entity reference string
103
+ */
104
+ const formatMDXNameEntity = (name, parentType) => {
105
+ return (parentType ? `${parentType}.${name}` : name);
106
+ };
107
+ exports.formatMDXNameEntity = formatMDXNameEntity;
108
+ /**
109
+ * Formats a "specified by" link as plain text with the raw URL.
110
+ * HonKit does not render custom JSX components.
111
+ * @param url - URL to the specification
112
+ * @returns Formatted specification text string
113
+ */
114
+ const formatMDXSpecifiedByLink = (url) => {
115
+ return `\n\nSpecified by: ${url}`;
116
+ };
117
+ exports.formatMDXSpecifiedByLink = formatMDXSpecifiedByLink;
118
+ /**
119
+ * Creates a HonKit formatter.
120
+ * @param _meta - Unused metadata parameter
121
+ * @returns A complete {@link Formatter} implementation for HonKit output
122
+ */
123
+ const createMDXFormatter = (_meta) => {
124
+ return {
125
+ formatMDXBadge: exports.formatMDXBadge,
126
+ formatMDXAdmonition: exports.formatMDXAdmonition,
127
+ formatMDXBullet: defaults_1.formatMDXBullet,
128
+ formatMDXDetails: exports.formatMDXDetails,
129
+ formatMDXFrontmatter: exports.formatMDXFrontmatter,
130
+ formatMDXLink: exports.formatMDXLink,
131
+ formatMDXNameEntity: exports.formatMDXNameEntity,
132
+ formatMDXSpecifiedByLink: exports.formatMDXSpecifiedByLink,
133
+ };
134
+ };
135
+ exports.createMDXFormatter = createMDXFormatter;
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Hugo formatter for GraphQL documentation output.
3
+ *
4
+ * Produces Markdown compatible with Hugo static site generator.
5
+ * Uses GitHub-style alerts (Hugo 0.132+) for admonitions and
6
+ * strips file extensions from internal links to match Hugo's URL routing.
7
+ *
8
+ * @packageDocumentation
9
+ */
10
+ import type { AdmonitionType, Badge, CollapsibleOption, Formatter, FrontMatterOptions, GenerateIndexMetafileHook, Maybe, MDXString, MetaInfo, TypeLink } from "@graphql-markdown/types";
11
+ /**
12
+ * Formats a badge as a styled span element.
13
+ * @param badge - Badge data containing the display text
14
+ * @returns HTML `<span>` string with the `gqlmd-badge` class
15
+ */
16
+ export declare const formatMDXBadge: ({ text }: Badge) => MDXString;
17
+ /**
18
+ * Formats an admonition using Hugo GitHub-style alert syntax (`> [!TYPE]`).
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}
23
+ * @param _meta - Unused metadata parameter
24
+ * @returns Formatted blockquote alert string
25
+ */
26
+ export declare const formatMDXAdmonition: ({ text, title, type }: AdmonitionType, _meta: Maybe<MetaInfo>) => MDXString;
27
+ /**
28
+ * 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
31
+ * @returns HTML `<details>`/`<summary>` block string
32
+ */
33
+ export declare const formatMDXDetails: ({ dataOpen, dataClose, }: CollapsibleOption) => MDXString;
34
+ /**
35
+ * Formats YAML front matter wrapped in `---` delimiters, with page title rendered as H1 heading.
36
+ * Falls back to serializing `props` via {@link formatFrontMatterObject} when `formatted` is not provided.
37
+ * The title is extracted from the frontmatter lines and also rendered as a visible `# Title` heading,
38
+ * since Hugo does not automatically display the frontmatter `title` field as page content.
39
+ * @param props - Front matter options used as fallback when `formatted` is not provided
40
+ * @param formatted - Pre-formatted front matter lines produced by the printer
41
+ * @returns Formatted front matter block with H1 title heading, or empty string if no data
42
+ */
43
+ export declare const formatMDXFrontmatter: (props: Maybe<FrontMatterOptions>, formatted: Maybe<string[]>) => MDXString;
44
+ /**
45
+ * Strips the `.md` extension from internal links.
46
+ * 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
49
+ * @returns Link object with the cleaned URL
50
+ */
51
+ export declare const formatMDXLink: ({ text, url }: TypeLink) => TypeLink;
52
+ export { formatMDXBullet, formatMDXNameEntity, formatMDXSpecifiedByLink, } from "../defaults";
53
+ /**
54
+ * Creates a Hugo formatter.
55
+ * @param _meta - Unused metadata parameter
56
+ * @returns A complete {@link Formatter} implementation for Hugo output
57
+ */
58
+ export declare const createMDXFormatter: (_meta?: Maybe<MetaInfo>) => Formatter;
59
+ /** File extension used for generated pages — Hugo uses standard Markdown (.md) files. */
60
+ export declare const mdxExtension: ".md";
61
+ /**
62
+ * Lifecycle hook that generates a Hugo-compatible `_index.md` section index file.
63
+ * The file is (re)created on every run with YAML frontmatter:
64
+ * - `title`: the start-cased category name
65
+ * - `type: docs`: required by the Hugo Book theme for sidebar rendering
66
+ * - `bookCollapseSection: true`: collapses the section in the Hugo Book theme sidebar by default
67
+ * @param event - Hook event whose `data` contains `dirPath` (target directory) and `category` (section name)
68
+ */
69
+ export declare const beforeGenerateIndexMetafileHook: GenerateIndexMetafileHook;
70
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hugo/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,yBAAyB,EACzB,KAAK,EACL,SAAS,EACT,QAAQ,EACR,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAmCjC;;;;GAIG;AACH,eAAO,MAAM,cAAc,aAAc,KAAK,KAAG,SAEhD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAIF,CAAC;AAEF;;;;;GAKG;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,QAKvD,CAAC;AAEF,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAW5D,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,YAAY,EAAG,KAAc,CAAC;AAE3C;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,EAAE,yBAW3C,CAAC"}
@@ -0,0 +1,143 @@
1
+ "use strict";
2
+ /**
3
+ * Hugo formatter for GraphQL documentation output.
4
+ *
5
+ * Produces Markdown compatible with Hugo static site generator.
6
+ * Uses GitHub-style alerts (Hugo 0.132+) for admonitions and
7
+ * strips file extensions from internal links to match Hugo's URL routing.
8
+ *
9
+ * @packageDocumentation
10
+ */
11
+ Object.defineProperty(exports, "__esModule", { value: true });
12
+ exports.beforeGenerateIndexMetafileHook = exports.mdxExtension = exports.createMDXFormatter = exports.formatMDXSpecifiedByLink = exports.formatMDXNameEntity = exports.formatMDXBullet = exports.formatMDXLink = exports.formatMDXFrontmatter = exports.formatMDXDetails = exports.formatMDXAdmonition = exports.formatMDXBadge = void 0;
13
+ const node_path_1 = require("node:path");
14
+ const helpers_1 = require("@graphql-markdown/helpers");
15
+ const utils_1 = require("@graphql-markdown/utils");
16
+ const defaults_1 = require("../defaults");
17
+ /**
18
+ * Maps graphql-markdown admonition types to Hugo GitHub-style alert types (Hugo 0.132+).
19
+ * @see https://gohugo.io/render-hooks/blockquotes/#alerts
20
+ */
21
+ const ALERT_TYPE_MAP = {
22
+ note: "NOTE",
23
+ tip: "TIP",
24
+ info: "IMPORTANT",
25
+ warning: "WARNING",
26
+ danger: "CAUTION",
27
+ deprecated: "WARNING",
28
+ caution: "CAUTION",
29
+ success: "NOTE",
30
+ };
31
+ /**
32
+ * Formats a badge as a styled span element.
33
+ * @param badge - Badge data containing the display text
34
+ * @returns HTML `<span>` string with the `gqlmd-badge` class
35
+ */
36
+ const formatMDXBadge = ({ text }) => {
37
+ return `<span class="gqlmd-badge">${text}</span>`;
38
+ };
39
+ exports.formatMDXBadge = formatMDXBadge;
40
+ /**
41
+ * Formats an admonition using Hugo GitHub-style alert syntax (`> [!TYPE]`).
42
+ * Requires Hugo 0.132 or later.
43
+ * @param text - The admonition body text
44
+ * @param title - Optional title rendered as bold text after the alert type line
45
+ * @param type - Admonition type (e.g. `note`, `warning`, `danger`) mapped via {@link ALERT_TYPE_MAP}
46
+ * @param _meta - Unused metadata parameter
47
+ * @returns Formatted blockquote alert string
48
+ */
49
+ const formatMDXAdmonition = ({ text, title, type }, _meta) => {
50
+ const alertType = ALERT_TYPE_MAP[type.toLowerCase()] ?? "NOTE";
51
+ const titleLine = title ? `${utils_1.MARKDOWN_EOL}> **${title}**` : "";
52
+ return `${utils_1.MARKDOWN_EOP}> [!${alertType}]${titleLine}${utils_1.MARKDOWN_EOL}${(0, helpers_1.quoteMarkdownLines)(text, utils_1.MARKDOWN_EOL)}${utils_1.MARKDOWN_EOL}`;
53
+ };
54
+ exports.formatMDXAdmonition = formatMDXAdmonition;
55
+ /**
56
+ * Formats a collapsible block as an HTML `<details>` element.
57
+ * @param dataOpen - Label shown when the section is collapsed (used as `<summary>` text)
58
+ * @param dataClose - Label shown inside the expanded section
59
+ * @returns HTML `<details>`/`<summary>` block string
60
+ */
61
+ const formatMDXDetails = ({ dataOpen, dataClose, }) => {
62
+ 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}<p><em>${dataClose}</em></p>${utils_1.MARKDOWN_EOL}</details>${utils_1.MARKDOWN_EOP}`;
63
+ };
64
+ exports.formatMDXDetails = formatMDXDetails;
65
+ /**
66
+ * Formats YAML front matter wrapped in `---` delimiters, with page title rendered as H1 heading.
67
+ * Falls back to serializing `props` via {@link formatFrontMatterObject} when `formatted` is not provided.
68
+ * The title is extracted from the frontmatter lines and also rendered as a visible `# Title` heading,
69
+ * since Hugo does not automatically display the frontmatter `title` field as page content.
70
+ * @param props - Front matter options used as fallback when `formatted` is not provided
71
+ * @param formatted - Pre-formatted front matter lines produced by the printer
72
+ * @returns Formatted front matter block with H1 title heading, or empty string if no data
73
+ */
74
+ const formatMDXFrontmatter = (props, formatted) => {
75
+ const lines = formatted ?? (props ? (0, utils_1.formatFrontMatterObject)(props) : []);
76
+ if (lines.length === 0) {
77
+ return "";
78
+ }
79
+ const title = (0, helpers_1.extractFrontmatterTitle)(lines);
80
+ const frontmatter = [
81
+ utils_1.FRONT_MATTER_DELIMITER,
82
+ ...lines,
83
+ utils_1.FRONT_MATTER_DELIMITER,
84
+ ].join(utils_1.MARKDOWN_EOL);
85
+ const heading = title ? `${utils_1.MARKDOWN_EOL}${utils_1.MARKDOWN_EOL}# ${title}` : "";
86
+ return `${frontmatter}${heading}`;
87
+ };
88
+ exports.formatMDXFrontmatter = formatMDXFrontmatter;
89
+ /**
90
+ * Strips the `.md` extension from internal links.
91
+ * Hugo serves pages at extensionless URLs — links with `.md` would 404 in the built site.
92
+ * @param text - Display text for the link
93
+ * @param url - Link target URL, with `.md` extension removed if present
94
+ * @returns Link object with the cleaned URL
95
+ */
96
+ const formatMDXLink = ({ text, url }) => {
97
+ return {
98
+ text,
99
+ url: url.replace(/\.md$/, ""),
100
+ };
101
+ };
102
+ exports.formatMDXLink = formatMDXLink;
103
+ var defaults_2 = require("../defaults");
104
+ Object.defineProperty(exports, "formatMDXBullet", { enumerable: true, get: function () { return defaults_2.formatMDXBullet; } });
105
+ Object.defineProperty(exports, "formatMDXNameEntity", { enumerable: true, get: function () { return defaults_2.formatMDXNameEntity; } });
106
+ Object.defineProperty(exports, "formatMDXSpecifiedByLink", { enumerable: true, get: function () { return defaults_2.formatMDXSpecifiedByLink; } });
107
+ /**
108
+ * Creates a Hugo formatter.
109
+ * @param _meta - Unused metadata parameter
110
+ * @returns A complete {@link Formatter} implementation for Hugo output
111
+ */
112
+ const createMDXFormatter = (_meta) => {
113
+ return {
114
+ formatMDXBadge: exports.formatMDXBadge,
115
+ formatMDXAdmonition: exports.formatMDXAdmonition,
116
+ formatMDXBullet: defaults_1.formatMDXBullet,
117
+ formatMDXDetails: exports.formatMDXDetails,
118
+ formatMDXFrontmatter: exports.formatMDXFrontmatter,
119
+ formatMDXLink: exports.formatMDXLink,
120
+ formatMDXNameEntity: defaults_1.formatMDXNameEntity,
121
+ formatMDXSpecifiedByLink: defaults_1.formatMDXSpecifiedByLink,
122
+ };
123
+ };
124
+ exports.createMDXFormatter = createMDXFormatter;
125
+ /** File extension used for generated pages — Hugo uses standard Markdown (.md) files. */
126
+ exports.mdxExtension = ".md";
127
+ /**
128
+ * Lifecycle hook that generates a Hugo-compatible `_index.md` section index file.
129
+ * The file is (re)created on every run with YAML frontmatter:
130
+ * - `title`: the start-cased category name
131
+ * - `type: docs`: required by the Hugo Book theme for sidebar rendering
132
+ * - `bookCollapseSection: true`: collapses the section in the Hugo Book theme sidebar by default
133
+ * @param event - Hook event whose `data` contains `dirPath` (target directory) and `category` (section name)
134
+ */
135
+ const beforeGenerateIndexMetafileHook = async (event) => {
136
+ const { dirPath, category } = event.data;
137
+ const filePath = (0, node_path_1.join)(dirPath, "_index.md");
138
+ const label = (0, utils_1.startCase)(category);
139
+ const content = `${utils_1.FRONT_MATTER_DELIMITER}${utils_1.MARKDOWN_EOL}title: "${label}"${utils_1.MARKDOWN_EOL}type: docs${utils_1.MARKDOWN_EOL}bookCollapseSection: true${utils_1.MARKDOWN_EOL}${utils_1.FRONT_MATTER_DELIMITER}${utils_1.MARKDOWN_EOL}${utils_1.MARKDOWN_EOL}# ${label}${utils_1.MARKDOWN_EOL}${utils_1.MARKDOWN_EOL}`;
140
+ await (0, utils_1.ensureDir)(dirPath);
141
+ await (0, utils_1.saveFile)(filePath, content);
142
+ };
143
+ exports.beforeGenerateIndexMetafileHook = beforeGenerateIndexMetafileHook;
package/dist/hugo.d.ts ADDED
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Hugo formatter for GraphQL documentation output.
3
+ *
4
+ * Produces Markdown compatible with Hugo static site generator.
5
+ * Uses GitHub-style alerts (Hugo 0.132+) for admonitions and
6
+ * strips file extensions from internal links to match Hugo's URL routing.
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: ({ text, url }: 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=hugo.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hugo.d.ts","sourceRoot":"","sources":["../src/hugo.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;AAyBjC,eAAO,MAAM,cAAc,aAAc,KAAK,KAAG,SACuB,CAAC;AAEzE,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,SACiM,CAAC;AAEzN,eAAO,MAAM,oBAAoB,WACvB,KAAK,CAAC,kBAAkB,CAAC,aACtB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAKoB,CAAC;AAGxB,eAAO,MAAM,aAAa,kBAAmB,QAAQ,KAAG,QAGtD,CAAC;AAEH,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/hugo.js ADDED
@@ -0,0 +1,68 @@
1
+ "use strict";
2
+ /**
3
+ * Hugo formatter for GraphQL documentation output.
4
+ *
5
+ * Produces Markdown compatible with Hugo static site generator.
6
+ * Uses GitHub-style alerts (Hugo 0.132+) for admonitions and
7
+ * strips file extensions from internal links to match Hugo's URL routing.
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
+ // Maps graphql-markdown admonition types to Hugo GitHub-style alert types (Hugo 0.132+)
15
+ const ALERT_TYPE_MAP = {
16
+ note: "NOTE",
17
+ tip: "TIP",
18
+ info: "IMPORTANT",
19
+ warning: "WARNING",
20
+ danger: "CAUTION",
21
+ deprecated: "WARNING",
22
+ caution: "CAUTION",
23
+ success: "NOTE",
24
+ };
25
+ const quoteLines = (text) => text
26
+ .split(utils_1.MARKDOWN_EOL)
27
+ .map((line) => `> ${line}`)
28
+ .join(utils_1.MARKDOWN_EOL);
29
+ const formatMDXBadge = ({ text }) => `<mark class="gqlmd-hugo-badge">${text}</mark>`;
30
+ exports.formatMDXBadge = formatMDXBadge;
31
+ const formatMDXAdmonition = ({ text, title, type }, _meta) => {
32
+ const alertType = ALERT_TYPE_MAP[type.toLowerCase()] ?? "NOTE";
33
+ const titleLine = title ? `${utils_1.MARKDOWN_EOL}> **${title}**` : "";
34
+ return `${utils_1.MARKDOWN_EOP}> [!${alertType}]${titleLine}${utils_1.MARKDOWN_EOL}${quoteLines(text)}${utils_1.MARKDOWN_EOL}`;
35
+ };
36
+ exports.formatMDXAdmonition = formatMDXAdmonition;
37
+ const formatMDXBullet = (text = "") => `&bull;&nbsp;${text}`;
38
+ exports.formatMDXBullet = formatMDXBullet;
39
+ 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}<p><em>${dataClose}</em></p>${utils_1.MARKDOWN_EOL}</details>${utils_1.MARKDOWN_EOP}`;
40
+ exports.formatMDXDetails = formatMDXDetails;
41
+ const formatMDXFrontmatter = (_props, formatted) => formatted
42
+ ? [utils_1.FRONT_MATTER_DELIMITER, ...formatted, utils_1.FRONT_MATTER_DELIMITER].join(utils_1.MARKDOWN_EOL)
43
+ : "";
44
+ exports.formatMDXFrontmatter = formatMDXFrontmatter;
45
+ // Hugo resolves pages by directory, not by .md extension — strip it from internal links
46
+ const formatMDXLink = ({ text, url }) => ({
47
+ text,
48
+ url: url.replace(/\.md$/, ""),
49
+ });
50
+ exports.formatMDXLink = formatMDXLink;
51
+ const formatMDXNameEntity = (name, parentType) => {
52
+ const parentName = parentType ? `${parentType}.` : "";
53
+ return `\`${parentName}${name}\``;
54
+ };
55
+ exports.formatMDXNameEntity = formatMDXNameEntity;
56
+ const formatMDXSpecifiedByLink = (url) => `[Specification ⎘](${url})`;
57
+ exports.formatMDXSpecifiedByLink = formatMDXSpecifiedByLink;
58
+ const createMDXFormatter = (_meta) => ({
59
+ formatMDXBadge: exports.formatMDXBadge,
60
+ formatMDXAdmonition: exports.formatMDXAdmonition,
61
+ formatMDXBullet: exports.formatMDXBullet,
62
+ formatMDXDetails: exports.formatMDXDetails,
63
+ formatMDXFrontmatter: exports.formatMDXFrontmatter,
64
+ formatMDXLink: exports.formatMDXLink,
65
+ formatMDXNameEntity: exports.formatMDXNameEntity,
66
+ formatMDXSpecifiedByLink: exports.formatMDXSpecifiedByLink,
67
+ });
68
+ exports.createMDXFormatter = createMDXFormatter;
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Formatter presets for documentation frameworks.
3
+ *
4
+ * Each preset implements the {@link Formatter} interface and can be used
5
+ * as the `mdxParser` config value in graphql-markdown.
6
+ *
7
+ * @example
8
+ * ```yaml
9
+ * # .graphqlrc.yml
10
+ * extensions:
11
+ * graphql-markdown:
12
+ * mdxParser: "@graphql-markdown/formatters/mkdocs"
13
+ * ```
14
+ *
15
+ * @packageDocumentation
16
+ */
17
+ export * as docusaurus from "./docusaurus/index";
18
+ export * as docfx from "./docfx/index";
19
+ export * as fumadocs from "./fumadocs/index";
20
+ export * as honkit from "./honkit/index";
21
+ export * as hugo from "./hugo/index";
22
+ export * as mdbook from "./mdbook/index";
23
+ export * as mkdocs from "./mkdocs/index";
24
+ export * as starlight from "./starlight/index";
25
+ export * as vocs from "./vocs/index";
26
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,UAAU,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,KAAK,MAAM,eAAe,CAAC;AACvC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,MAAM,MAAM,gBAAgB,CAAC;AACzC,OAAO,KAAK,IAAI,MAAM,cAAc,CAAC;AACrC,OAAO,KAAK,MAAM,MAAM,gBAAgB,CAAC;AACzC,OAAO,KAAK,MAAM,MAAM,gBAAgB,CAAC;AACzC,OAAO,KAAK,SAAS,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,IAAI,MAAM,cAAc,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,61 @@
1
+ "use strict";
2
+ /**
3
+ * Formatter presets for documentation frameworks.
4
+ *
5
+ * Each preset implements the {@link Formatter} interface and can be used
6
+ * as the `mdxParser` config value in graphql-markdown.
7
+ *
8
+ * @example
9
+ * ```yaml
10
+ * # .graphqlrc.yml
11
+ * extensions:
12
+ * graphql-markdown:
13
+ * mdxParser: "@graphql-markdown/formatters/mkdocs"
14
+ * ```
15
+ *
16
+ * @packageDocumentation
17
+ */
18
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
19
+ if (k2 === undefined) k2 = k;
20
+ var desc = Object.getOwnPropertyDescriptor(m, k);
21
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
22
+ desc = { enumerable: true, get: function() { return m[k]; } };
23
+ }
24
+ Object.defineProperty(o, k2, desc);
25
+ }) : (function(o, m, k, k2) {
26
+ if (k2 === undefined) k2 = k;
27
+ o[k2] = m[k];
28
+ }));
29
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
30
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
31
+ }) : function(o, v) {
32
+ o["default"] = v;
33
+ });
34
+ var __importStar = (this && this.__importStar) || (function () {
35
+ var ownKeys = function(o) {
36
+ ownKeys = Object.getOwnPropertyNames || function (o) {
37
+ var ar = [];
38
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
39
+ return ar;
40
+ };
41
+ return ownKeys(o);
42
+ };
43
+ return function (mod) {
44
+ if (mod && mod.__esModule) return mod;
45
+ var result = {};
46
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
47
+ __setModuleDefault(result, mod);
48
+ return result;
49
+ };
50
+ })();
51
+ Object.defineProperty(exports, "__esModule", { value: true });
52
+ exports.vocs = exports.starlight = exports.mkdocs = exports.mdbook = exports.hugo = exports.honkit = exports.fumadocs = exports.docfx = exports.docusaurus = void 0;
53
+ exports.docusaurus = __importStar(require("./docusaurus/index"));
54
+ exports.docfx = __importStar(require("./docfx/index"));
55
+ exports.fumadocs = __importStar(require("./fumadocs/index"));
56
+ exports.honkit = __importStar(require("./honkit/index"));
57
+ exports.hugo = __importStar(require("./hugo/index"));
58
+ exports.mdbook = __importStar(require("./mdbook/index"));
59
+ exports.mkdocs = __importStar(require("./mkdocs/index"));
60
+ exports.starlight = __importStar(require("./starlight/index"));
61
+ exports.vocs = __importStar(require("./vocs/index"));
@@ -0,0 +1,69 @@
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 use mdBook's native `> [!TYPE]` syntax.
7
+ * Exports `afterRenderFilesHook` to build `SUMMARY.md` after all pages are written.
8
+ *
9
+ * @packageDocumentation
10
+ */
11
+ import type { AdmonitionType, Badge, CollapsibleOption, Formatter, FrontMatterOptions, Maybe, MDXString, MetaInfo, RenderFilesHook, TypeLink } from "@graphql-markdown/types";
12
+ /**
13
+ * Formats a badge as Markdown bold text — mdBook has no badge component.
14
+ * @param badge - Badge data containing text
15
+ * @returns Formatted bold text string
16
+ */
17
+ export declare const formatMDXBadge: ({ text }: Badge) => MDXString;
18
+ /**
19
+ * Formats an admonition using mdBook's native admonition syntax (`> [!TYPE]`).
20
+ * Uses `type` for the admonition tag and `title` as an optional override label.
21
+ * @param admonition - Admonition data with text, title, and type
22
+ * @param _meta - Unused metadata parameter
23
+ * @returns Formatted admonition string
24
+ */
25
+ export declare const formatMDXAdmonition: ({ text, title, type }: AdmonitionType, _meta: Maybe<MetaInfo>) => MDXString;
26
+ /**
27
+ * Renders a deprecated section as a bold inline label.
28
+ *
29
+ * A fixed heading level would break hierarchy when this section is nested
30
+ * inside field entries at varying depths. Bold text is CommonMark-safe and
31
+ * works at any nesting level without affecting the heading outline.
32
+ *
33
+ * The output is split on `\r` to produce [openSection, closeSection] as the
34
+ * printer expects — the deprecated items are inserted between the two halves.
35
+ * @param option - Configuration for the section label
36
+ * @returns Bold label + split marker
37
+ */
38
+ export declare const formatMDXDetails: ({ dataOpen, }: CollapsibleOption) => MDXString;
39
+ /**
40
+ * Replaces front matter with an H1 title heading.
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
44
+ */
45
+ export declare const formatMDXFrontmatter: (_props: Maybe<FrontMatterOptions>, formatted: Maybe<string[]>) => MDXString;
46
+ /** mdBook expects `.md` files; override the default `.mdx` extension. */
47
+ export declare const mdxExtension = ".md";
48
+ /**
49
+ * Returns the link unchanged — mdBook resolves `.md` links natively.
50
+ * @param link - Link data with URL and text
51
+ * @returns The link with `.md` appended to extensionless absolute paths
52
+ */
53
+ export declare const formatMDXLink: (link: TypeLink) => TypeLink;
54
+ export { formatMDXBullet, formatMDXNameEntity, formatMDXSpecifiedByLink, } from "../defaults";
55
+ /**
56
+ * Creates an mdBook formatter.
57
+ * @param _meta - Unused metadata parameter
58
+ * @returns A complete {@link Formatter} implementation for mdBook output
59
+ */
60
+ export declare const createMDXFormatter: (_meta?: Maybe<MetaInfo>) => Formatter;
61
+ /**
62
+ * Builds `src/SUMMARY.md` after all pages have been written.
63
+ *
64
+ * mdBook requires every page to be listed in `SUMMARY.md` before the site can
65
+ * be built. This hook collects all rendered pages from the event, groups them
66
+ * by top-level section (Operations / Types) and category, then writes the file.
67
+ */
68
+ export declare const afterRenderFilesHook: RenderFilesHook;
69
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +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,EACL,SAAS,EACT,QAAQ,EACR,eAAe,EACf,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAkBjC;;;;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,SAGF,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,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAW5D,CAAC;AAeF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,eAiFlC,CAAC"}