@graphql-markdown/formatters 1.1.2 → 1.2.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.
- package/README.md +1 -0
- package/dist/docfx/index.d.ts.map +1 -1
- package/dist/docfx/index.js +6 -5
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -1
- package/dist/mdbook/index.d.ts.map +1 -1
- package/dist/mdbook/index.js +1 -13
- package/dist/mdx/index.d.ts +52 -0
- package/dist/mdx/index.d.ts.map +1 -0
- package/dist/mdx/index.js +94 -0
- package/dist/mkdocs/index.d.ts.map +1 -1
- package/dist/mkdocs/index.js +1 -12
- package/dist/output.d.ts +8 -1
- package/dist/output.d.ts.map +1 -1
- package/dist/output.js +27 -3
- package/package.json +21 -6
package/README.md
CHANGED
|
@@ -50,6 +50,7 @@ Each formatter has its own setup guide:
|
|
|
50
50
|
| HonKit | `@graphql-markdown/formatters/honkit` | [Guide](src/honkit/README.md) |
|
|
51
51
|
| Hugo | `@graphql-markdown/formatters/hugo` | [Guide](src/hugo/README.md) |
|
|
52
52
|
| mdBook | `@graphql-markdown/formatters/mdbook` | [Guide](src/mdbook/README.md) |
|
|
53
|
+
| Generic MDX | `@graphql-markdown/formatters/mdx` | [Guide](src/mdx/README.md) |
|
|
53
54
|
| MkDocs | `@graphql-markdown/formatters/mkdocs` | [Guide](src/mkdocs/README.md) |
|
|
54
55
|
| Next.js + Fumadocs | `@graphql-markdown/formatters/fumadocs` | [Guide](src/fumadocs/README.md) |
|
|
55
56
|
| Vocs | `@graphql-markdown/formatters/vocs` | [Guide](src/vocs/README.md) |
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docfx/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,SAAS,EACT,kBAAkB,EAClB,KAAK,EAEL,SAAS,EACT,QAAQ,EACR,sBAAsB,EACtB,QAAQ,EACT,MAAM,yBAAyB,CAAC;AA+BjC,sFAAsF;AACtF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAIlD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,wBAAyB,KAAK,KAAG,SAI3D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAIF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,UACxB,KAAK,CAAC,kBAAkB,CAAC,aACrB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAgBF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAU,QAAQ,KAAG,QAE9C,CAAC;AAEF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAY5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAG,KAAc,CAAC;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/docfx/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,SAAS,EACT,kBAAkB,EAClB,KAAK,EAEL,SAAS,EACT,QAAQ,EACR,sBAAsB,EACtB,QAAQ,EACT,MAAM,yBAAyB,CAAC;AA+BjC,sFAAsF;AACtF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAIlD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,wBAAyB,KAAK,KAAG,SAI3D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAIF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,UACxB,KAAK,CAAC,kBAAkB,CAAC,aACrB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAgBF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAU,QAAQ,KAAG,QAE9C,CAAC;AAEF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAY5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAG,KAAc,CAAC;AA0P3C,eAAO,MAAM,2BAA2B,EAAE,sBAiDzC,CAAC"}
|
package/dist/docfx/index.js
CHANGED
|
@@ -133,7 +133,7 @@ const isAbsoluteInternalLink = (content, urlStart) => {
|
|
|
133
133
|
/**
|
|
134
134
|
* Resolves an internal link to its relative path within the generated documentation.
|
|
135
135
|
*/
|
|
136
|
-
const resolveLink = (urlWithHash, filePath, outputDir, normalizedBaseURL, baseSegment) => {
|
|
136
|
+
const resolveLink = (urlWithHash, filePath, outputDir, normalizedBaseURL, baseSegment, knownDocPaths) => {
|
|
137
137
|
const sepIdx = urlWithHash.indexOf("#");
|
|
138
138
|
const [urlPath, hash] = sepIdx < 0
|
|
139
139
|
? [urlWithHash, ""]
|
|
@@ -147,6 +147,7 @@ const resolveLink = (urlWithHash, filePath, outputDir, normalizedBaseURL, baseSe
|
|
|
147
147
|
baseURL: normalizedBaseURL,
|
|
148
148
|
currentFilePath: filePath,
|
|
149
149
|
extension: exports.mdxExtension,
|
|
150
|
+
knownDocPaths,
|
|
150
151
|
outputDir,
|
|
151
152
|
targetUrlPath: urlPath.slice(baseIndex),
|
|
152
153
|
});
|
|
@@ -156,7 +157,7 @@ const resolveLink = (urlWithHash, filePath, outputDir, normalizedBaseURL, baseSe
|
|
|
156
157
|
* Rewrites all absolute internal links in the content to relative links
|
|
157
158
|
* based on the file's location and the documentation structure.
|
|
158
159
|
*/
|
|
159
|
-
const rewriteInternalLinks = (content, filePath, outputDir, baseURL) => {
|
|
160
|
+
const rewriteInternalLinks = (content, filePath, outputDir, baseURL, knownDocPaths) => {
|
|
160
161
|
const normalizedBaseURL = baseURL.split("/").filter(Boolean).join("/");
|
|
161
162
|
const baseSegment = `/${normalizedBaseURL}/`;
|
|
162
163
|
// Use indexOf scanning instead of regex to avoid ReDoS on file content.
|
|
@@ -175,7 +176,7 @@ const rewriteInternalLinks = (content, filePath, outputDir, baseURL) => {
|
|
|
175
176
|
pos = urlStart;
|
|
176
177
|
continue;
|
|
177
178
|
}
|
|
178
|
-
out.push(content.slice(pos, markerPos), resolveLink(match.urlWithHash, filePath, outputDir, normalizedBaseURL, baseSegment));
|
|
179
|
+
out.push(content.slice(pos, markerPos), resolveLink(match.urlWithHash, filePath, outputDir, normalizedBaseURL, baseSegment, knownDocPaths));
|
|
179
180
|
pos = match.closePos + 1;
|
|
180
181
|
}
|
|
181
182
|
return out.join("");
|
|
@@ -285,7 +286,7 @@ const updateTocChain = async (page, outputAdapter) => {
|
|
|
285
286
|
}
|
|
286
287
|
};
|
|
287
288
|
const afterRenderTypeEntitiesHook = async (event) => {
|
|
288
|
-
const { baseURL, filePath, name, outputAdapter, outputDir } = event.data;
|
|
289
|
+
const { baseURL, filePath, knownDocPaths, name, outputAdapter, outputDir } = event.data;
|
|
289
290
|
const pagePath = (0, node_path_1.relative)(outputDir, filePath);
|
|
290
291
|
// Rewrite uid as a path-derived value to guarantee uniqueness across the site.
|
|
291
292
|
// e.g. operations/queries/continent.md → uid: operations-queries-continent
|
|
@@ -298,7 +299,7 @@ const afterRenderTypeEntitiesHook = async (event) => {
|
|
|
298
299
|
// matches newlines, which would overlap with the `m`-flag line anchors and
|
|
299
300
|
// cause polynomial backtracking when no "uid:" line is present.
|
|
300
301
|
const withUid = content.replace(/^([ \t]*)uid:.*$/m, `$1uid: ${uid}`);
|
|
301
|
-
const rewritten = rewriteInternalLinks(withUid, filePath, outputDir, baseURL);
|
|
302
|
+
const rewritten = rewriteInternalLinks(withUid, filePath, outputDir, baseURL, knownDocPaths);
|
|
302
303
|
if (rewritten !== content) {
|
|
303
304
|
await (0, output_1.writeOutput)(filePath, rewritten, outputAdapter);
|
|
304
305
|
}
|
package/dist/index.d.ts
CHANGED
|
@@ -20,6 +20,7 @@ export * as fumadocs from "./fumadocs/index";
|
|
|
20
20
|
export * as honkit from "./honkit/index";
|
|
21
21
|
export * as hugo from "./hugo/index";
|
|
22
22
|
export * as mdbook from "./mdbook/index";
|
|
23
|
+
export * as mdx from "./mdx/index";
|
|
23
24
|
export * as mkdocs from "./mkdocs/index";
|
|
24
25
|
export * as starlight from "./starlight/index";
|
|
25
26
|
export * as vocs from "./vocs/index";
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +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"}
|
|
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,GAAG,MAAM,aAAa,CAAC;AACnC,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
CHANGED
|
@@ -49,13 +49,14 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
49
49
|
};
|
|
50
50
|
})();
|
|
51
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;
|
|
52
|
+
exports.vocs = exports.starlight = exports.mkdocs = exports.mdx = exports.mdbook = exports.hugo = exports.honkit = exports.fumadocs = exports.docfx = exports.docusaurus = void 0;
|
|
53
53
|
exports.docusaurus = __importStar(require("./docusaurus/index"));
|
|
54
54
|
exports.docfx = __importStar(require("./docfx/index"));
|
|
55
55
|
exports.fumadocs = __importStar(require("./fumadocs/index"));
|
|
56
56
|
exports.honkit = __importStar(require("./honkit/index"));
|
|
57
57
|
exports.hugo = __importStar(require("./hugo/index"));
|
|
58
58
|
exports.mdbook = __importStar(require("./mdbook/index"));
|
|
59
|
+
exports.mdx = __importStar(require("./mdx/index"));
|
|
59
60
|
exports.mkdocs = __importStar(require("./mkdocs/index"));
|
|
60
61
|
exports.starlight = __importStar(require("./starlight/index"));
|
|
61
62
|
exports.vocs = __importStar(require("./vocs/index"));
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mdbook/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,KAAK,EAEL,SAAS,EACT,QAAQ,EACR,eAAe,EACf,sBAAsB,EACtB,QAAQ,EACT,MAAM,yBAAyB,CAAC;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mdbook/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,KAAK,EAEL,SAAS,EACT,QAAQ,EACR,eAAe,EACf,sBAAsB,EACtB,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAuBjC;;;;GAIG;AACH,eAAO,MAAM,cAAc,aAAc,KAAK,KAAG,SAEhD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAIF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,kBAE1B,iBAAiB,KAAG,SAEtB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,WACvB,KAAK,CAAC,kBAAkB,CAAC,aACtB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAEF,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,YAAY,QAAQ,CAAC;AAElC;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAU,QAAQ,KAAG,QAU9C,CAAC;AAEF,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAIrB;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,EAAE,sBAIzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAY5D,CAAC;AAeF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,eAkFlC,CAAC"}
|
package/dist/mdbook/index.js
CHANGED
|
@@ -87,19 +87,7 @@ Object.defineProperty(exports, "formatMDXBullet", { enumerable: true, get: funct
|
|
|
87
87
|
Object.defineProperty(exports, "formatMDXNameEntity", { enumerable: true, get: function () { return defaults_2.formatMDXNameEntity; } });
|
|
88
88
|
Object.defineProperty(exports, "formatMDXPermalink", { enumerable: true, get: function () { return defaults_2.formatMDXPermalink; } });
|
|
89
89
|
Object.defineProperty(exports, "formatMDXSpecifiedByLink", { enumerable: true, get: function () { return defaults_2.formatMDXSpecifiedByLink; } });
|
|
90
|
-
const rewriteInternalLinks = (
|
|
91
|
-
return content.replaceAll(/\]\((\/[^)\s#]+)(#[^)\s]+)?\)/g, (_match, urlPath, hash = "") => {
|
|
92
|
-
const relativePath = (0, utils_1.toRelativeGeneratedDocLink)({
|
|
93
|
-
baseURL,
|
|
94
|
-
currentFilePath: filePath,
|
|
95
|
-
extension: exports.mdxExtension,
|
|
96
|
-
outputDir,
|
|
97
|
-
targetUrlPath: urlPath,
|
|
98
|
-
});
|
|
99
|
-
const target = relativePath ?? urlPath;
|
|
100
|
-
return `](${target}${hash})`;
|
|
101
|
-
});
|
|
102
|
-
};
|
|
90
|
+
const rewriteInternalLinks = (0, output_1.createInternalLinksRewriter)(exports.mdxExtension);
|
|
103
91
|
/**
|
|
104
92
|
* Rewrites absolute generated doc links to page-relative `.md` paths after each page is rendered.
|
|
105
93
|
*
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Generic MDX formatter for GraphQL documentation output.
|
|
3
|
+
*
|
|
4
|
+
* Produces framework-neutral `.mdx` pages: plain Markdown and JSX-safe HTML,
|
|
5
|
+
* with no framework components and no `import` declarations.
|
|
6
|
+
* Header permalinks are escaped (`\{#id\}`) so that they remain valid MDX.
|
|
7
|
+
* YAML front matter is kept, and internal links are rewritten to page-relative paths.
|
|
8
|
+
*
|
|
9
|
+
* @packageDocumentation
|
|
10
|
+
*/
|
|
11
|
+
import type { AdmonitionType, CollapsibleOption, Formatter, Maybe, MDXString, MetaInfo, RenderTypeEntitiesHook, TypeLink } from "@graphql-markdown/types";
|
|
12
|
+
import { formatMDXBadge, formatMDXBullet, formatMDXEscapedPermalink, formatMDXFrontmatter, formatMDXNameEntity, formatMDXSpecifiedByLink } from "../defaults";
|
|
13
|
+
/** Generic MDX pages use the `.mdx` extension. */
|
|
14
|
+
export declare const mdxExtension = ".mdx";
|
|
15
|
+
/**
|
|
16
|
+
* Formats an admonition as a Markdown blockquote with a bold type/title label.
|
|
17
|
+
* @param admonition - Admonition data with text, title, and type
|
|
18
|
+
* @param _meta - Unused metadata parameter
|
|
19
|
+
* @returns Formatted admonition string
|
|
20
|
+
*/
|
|
21
|
+
export declare const formatMDXAdmonition: ({ text, title, type }: AdmonitionType, _meta: Maybe<MetaInfo>) => MDXString;
|
|
22
|
+
/**
|
|
23
|
+
* Formats a collapsible block as an HTML `<details>` element.
|
|
24
|
+
* The output is split on `\r` by the printer into [openSection, closeSection].
|
|
25
|
+
* @param option - Configuration for open/close label text
|
|
26
|
+
* @returns Formatted collapsible string
|
|
27
|
+
*/
|
|
28
|
+
export declare const formatMDXDetails: ({ dataOpen, dataClose, }: CollapsibleOption) => MDXString;
|
|
29
|
+
/**
|
|
30
|
+
* Rewrites extensionless absolute links so they point to `.mdx` pages.
|
|
31
|
+
* @param link - Link data with URL and text
|
|
32
|
+
* @returns The link with `.mdx` appended to extensionless absolute paths
|
|
33
|
+
*/
|
|
34
|
+
export declare const formatMDXLink: (link: TypeLink) => TypeLink;
|
|
35
|
+
export { formatMDXBadge, formatMDXBullet, formatMDXFrontmatter, formatMDXNameEntity, formatMDXSpecifiedByLink, };
|
|
36
|
+
/**
|
|
37
|
+
* Formats a header permalink with escaped braces (`\{#id\}`), valid in MDX.
|
|
38
|
+
* @param id - The ID of the section header
|
|
39
|
+
* @returns Escaped permalink string
|
|
40
|
+
*/
|
|
41
|
+
export declare const formatMDXPermalink: typeof formatMDXEscapedPermalink;
|
|
42
|
+
/**
|
|
43
|
+
* Rewrites absolute generated doc links to page-relative `.mdx` paths after each page is rendered.
|
|
44
|
+
*/
|
|
45
|
+
export declare const afterRenderTypeEntitiesHook: RenderTypeEntitiesHook;
|
|
46
|
+
/**
|
|
47
|
+
* Creates a generic MDX formatter.
|
|
48
|
+
* @param _meta - Unused metadata parameter
|
|
49
|
+
* @returns A complete {@link Formatter} implementation for generic MDX output
|
|
50
|
+
*/
|
|
51
|
+
export declare const createMDXFormatter: (_meta?: Maybe<MetaInfo>) => Formatter;
|
|
52
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mdx/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,SAAS,EACT,KAAK,EACL,SAAS,EACT,QAAQ,EACR,sBAAsB,EACtB,QAAQ,EACT,MAAM,yBAAyB,CAAC;AAMjC,OAAO,EACL,cAAc,EACd,eAAe,EACf,yBAAyB,EACzB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACzB,MAAM,aAAa,CAAC;AAGrB,kDAAkD;AAClD,eAAO,MAAM,YAAY,SAAS,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAGF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,6BAG1B,iBAAiB,KAAG,SAEtB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAU,QAAQ,KAAG,QAU9C,CAAC;AAEF,OAAO,EACL,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,GACzB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,kCAA4B,CAAC;AAI5D;;GAEG;AACH,eAAO,MAAM,2BAA2B,EAAE,sBAIzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAY5D,CAAC"}
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Generic MDX formatter for GraphQL documentation output.
|
|
4
|
+
*
|
|
5
|
+
* Produces framework-neutral `.mdx` pages: plain Markdown and JSX-safe HTML,
|
|
6
|
+
* with no framework components and no `import` declarations.
|
|
7
|
+
* Header permalinks are escaped (`\{#id\}`) so that they remain valid MDX.
|
|
8
|
+
* YAML front matter is kept, and internal links are rewritten to page-relative paths.
|
|
9
|
+
*
|
|
10
|
+
* @packageDocumentation
|
|
11
|
+
*/
|
|
12
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
13
|
+
exports.createMDXFormatter = exports.afterRenderTypeEntitiesHook = exports.formatMDXPermalink = exports.formatMDXSpecifiedByLink = exports.formatMDXNameEntity = exports.formatMDXFrontmatter = exports.formatMDXBullet = exports.formatMDXBadge = exports.formatMDXLink = exports.formatMDXDetails = exports.formatMDXAdmonition = exports.mdxExtension = void 0;
|
|
14
|
+
const helpers_1 = require("@graphql-markdown/helpers");
|
|
15
|
+
const utils_1 = require("@graphql-markdown/utils");
|
|
16
|
+
const defaults_1 = require("../defaults");
|
|
17
|
+
Object.defineProperty(exports, "formatMDXBadge", { enumerable: true, get: function () { return defaults_1.formatMDXBadge; } });
|
|
18
|
+
Object.defineProperty(exports, "formatMDXBullet", { enumerable: true, get: function () { return defaults_1.formatMDXBullet; } });
|
|
19
|
+
Object.defineProperty(exports, "formatMDXFrontmatter", { enumerable: true, get: function () { return defaults_1.formatMDXFrontmatter; } });
|
|
20
|
+
Object.defineProperty(exports, "formatMDXNameEntity", { enumerable: true, get: function () { return defaults_1.formatMDXNameEntity; } });
|
|
21
|
+
Object.defineProperty(exports, "formatMDXSpecifiedByLink", { enumerable: true, get: function () { return defaults_1.formatMDXSpecifiedByLink; } });
|
|
22
|
+
const output_1 = require("../output");
|
|
23
|
+
/** Generic MDX pages use the `.mdx` extension. */
|
|
24
|
+
exports.mdxExtension = ".mdx";
|
|
25
|
+
/**
|
|
26
|
+
* Formats an admonition as a Markdown blockquote with a bold type/title label.
|
|
27
|
+
* @param admonition - Admonition data with text, title, and type
|
|
28
|
+
* @param _meta - Unused metadata parameter
|
|
29
|
+
* @returns Formatted admonition string
|
|
30
|
+
*/
|
|
31
|
+
const formatMDXAdmonition = ({ text, title, type }, _meta) => {
|
|
32
|
+
const label = title?.trim() ? title.trim() : type.toUpperCase();
|
|
33
|
+
return `${utils_1.MARKDOWN_EOP}> **${label}**${utils_1.MARKDOWN_EOL}>${utils_1.MARKDOWN_EOL}${(0, helpers_1.quoteMarkdownLines)(text, utils_1.MARKDOWN_EOL)}${utils_1.MARKDOWN_EOP}`;
|
|
34
|
+
};
|
|
35
|
+
exports.formatMDXAdmonition = formatMDXAdmonition;
|
|
36
|
+
/**
|
|
37
|
+
* Formats a collapsible block as an HTML `<details>` element.
|
|
38
|
+
* The output is split on `\r` by the printer into [openSection, closeSection].
|
|
39
|
+
* @param option - Configuration for open/close label text
|
|
40
|
+
* @returns Formatted collapsible string
|
|
41
|
+
*/
|
|
42
|
+
const formatMDXDetails = ({ dataOpen, dataClose, }) => {
|
|
43
|
+
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}`;
|
|
44
|
+
};
|
|
45
|
+
exports.formatMDXDetails = formatMDXDetails;
|
|
46
|
+
/**
|
|
47
|
+
* Rewrites extensionless absolute links so they point to `.mdx` pages.
|
|
48
|
+
* @param link - Link data with URL and text
|
|
49
|
+
* @returns The link with `.mdx` appended to extensionless absolute paths
|
|
50
|
+
*/
|
|
51
|
+
const formatMDXLink = (link) => {
|
|
52
|
+
const { url } = link;
|
|
53
|
+
if (!url) {
|
|
54
|
+
return link;
|
|
55
|
+
}
|
|
56
|
+
return {
|
|
57
|
+
...link,
|
|
58
|
+
url: (0, helpers_1.appendExtensionToAbsolutePathWithoutExtension)(url, exports.mdxExtension),
|
|
59
|
+
};
|
|
60
|
+
};
|
|
61
|
+
exports.formatMDXLink = formatMDXLink;
|
|
62
|
+
/**
|
|
63
|
+
* Formats a header permalink with escaped braces (`\{#id\}`), valid in MDX.
|
|
64
|
+
* @param id - The ID of the section header
|
|
65
|
+
* @returns Escaped permalink string
|
|
66
|
+
*/
|
|
67
|
+
exports.formatMDXPermalink = defaults_1.formatMDXEscapedPermalink;
|
|
68
|
+
const rewriteInternalLinks = (0, output_1.createInternalLinksRewriter)(exports.mdxExtension);
|
|
69
|
+
/**
|
|
70
|
+
* Rewrites absolute generated doc links to page-relative `.mdx` paths after each page is rendered.
|
|
71
|
+
*/
|
|
72
|
+
const afterRenderTypeEntitiesHook = async (event) => {
|
|
73
|
+
await (0, output_1.rewriteRenderedPage)(event, rewriteInternalLinks);
|
|
74
|
+
};
|
|
75
|
+
exports.afterRenderTypeEntitiesHook = afterRenderTypeEntitiesHook;
|
|
76
|
+
/**
|
|
77
|
+
* Creates a generic MDX formatter.
|
|
78
|
+
* @param _meta - Unused metadata parameter
|
|
79
|
+
* @returns A complete {@link Formatter} implementation for generic MDX output
|
|
80
|
+
*/
|
|
81
|
+
const createMDXFormatter = (_meta) => {
|
|
82
|
+
return {
|
|
83
|
+
formatMDXBadge: defaults_1.formatMDXBadge,
|
|
84
|
+
formatMDXAdmonition: exports.formatMDXAdmonition,
|
|
85
|
+
formatMDXBullet: defaults_1.formatMDXBullet,
|
|
86
|
+
formatMDXDetails: exports.formatMDXDetails,
|
|
87
|
+
formatMDXFrontmatter: defaults_1.formatMDXFrontmatter,
|
|
88
|
+
formatMDXLink: exports.formatMDXLink,
|
|
89
|
+
formatMDXNameEntity: defaults_1.formatMDXNameEntity,
|
|
90
|
+
formatMDXPermalink: exports.formatMDXPermalink,
|
|
91
|
+
formatMDXSpecifiedByLink: defaults_1.formatMDXSpecifiedByLink,
|
|
92
|
+
};
|
|
93
|
+
};
|
|
94
|
+
exports.createMDXFormatter = createMDXFormatter;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mkdocs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,KAAK,EACL,SAAS,EACT,QAAQ,EACR,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mkdocs/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,KAAK,EACL,iBAAiB,EACjB,SAAS,EACT,kBAAkB,EAClB,KAAK,EACL,SAAS,EACT,QAAQ,EACR,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,eAAe,EAEf,aAAa,EACb,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAGrB,eAAO,MAAM,SAAS;;;;CAIrB,CAAC;AAeF;;;;GAIG;AACH,eAAO,MAAM,cAAc,aAAc,KAAK,KAAG,SAEhD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,0BACP,cAAc,SAC9B,KAAK,CAAC,QAAQ,CAAC,KACrB,SAIF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6BAG1B,iBAAiB,KAAG,SAEtB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,WACvB,KAAK,CAAC,kBAAkB,CAAC,aACtB,KAAK,CAAC,MAAM,EAAE,CAAC,KACzB,SAEF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,SACxB,MAAM,eACC,KAAK,CAAC,MAAM,CAAC,KACzB,SAGF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAAS,MAAM,KAAG,SAEtD,CAAC;AAEF,2FAA2F;AAC3F,eAAO,MAAM,YAAY,EAAG,KAAc,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,sBAIzC,CAAC;AAEF,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,WAAY,KAAK,CAAC,QAAQ,CAAC,KAAG,SAY5D,CAAC"}
|
package/dist/mkdocs/index.js
CHANGED
|
@@ -28,18 +28,7 @@ const ADMONITION_TYPE_MAP = {
|
|
|
28
28
|
caution: "warning",
|
|
29
29
|
success: "success",
|
|
30
30
|
};
|
|
31
|
-
const rewriteInternalLinks = (
|
|
32
|
-
return content.replaceAll(/\]\((\/[^)\s#]+)(#[^)\s]+)?\)/g, (_match, urlPath, hash = "") => {
|
|
33
|
-
const relativePath = (0, utils_1.toRelativeGeneratedDocLink)({
|
|
34
|
-
baseURL,
|
|
35
|
-
currentFilePath: filePath,
|
|
36
|
-
outputDir,
|
|
37
|
-
targetUrlPath: urlPath,
|
|
38
|
-
});
|
|
39
|
-
const target = relativePath ?? urlPath;
|
|
40
|
-
return `](${target}${hash})`;
|
|
41
|
-
});
|
|
42
|
-
};
|
|
31
|
+
const rewriteInternalLinks = (0, output_1.createInternalLinksRewriter)();
|
|
43
32
|
/**
|
|
44
33
|
* Formats a badge as an inline HTML mark element.
|
|
45
34
|
* @param badge - Badge data containing text and optional classname
|
package/dist/output.d.ts
CHANGED
|
@@ -54,5 +54,12 @@ export declare const writeOutput: (filePath: string, content: string, outputAdap
|
|
|
54
54
|
* @param event - The hook event, carrying the page path and its destination
|
|
55
55
|
* @param rewrite - Returns the new content, or the content unchanged to skip
|
|
56
56
|
*/
|
|
57
|
-
export declare const rewriteRenderedPage: (event: unknown, rewrite: (content: string, filePath: string, outputDir: string, baseURL: string) => string) => Promise<void>;
|
|
57
|
+
export declare const rewriteRenderedPage: (event: unknown, rewrite: (content: string, filePath: string, outputDir: string, baseURL: string, linkRoot?: string, knownDocPaths?: ReadonlySet<string>) => string) => Promise<void>;
|
|
58
|
+
/**
|
|
59
|
+
* Creates a rewriter turning absolute generated doc links into page-relative ones.
|
|
60
|
+
*
|
|
61
|
+
* @param extension - Page extension to resolve targets with (defaults to `.md`)
|
|
62
|
+
* @returns A rewrite function usable with {@link rewriteRenderedPage}
|
|
63
|
+
*/
|
|
64
|
+
export declare const createInternalLinksRewriter: (extension?: string) => ((content: string, filePath: string, outputDir: string, baseURL: string, linkRoot?: string, knownDocPaths?: ReadonlySet<string>) => string);
|
|
58
65
|
//# sourceMappingURL=output.d.ts.map
|
package/dist/output.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;
|
|
1
|
+
{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AA6BpE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU,aACX,MAAM,iBACD,KAAK,CAAC,aAAa,CAAC,KAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAgB5B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,aACnB,MAAM,iBACD,KAAK,CAAC,aAAa,CAAC,KAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAE5B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,aACZ,MAAM,WACP,MAAM,iBACA,KAAK,CAAC,aAAa,CAAC,YACzB,MAAM,KACf,OAAO,CAAC,IAAI,CAQd,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,UACvB,OAAO,WACL,CACP,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,KAChC,MAAM,KACV,OAAO,CAAC,IAAI,CAuCd,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,eAC1B,MAAM,KACjB,CAAC,CACF,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,KAChC,MAAM,CAoBV,CAAC"}
|
package/dist/output.js
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
* @packageDocumentation
|
|
11
11
|
*/
|
|
12
12
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
13
|
-
exports.rewriteRenderedPage = exports.writeOutput = exports.readOptionalOutput = exports.readOutput = void 0;
|
|
13
|
+
exports.createInternalLinksRewriter = exports.rewriteRenderedPage = exports.writeOutput = exports.readOptionalOutput = exports.readOutput = void 0;
|
|
14
14
|
const utils_1 = require("@graphql-markdown/utils");
|
|
15
15
|
/**
|
|
16
16
|
* Resolves the destination a hook must use, falling back to the filesystem.
|
|
@@ -99,14 +99,38 @@ exports.writeOutput = writeOutput;
|
|
|
99
99
|
* @param rewrite - Returns the new content, or the content unchanged to skip
|
|
100
100
|
*/
|
|
101
101
|
const rewriteRenderedPage = async (event, rewrite) => {
|
|
102
|
-
const { baseURL, filePath, outputAdapter, outputDir } = event.data;
|
|
102
|
+
const { baseURL, filePath, knownDocPaths, linkRoot, outputAdapter, outputDir, } = event.data;
|
|
103
103
|
const content = await (0, exports.readOutput)(filePath, outputAdapter);
|
|
104
104
|
if (typeof content !== "string") {
|
|
105
105
|
return;
|
|
106
106
|
}
|
|
107
|
-
const rewritten = rewrite(content, filePath, outputDir, baseURL);
|
|
107
|
+
const rewritten = rewrite(content, filePath, outputDir, baseURL, linkRoot, knownDocPaths);
|
|
108
108
|
if (rewritten !== content) {
|
|
109
109
|
await (0, exports.writeOutput)(filePath, rewritten, outputAdapter);
|
|
110
110
|
}
|
|
111
111
|
};
|
|
112
112
|
exports.rewriteRenderedPage = rewriteRenderedPage;
|
|
113
|
+
/**
|
|
114
|
+
* Creates a rewriter turning absolute generated doc links into page-relative ones.
|
|
115
|
+
*
|
|
116
|
+
* @param extension - Page extension to resolve targets with (defaults to `.md`)
|
|
117
|
+
* @returns A rewrite function usable with {@link rewriteRenderedPage}
|
|
118
|
+
*/
|
|
119
|
+
const createInternalLinksRewriter = (extension) => {
|
|
120
|
+
return (content, filePath, outputDir, baseURL, linkRoot, knownDocPaths) => {
|
|
121
|
+
return content.replaceAll(/\]\((\/[^)\s#]+)(#[^)\s]+)?\)/g, (_match, urlPath, hash = "") => {
|
|
122
|
+
const relativePath = (0, utils_1.toRelativeGeneratedDocLink)({
|
|
123
|
+
baseURL,
|
|
124
|
+
currentFilePath: filePath,
|
|
125
|
+
...(extension !== undefined && { extension }),
|
|
126
|
+
...(linkRoot !== undefined && { linkRoot }),
|
|
127
|
+
knownDocPaths,
|
|
128
|
+
outputDir,
|
|
129
|
+
targetUrlPath: urlPath,
|
|
130
|
+
});
|
|
131
|
+
const target = relativePath ?? urlPath;
|
|
132
|
+
return `](${target}${hash})`;
|
|
133
|
+
});
|
|
134
|
+
};
|
|
135
|
+
};
|
|
136
|
+
exports.createInternalLinksRewriter = createInternalLinksRewriter;
|
package/package.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@graphql-markdown/formatters",
|
|
3
3
|
"homepage": "https://graphql-markdown.dev",
|
|
4
|
-
"description": "Formatter presets for Docusaurus, Starlight, Fumadocs, Vocs, HonKit, Hugo, MkDocs, DocFX, and
|
|
4
|
+
"description": "Formatter presets for Docusaurus, Starlight, Fumadocs, Vocs, HonKit, Hugo, MkDocs, DocFX, mdBook, and generic MDX.",
|
|
5
5
|
"bugs": {
|
|
6
6
|
"url": "https://github.com/graphql-markdown/graphql-markdown/issues"
|
|
7
7
|
},
|
|
8
|
-
"version": "1.
|
|
8
|
+
"version": "1.2.0",
|
|
9
9
|
"license": "MIT",
|
|
10
10
|
"repository": {
|
|
11
11
|
"type": "git",
|
|
@@ -24,6 +24,7 @@
|
|
|
24
24
|
"mkdocs",
|
|
25
25
|
"docfx",
|
|
26
26
|
"mdbook",
|
|
27
|
+
"mdx",
|
|
27
28
|
"documentation",
|
|
28
29
|
"formatter"
|
|
29
30
|
],
|
|
@@ -131,6 +132,20 @@
|
|
|
131
132
|
"default": "./dist/mdbook/index.js"
|
|
132
133
|
}
|
|
133
134
|
},
|
|
135
|
+
"./mdx": {
|
|
136
|
+
"require": {
|
|
137
|
+
"types": "./dist/mdx/index.d.ts",
|
|
138
|
+
"default": "./dist/mdx/index.js"
|
|
139
|
+
},
|
|
140
|
+
"import": {
|
|
141
|
+
"types": "./dist/mdx/index.d.ts",
|
|
142
|
+
"default": "./dist/mdx/index.js"
|
|
143
|
+
},
|
|
144
|
+
"default": {
|
|
145
|
+
"types": "./dist/mdx/index.d.ts",
|
|
146
|
+
"default": "./dist/mdx/index.js"
|
|
147
|
+
}
|
|
148
|
+
},
|
|
134
149
|
"./mkdocs": {
|
|
135
150
|
"require": {
|
|
136
151
|
"types": "./dist/mkdocs/index.d.ts",
|
|
@@ -206,12 +221,12 @@
|
|
|
206
221
|
"test:watch": "vitest --watch"
|
|
207
222
|
},
|
|
208
223
|
"dependencies": {
|
|
209
|
-
"@graphql-markdown/helpers": "",
|
|
210
|
-
"@graphql-markdown/types": "",
|
|
211
|
-
"@graphql-markdown/utils": ""
|
|
224
|
+
"@graphql-markdown/helpers": "^1.2.3",
|
|
225
|
+
"@graphql-markdown/types": "^1.17.0",
|
|
226
|
+
"@graphql-markdown/utils": "^1.14.0"
|
|
212
227
|
},
|
|
213
228
|
"devDependencies": {
|
|
214
|
-
"@graphql-markdown/tooling-config": ""
|
|
229
|
+
"@graphql-markdown/tooling-config": "^1.0.0"
|
|
215
230
|
},
|
|
216
231
|
"directories": {
|
|
217
232
|
"test": "tests"
|