@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
package/README.md ADDED
@@ -0,0 +1,106 @@
1
+ # @graphql-markdown/formatters
2
+
3
+ Framework formatter presets for GraphQL-Markdown.
4
+
5
+ This package provides ready-to-use formatter presets for popular documentation frameworks, with each formatter in its own package subpath.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ npm install @graphql-markdown/formatters
11
+ ```
12
+
13
+ ## Quick Start
14
+
15
+ Use any formatter in your GraphQL-Markdown configuration:
16
+
17
+ ```yaml
18
+ schema: ./schema.graphql
19
+ extensions:
20
+ graphql-markdown:
21
+ rootPath: ./docs
22
+ baseURL: api
23
+ formatter: "@graphql-markdown/formatters/docusaurus"
24
+ ```
25
+
26
+ Or programmatically:
27
+
28
+ ```ts
29
+ import { runGraphQLMarkdown } from "@graphql-markdown/cli";
30
+
31
+ await runGraphQLMarkdown({
32
+ schema: "./schema.graphql",
33
+ rootPath: "./docs",
34
+ baseURL: "api",
35
+ formatter: "@graphql-markdown/formatters/docusaurus",
36
+ });
37
+ ```
38
+
39
+ The legacy `mdxParser` setting still works as a deprecated alias, but new configurations should use `formatter`.
40
+
41
+ ## Supported Formatters
42
+
43
+ Each formatter has its own setup guide:
44
+
45
+ | Framework | Package Path | Documentation |
46
+ | --------- | ------------ | ------------- |
47
+ | Astro Starlight | `@graphql-markdown/formatters/starlight` | [Guide](src/starlight/README.md) |
48
+ | DocFX | `@graphql-markdown/formatters/docfx` | [Guide](src/docfx/README.md) |
49
+ | Docusaurus | `@graphql-markdown/formatters/docusaurus` | [Guide](src/docusaurus/README.md) |
50
+ | HonKit | `@graphql-markdown/formatters/honkit` | [Guide](src/honkit/README.md) |
51
+ | Hugo | `@graphql-markdown/formatters/hugo` | [Guide](src/hugo/README.md) |
52
+ | mdBook | `@graphql-markdown/formatters/mdbook` | [Guide](src/mdbook/README.md) |
53
+ | MkDocs | `@graphql-markdown/formatters/mkdocs` | [Guide](src/mkdocs/README.md) |
54
+ | Next.js + Fumadocs | `@graphql-markdown/formatters/fumadocs` | [Guide](src/fumadocs/README.md) |
55
+ | Vocs | `@graphql-markdown/formatters/vocs` | [Guide](src/vocs/README.md) |
56
+
57
+ ## Custom Formatter
58
+
59
+ For frameworks not listed above, create a custom MDX module. See the [Integration Guide](https://graphql-markdown.dev/docs/advanced/integration-with-frameworks#custom-mdx-formatter) for the full formatter contract, the `formatMDXDetails` `\r` delimiter invariant, and examples of extending a preset.
60
+
61
+ ## Contributing
62
+
63
+ ### Add a New Formatter
64
+
65
+ 1. Create the formatter module at `src/<name>/index.ts`.
66
+ 2. Create documentation at `src/<name>/README.md`.
67
+ 3. Export the formatter from `src/index.ts`.
68
+ 4. Add a package subpath export for `./<name>` in `package.json` under `exports`.
69
+ 5. Add unit tests in `tests/unit/<name>/index.test.ts`.
70
+
71
+ ### Formatter Contract
72
+
73
+ A formatter module exports `createMDXFormatter` and any subset of the standard formatter functions (`formatMDXBadge`, `formatMDXAdmonition`, `formatMDXBullet`, `formatMDXDetails`, `formatMDXFrontmatter`, `formatMDXLink`, `formatMDXNameEntity`, `formatMDXSpecifiedByLink`). Optional exports include `mdxDeclaration`, `mdxExtension`, and lifecycle hooks.
74
+
75
+ See the [Integration Guide](https://graphql-markdown.dev/docs/advanced/integration-with-frameworks#custom-mdx-formatter) for the full contract, type signatures, and the `formatMDXDetails` `\r` delimiter invariant.
76
+
77
+ ### Testing Checklist
78
+
79
+ Add tests that verify:
80
+
81
+ 1. Each formatter function output for representative inputs.
82
+ 2. `createMDXFormatter` returns all required formatter methods.
83
+ 3. Framework-specific behavior and edge cases (for example link extension mapping, frontmatter behavior, empty title fallback).
84
+
85
+ Run targeted tests while developing:
86
+
87
+ ```bash
88
+ cd packages/formatters
89
+ bun run test:unit -- tests/unit/<name>/index.test.ts
90
+ ```
91
+
92
+ Run package checks before opening a PR:
93
+
94
+ ```bash
95
+ cd packages/formatters
96
+ bun run lint
97
+ bun run prettier
98
+ bun run test:unit
99
+ ```
100
+
101
+ For repository-wide validation:
102
+
103
+ ```bash
104
+ cd /path/to/graphql-markdown
105
+ bun run test
106
+ ```
@@ -0,0 +1,63 @@
1
+ /**
2
+ * Default formatter implementations shared across multiple formatter packages.
3
+ *
4
+ * These functions provide the standard/baseline rendering behaviour.
5
+ * Individual formatters import what they need and override only what differs.
6
+ *
7
+ * @packageDocumentation
8
+ */
9
+ import type { AdmonitionType, Badge, CollapsibleOption, FrontMatterOptions, Maybe, MDXString, MetaInfo, TypeLink } from "@graphql-markdown/types";
10
+ /**
11
+ * Formats a badge using an HTML `<mark>` element with a `gqlmd-mdx-badge` CSS class.
12
+ * @param badge - Badge data containing the text to display
13
+ * @returns Formatted badge string
14
+ */
15
+ export declare const formatMDXBadge: (badge: Badge) => MDXString;
16
+ /**
17
+ * Formats an admonition as an HTML `<fieldset>` element with `gqlmd-mdx-admonition-*` CSS classes.
18
+ * @param admonition - Admonition data with text, title, type, and optional icon
19
+ * @param _meta - Unused metadata parameter
20
+ * @returns Formatted admonition string
21
+ */
22
+ export declare const formatMDXAdmonition: ({ text, title, type, icon }: AdmonitionType, _meta: Maybe<MetaInfo>) => MDXString;
23
+ /**
24
+ * Formats a bullet point separator using a `<span>` with a `gqlmd-mdx-bullet` CSS class.
25
+ * @param text - Optional text to append after the bullet
26
+ * @returns Formatted bullet string
27
+ */
28
+ export declare const formatMDXBullet: (text?: string) => MDXString;
29
+ /**
30
+ * Formats a collapsible block as an HTML `<details>` element with a `gqlmd-mdx-details` CSS class.
31
+ * The summary label is uppercase; the close label is rendered as `<em>`.
32
+ * @param option - Configuration for open/close label text
33
+ * @returns Formatted details element string
34
+ */
35
+ export declare const formatMDXDetails: ({ dataOpen, dataClose, }: CollapsibleOption) => MDXString;
36
+ /**
37
+ * Formats YAML front matter wrapped in `---` delimiters.
38
+ * @param _props - Front matter options (unused)
39
+ * @param formatted - Pre-formatted front matter lines
40
+ * @returns Formatted front matter block, or empty string if no lines provided
41
+ */
42
+ export declare const formatMDXFrontmatter: (_props: Maybe<FrontMatterOptions>, formatted: Maybe<string[]>) => MDXString;
43
+ /**
44
+ * Formats a type link — returns the link unchanged (identity passthrough).
45
+ * @param link - The `TypeLink` object to format
46
+ * @returns The unmodified `TypeLink` object
47
+ */
48
+ export declare const formatMDXLink: (link: TypeLink) => TypeLink;
49
+ /**
50
+ * Formats a named entity using `<span>` and `<code>` elements with `gqlmd-mdx-entity-*` CSS classes.
51
+ * @param name - Entity name
52
+ * @param parentType - Optional parent type name for qualified references
53
+ * @returns Formatted entity reference string
54
+ */
55
+ export declare const formatMDXNameEntity: (name: string, parentType?: Maybe<string>) => MDXString;
56
+ /**
57
+ * Formats a "specified by" link as an HTML `<span>` with a `gqlmd-mdx-specifiedby` CSS class
58
+ * containing an anchor that opens in a new tab.
59
+ * @param url - URL to the specification
60
+ * @returns Formatted specification link string
61
+ */
62
+ export declare const formatMDXSpecifiedByLink: (url: string) => MDXString;
63
+ //# sourceMappingURL=defaults.d.ts.map
@@ -0,0 +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"}
@@ -0,0 +1,93 @@
1
+ "use strict";
2
+ /**
3
+ * Default formatter implementations shared across multiple formatter packages.
4
+ *
5
+ * These functions provide the standard/baseline rendering behaviour.
6
+ * Individual formatters import what they need and override only what differs.
7
+ *
8
+ * @packageDocumentation
9
+ */
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;
12
+ const helpers_1 = require("@graphql-markdown/helpers");
13
+ const utils_1 = require("@graphql-markdown/utils");
14
+ /**
15
+ * Formats a badge using an HTML `<mark>` element with a `gqlmd-mdx-badge` CSS class.
16
+ * @param badge - Badge data containing the text to display
17
+ * @returns Formatted badge string
18
+ */
19
+ const formatMDXBadge = (badge) => {
20
+ return `<mark class="gqlmd-mdx-badge">${badge.text}</mark>`;
21
+ };
22
+ exports.formatMDXBadge = formatMDXBadge;
23
+ /**
24
+ * Formats an admonition as an HTML `<fieldset>` element with `gqlmd-mdx-admonition-*` CSS classes.
25
+ * @param admonition - Admonition data with text, title, type, and optional icon
26
+ * @param _meta - Unused metadata parameter
27
+ * @returns Formatted admonition string
28
+ */
29
+ const formatMDXAdmonition = ({ text, title, type, icon }, _meta) => {
30
+ return `${utils_1.MARKDOWN_EOP}<fieldset class="gqlmd-mdx-admonition-fieldset">${utils_1.MARKDOWN_EOL}<legend class="gqlmd-mdx-admonition-legend"><span class="gqlmd-mdx-admonition-legend-type gqlmd-mdx-admonition-legend-type-${type.toLocaleLowerCase()}">${icon ?? type.toUpperCase()} ${title}</span></legend>${utils_1.MARKDOWN_EOL}<span>${text}</span>${utils_1.MARKDOWN_EOL}</fieldset>`;
31
+ };
32
+ exports.formatMDXAdmonition = formatMDXAdmonition;
33
+ /**
34
+ * Formats a bullet point separator using a `<span>` with a `gqlmd-mdx-bullet` CSS class.
35
+ * @param text - Optional text to append after the bullet
36
+ * @returns Formatted bullet string
37
+ */
38
+ const formatMDXBullet = (text = "") => {
39
+ return `<span class="gqlmd-mdx-bullet">&nbsp;●&nbsp;</span>${text}`;
40
+ };
41
+ exports.formatMDXBullet = formatMDXBullet;
42
+ /**
43
+ * Formats a collapsible block as an HTML `<details>` element with a `gqlmd-mdx-details` CSS class.
44
+ * The summary label is uppercase; the close label is rendered as `<em>`.
45
+ * @param option - Configuration for open/close label text
46
+ * @returns Formatted details element string
47
+ */
48
+ const formatMDXDetails = ({ dataOpen, dataClose, }) => {
49
+ return `${utils_1.MARKDOWN_EOP}<details class="gqlmd-mdx-details">${utils_1.MARKDOWN_EOL}<summary class="gqlmd-mdx-details-summary"><span class="gqlmd-mdx-details-summary-open">${dataOpen.toUpperCase()}</span></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}`;
50
+ };
51
+ exports.formatMDXDetails = formatMDXDetails;
52
+ /**
53
+ * Formats YAML front matter wrapped in `---` delimiters.
54
+ * @param _props - Front matter options (unused)
55
+ * @param formatted - Pre-formatted front matter lines
56
+ * @returns Formatted front matter block, or empty string if no lines provided
57
+ */
58
+ const formatMDXFrontmatter = (_props, formatted) => {
59
+ return (0, helpers_1.formatMarkdownFrontmatter)(formatted, utils_1.FRONT_MATTER_DELIMITER, utils_1.MARKDOWN_EOL);
60
+ };
61
+ exports.formatMDXFrontmatter = formatMDXFrontmatter;
62
+ /**
63
+ * Formats a type link — returns the link unchanged (identity passthrough).
64
+ * @param link - The `TypeLink` object to format
65
+ * @returns The unmodified `TypeLink` object
66
+ */
67
+ const formatMDXLink = (link) => {
68
+ return link;
69
+ };
70
+ exports.formatMDXLink = formatMDXLink;
71
+ /**
72
+ * Formats a named entity using `<span>` and `<code>` elements with `gqlmd-mdx-entity-*` CSS classes.
73
+ * @param name - Entity name
74
+ * @param parentType - Optional parent type name for qualified references
75
+ * @returns Formatted entity reference string
76
+ */
77
+ const formatMDXNameEntity = (name, parentType) => {
78
+ const parentName = parentType
79
+ ? `<code class="gqlmd-mdx-entity-parent">${parentType}</code>.`
80
+ : "";
81
+ return `<span class="gqlmd-mdx-entity">${parentName}<code class="gqlmd-mdx-entity-name">${name}</code></span>`;
82
+ };
83
+ exports.formatMDXNameEntity = formatMDXNameEntity;
84
+ /**
85
+ * Formats a "specified by" link as an HTML `<span>` with a `gqlmd-mdx-specifiedby` CSS class
86
+ * containing an anchor that opens in a new tab.
87
+ * @param url - URL to the specification
88
+ * @returns Formatted specification link string
89
+ */
90
+ const formatMDXSpecifiedByLink = (url) => {
91
+ return `<span class="gqlmd-mdx-specifiedby">Specification<a class="gqlmd-mdx-specifiedby-link" target="_blank" href="${url}" title="Specified by ${url}">⎘</a></span>`;
92
+ };
93
+ exports.formatMDXSpecifiedByLink = formatMDXSpecifiedByLink;
@@ -0,0 +1,56 @@
1
+ /**
2
+ * DocFX formatter for GraphQL documentation output.
3
+ *
4
+ * Produces Markdown compatible with Microsoft DocFX.
5
+ * Uses DocFX alert syntax for admonitions and injects the required
6
+ * `uid` front matter field for cross-reference resolution.
7
+ *
8
+ * @packageDocumentation
9
+ */
10
+ import type { AdmonitionType, Badge, Formatter, FrontMatterOptions, Maybe, MDXString, MetaInfo, RenderTypeEntitiesHook, TypeLink } from "@graphql-markdown/types";
11
+ /** Maps graphql-markdown badge classnames to Bootstrap 5 contextual badge classes. */
12
+ export declare const BADGE_CLASS_MAP: Record<string, string>;
13
+ /**
14
+ * Formats a badge using Bootstrap 5 badge classes available in DocFX's modern template.
15
+ * @param badge - Badge data containing text and optional classname
16
+ * @returns Formatted badge string
17
+ */
18
+ export declare const formatMDXBadge: ({ text, classname }: Badge) => MDXString;
19
+ /**
20
+ * Formats an admonition using DocFX alert syntax (`> [!TYPE]`).
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
+ * Formats YAML front matter, injecting a `uid` field required by DocFX
28
+ * for cross-reference resolution between pages.
29
+ * @param props - Front matter options; `id` is used as the DocFX `uid` value
30
+ * @param formatted - Pre-formatted front matter lines
31
+ * @returns Formatted front matter block, or empty string if no lines provided
32
+ */
33
+ export declare const formatMDXFrontmatter: (props: Maybe<FrontMatterOptions>, formatted: Maybe<string[]>) => MDXString;
34
+ /**
35
+ * Returns the link unchanged — DocFX resolves `.md` links natively.
36
+ * @param link - Link data with URL and text
37
+ * @returns The link unchanged
38
+ */
39
+ export declare const formatMDXLink: (link: TypeLink) => TypeLink;
40
+ export { formatMDXBullet, formatMDXDetails, formatMDXNameEntity, formatMDXSpecifiedByLink, } from "../defaults";
41
+ /**
42
+ * Creates a DocFX formatter.
43
+ * @param _meta - Unused metadata parameter
44
+ * @returns A complete {@link Formatter} implementation for DocFX output
45
+ */
46
+ export declare const createMDXFormatter: (_meta?: Maybe<MetaInfo>) => Formatter;
47
+ export declare const mdxExtension: ".md";
48
+ /**
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.
54
+ */
55
+ export declare const afterRenderTypeEntitiesHook: RenderTypeEntitiesHook;
56
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +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;AA8BjC,sFAAsF;AACtF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAIlD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,wBAAyB,KAAK,KAAG,SAI3D,CAAC;AAEF;;;;;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;AA6C3C;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,sBAoDzC,CAAC"}
@@ -0,0 +1,184 @@
1
+ "use strict";
2
+ /**
3
+ * DocFX formatter for GraphQL documentation output.
4
+ *
5
+ * Produces Markdown compatible with Microsoft DocFX.
6
+ * Uses DocFX alert syntax for admonitions and injects the required
7
+ * `uid` front matter field for cross-reference resolution.
8
+ *
9
+ * @packageDocumentation
10
+ */
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;
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
+ /** Maps graphql-markdown admonition types to DocFX alert types. */
18
+ const ALERT_TYPE_MAP = {
19
+ note: "NOTE",
20
+ tip: "TIP",
21
+ info: "IMPORTANT",
22
+ warning: "WARNING",
23
+ danger: "CAUTION",
24
+ deprecated: "WARNING",
25
+ caution: "CAUTION",
26
+ success: "NOTE",
27
+ };
28
+ /** Maps graphql-markdown badge classnames to Bootstrap 5 contextual badge classes. */
29
+ exports.BADGE_CLASS_MAP = {
30
+ DEPRECATED: "text-bg-danger",
31
+ NON_NULL: "text-bg-primary",
32
+ RELATION: "text-bg-info",
33
+ };
34
+ /**
35
+ * Formats a badge using Bootstrap 5 badge classes available in DocFX's modern template.
36
+ * @param badge - Badge data containing text and optional classname
37
+ * @returns Formatted badge string
38
+ */
39
+ const formatMDXBadge = ({ text, classname }) => {
40
+ const key = Array.isArray(classname) ? classname[0] : classname;
41
+ const variant = (key && exports.BADGE_CLASS_MAP[key]) ?? "text-bg-secondary";
42
+ return `<span class="badge ${variant}">${text}</span>`;
43
+ };
44
+ exports.formatMDXBadge = formatMDXBadge;
45
+ /**
46
+ * Formats an admonition using DocFX alert syntax (`> [!TYPE]`).
47
+ * @param admonition - Admonition data with text, title, and type
48
+ * @param _meta - Unused metadata parameter
49
+ * @returns Formatted admonition string
50
+ */
51
+ const formatMDXAdmonition = ({ text, title, type }, _meta) => {
52
+ const alertType = ALERT_TYPE_MAP[type.toLowerCase()] ?? "NOTE";
53
+ const titleLine = title ? `${utils_1.MARKDOWN_EOL}> **${title}**` : "";
54
+ return `${utils_1.MARKDOWN_EOP}> [!${alertType}]${titleLine}${utils_1.MARKDOWN_EOL}${(0, helpers_1.quoteMarkdownLines)(text, utils_1.MARKDOWN_EOL)}${utils_1.MARKDOWN_EOL}`;
55
+ };
56
+ exports.formatMDXAdmonition = formatMDXAdmonition;
57
+ /**
58
+ * Formats YAML front matter, injecting a `uid` field required by DocFX
59
+ * for cross-reference resolution between pages.
60
+ * @param props - Front matter options; `id` is used as the DocFX `uid` value
61
+ * @param formatted - Pre-formatted front matter lines
62
+ * @returns Formatted front matter block, or empty string if no lines provided
63
+ */
64
+ const formatMDXFrontmatter = (props, formatted) => {
65
+ if (!formatted)
66
+ return "";
67
+ // DocFX requires a uid field for cross-reference resolution between pages
68
+ const id = props && typeof props === "object" && "id" in props
69
+ ? props.id
70
+ : undefined;
71
+ const uidLine = id ? [` uid: ${id}`] : [];
72
+ return [
73
+ utils_1.FRONT_MATTER_DELIMITER,
74
+ ...uidLine,
75
+ ...formatted,
76
+ utils_1.FRONT_MATTER_DELIMITER,
77
+ ].join(utils_1.MARKDOWN_EOL);
78
+ };
79
+ exports.formatMDXFrontmatter = formatMDXFrontmatter;
80
+ /**
81
+ * Returns the link unchanged — DocFX resolves `.md` links natively.
82
+ * @param link - Link data with URL and text
83
+ * @returns The link unchanged
84
+ */
85
+ const formatMDXLink = (link) => {
86
+ return link;
87
+ };
88
+ exports.formatMDXLink = formatMDXLink;
89
+ var defaults_2 = require("../defaults");
90
+ Object.defineProperty(exports, "formatMDXBullet", { enumerable: true, get: function () { return defaults_2.formatMDXBullet; } });
91
+ Object.defineProperty(exports, "formatMDXDetails", { enumerable: true, get: function () { return defaults_2.formatMDXDetails; } });
92
+ Object.defineProperty(exports, "formatMDXNameEntity", { enumerable: true, get: function () { return defaults_2.formatMDXNameEntity; } });
93
+ Object.defineProperty(exports, "formatMDXSpecifiedByLink", { enumerable: true, get: function () { return defaults_2.formatMDXSpecifiedByLink; } });
94
+ /**
95
+ * Creates a DocFX formatter.
96
+ * @param _meta - Unused metadata parameter
97
+ * @returns A complete {@link Formatter} implementation for DocFX output
98
+ */
99
+ const createMDXFormatter = (_meta) => {
100
+ return {
101
+ formatMDXBadge: exports.formatMDXBadge,
102
+ formatMDXAdmonition: exports.formatMDXAdmonition,
103
+ formatMDXBullet: defaults_1.formatMDXBullet,
104
+ formatMDXDetails: defaults_1.formatMDXDetails,
105
+ formatMDXFrontmatter: exports.formatMDXFrontmatter,
106
+ formatMDXLink: exports.formatMDXLink,
107
+ formatMDXNameEntity: defaults_1.formatMDXNameEntity,
108
+ formatMDXSpecifiedByLink: defaults_1.formatMDXSpecifiedByLink,
109
+ };
110
+ };
111
+ exports.createMDXFormatter = createMDXFormatter;
112
+ exports.mdxExtension = ".md";
113
+ // ─── toc.yml builder ────────────────────────────────────────────────────────
114
+ const writeQueue = new Map();
115
+ const queueFileUpdate = async (filePath, update) => {
116
+ const previous = writeQueue.get(filePath) ?? Promise.resolve();
117
+ const next = previous.catch(() => { }).then(update);
118
+ writeQueue.set(filePath, next);
119
+ return next;
120
+ };
121
+ const updateToc = async (tocFilePath, name, href) => {
122
+ await queueFileUpdate(tocFilePath, async () => {
123
+ const entry = `- name: ${name}${utils_1.MARKDOWN_EOL} href: ${href}`;
124
+ if (!(await (0, utils_1.fileExists)(tocFilePath))) {
125
+ await (0, utils_1.saveFile)(tocFilePath, entry + utils_1.MARKDOWN_EOL);
126
+ return;
127
+ }
128
+ const existing = await (0, utils_1.readFile)(tocFilePath, "utf-8");
129
+ if (existing.includes(`href: ${href}`)) {
130
+ return;
131
+ }
132
+ await (0, utils_1.saveFile)(tocFilePath, existing.trimEnd() + utils_1.MARKDOWN_EOL + entry + utils_1.MARKDOWN_EOL);
133
+ });
134
+ };
135
+ // Tracks directories whose index.md has already been prepended to their toc.yml.
136
+ // Module-level so it persists across all hook invocations within one generation run.
137
+ const seenDirectories = new Set();
138
+ /**
139
+ * Builds DocFX `toc.yml` navigation files as each entity page is written.
140
+ *
141
+ * Walks up from the generated file to the graphql output root (`outputDir`),
142
+ * writing or updating a `toc.yml` at every directory level. Section index pages
143
+ * are prepended as an "Overview" entry on first encounter.
144
+ */
145
+ const afterRenderTypeEntitiesHook = async (event) => {
146
+ const { filePath, name, outputDir } = event.data;
147
+ const graphqlRoot = (0, node_path_1.resolve)(outputDir);
148
+ // Rewrite uid as a path-derived value to guarantee uniqueness across the site.
149
+ // e.g. operations/queries/continent.md → uid: operations-queries-continent
150
+ const uid = (0, node_path_1.relative)(graphqlRoot, filePath)
151
+ .replace(/\.mdx?$/, "")
152
+ .replaceAll(/[/\\]/g, "-");
153
+ const content = await (0, utils_1.readFile)(filePath, "utf-8");
154
+ const rewritten = content.replace(/^(\s*)uid:.*$/m, `$1uid: ${uid}`);
155
+ if (rewritten !== content) {
156
+ await (0, utils_1.saveFile)(filePath, rewritten);
157
+ }
158
+ let currentDir = (0, node_path_1.resolve)((0, node_path_1.dirname)(filePath));
159
+ let currentHref = (0, node_path_1.basename)(filePath);
160
+ let currentName = name;
161
+ while (currentDir.startsWith(graphqlRoot)) {
162
+ const tocPath = (0, node_path_1.resolve)(currentDir, "toc.yml");
163
+ if (!seenDirectories.has(currentDir)) {
164
+ seenDirectories.add(currentDir);
165
+ if (currentDir === graphqlRoot) {
166
+ // Homepage is written after hooks run, so add Overview unconditionally.
167
+ await updateToc(tocPath, "Overview", "index.md");
168
+ }
169
+ else {
170
+ const indexPath = (0, node_path_1.resolve)(currentDir, "index.md");
171
+ if (await (0, utils_1.fileExists)(indexPath)) {
172
+ await updateToc(tocPath, `${(0, utils_1.capitalize)((0, node_path_1.basename)(currentDir))} Overview`, "index.md");
173
+ }
174
+ }
175
+ }
176
+ await updateToc(tocPath, currentName, currentHref);
177
+ if (currentDir === graphqlRoot)
178
+ break;
179
+ currentHref = `${(0, node_path_1.basename)(currentDir)}/toc.yml`;
180
+ currentName = (0, utils_1.capitalize)((0, node_path_1.basename)(currentDir));
181
+ currentDir = (0, node_path_1.dirname)(currentDir);
182
+ }
183
+ };
184
+ exports.afterRenderTypeEntitiesHook = afterRenderTypeEntitiesHook;
@@ -0,0 +1,20 @@
1
+ /**
2
+ * DocFX formatter for GraphQL documentation output.
3
+ *
4
+ * Produces Markdown compatible with Microsoft DocFX.
5
+ * Uses DocFX alert syntax for admonitions and injects the required
6
+ * `uid` front matter field for cross-reference resolution.
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=docfx.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"docfx.d.ts","sourceRoot":"","sources":["../src/docfx.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,SACwB,CAAC;AAE1E,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,SAC0L,CAAC;AAElN,eAAO,MAAM,oBAAoB,UACxB,KAAK,CAAC,kBAAkB,CAAC,aACrB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAaF,CAAC;AAEF,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/docfx.js ADDED
@@ -0,0 +1,71 @@
1
+ "use strict";
2
+ /**
3
+ * DocFX formatter for GraphQL documentation output.
4
+ *
5
+ * Produces Markdown compatible with Microsoft DocFX.
6
+ * Uses DocFX alert syntax for admonitions and injects the required
7
+ * `uid` front matter field for cross-reference resolution.
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 DocFX alert types
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-docfx-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}<em>${dataClose}</em>${utils_1.MARKDOWN_EOL}</details>${utils_1.MARKDOWN_EOP}`;
40
+ exports.formatMDXDetails = formatMDXDetails;
41
+ const formatMDXFrontmatter = (props, formatted) => {
42
+ if (!formatted)
43
+ return "";
44
+ // DocFX requires a uid field for cross-reference resolution between pages
45
+ const id = props && typeof props === "object" && "id" in props
46
+ ? props.id
47
+ : undefined;
48
+ const uidLine = id ? [` uid: ${id}`] : [];
49
+ return [utils_1.FRONT_MATTER_DELIMITER, ...uidLine, ...formatted, utils_1.FRONT_MATTER_DELIMITER].join(utils_1.MARKDOWN_EOL);
50
+ };
51
+ exports.formatMDXFrontmatter = formatMDXFrontmatter;
52
+ const formatMDXLink = (link) => link;
53
+ exports.formatMDXLink = formatMDXLink;
54
+ const formatMDXNameEntity = (name, parentType) => {
55
+ const parentName = parentType ? `${parentType}.` : "";
56
+ return `\`${parentName}${name}\``;
57
+ };
58
+ exports.formatMDXNameEntity = formatMDXNameEntity;
59
+ const formatMDXSpecifiedByLink = (url) => `[Specification ⎘](${url})`;
60
+ exports.formatMDXSpecifiedByLink = formatMDXSpecifiedByLink;
61
+ const createMDXFormatter = (_meta) => ({
62
+ formatMDXBadge: exports.formatMDXBadge,
63
+ formatMDXAdmonition: exports.formatMDXAdmonition,
64
+ formatMDXBullet: exports.formatMDXBullet,
65
+ formatMDXDetails: exports.formatMDXDetails,
66
+ formatMDXFrontmatter: exports.formatMDXFrontmatter,
67
+ formatMDXLink: exports.formatMDXLink,
68
+ formatMDXNameEntity: exports.formatMDXNameEntity,
69
+ formatMDXSpecifiedByLink: exports.formatMDXSpecifiedByLink,
70
+ });
71
+ exports.createMDXFormatter = createMDXFormatter;