@graphql-markdown/nuxt-theme 0.0.0-stage → 0.1.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 +196 -2
- package/app/app-config.d.ts +15 -0
- package/app/app.config.ts +22 -0
- package/app/assets/css/main.css +85 -0
- package/app/components/ApiCodeColumn.vue +53 -0
- package/app/components/ApiDocumentContent.vue +45 -0
- package/app/components/ApiNamespaceLanding.vue +29 -0
- package/app/components/ApiOverviewGrid.vue +38 -0
- package/app/components/ApiSinglePageEntry.vue +75 -0
- package/app/components/ApiSinglePageSection.vue +32 -0
- package/app/components/SchemaCodeCard.vue +68 -0
- package/app/components/SiteFooter.vue +13 -0
- package/app/components/SiteHeader.vue +31 -0
- package/app/composables/useApiCodeCards.ts +96 -0
- package/app/composables/useApiDocument.ts +69 -0
- package/app/composables/useApiNavigation.ts +212 -0
- package/app/composables/useApiReferencePage.ts +164 -0
- package/app/composables/useApiSinglePage.ts +320 -0
- package/app/composables/useClipboardCopy.ts +56 -0
- package/app/composables/useHierarchyMode.ts +48 -0
- package/app/layouts/reference.vue +128 -0
- package/app/pages/api-reference/[...slug].vue +233 -0
- package/app/utils/api-document.ts +329 -0
- package/app/utils/mdc.ts +60 -0
- package/app/utils/navigation-tree.ts +28 -0
- package/bin/swizzle.mjs +256 -0
- package/content.config.ts +13 -0
- package/formatter.ts +77 -0
- package/generate.ts +91 -0
- package/modules/generate.ts +72 -0
- package/modules/prerender.ts +104 -0
- package/nuxt.config.ts +16 -0
- package/package.json +81 -4
- package/swizzle.manifest.mjs +84 -0
- package/swizzle.manifest.ts +11 -0
package/bin/swizzle.mjs
ADDED
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
import {
|
|
4
|
+
readFileSync,
|
|
5
|
+
writeFileSync,
|
|
6
|
+
mkdirSync,
|
|
7
|
+
existsSync,
|
|
8
|
+
realpathSync,
|
|
9
|
+
} from "node:fs";
|
|
10
|
+
import { dirname, join } from "node:path";
|
|
11
|
+
import { fileURLToPath } from "node:url";
|
|
12
|
+
import * as process from "node:process";
|
|
13
|
+
import { swizzleManifest } from "../swizzle.manifest.mjs";
|
|
14
|
+
|
|
15
|
+
// Parse arguments manually (simple approach without citty dependency)
|
|
16
|
+
export function parseArgs(argv) {
|
|
17
|
+
const flags = {};
|
|
18
|
+
|
|
19
|
+
for (let i = 0; i < argv.length; i++) {
|
|
20
|
+
if (!argv[i].startsWith("--")) {
|
|
21
|
+
continue;
|
|
22
|
+
}
|
|
23
|
+
const key = argv[i].substring(2);
|
|
24
|
+
if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
|
|
25
|
+
flags[key] = argv[i + 1];
|
|
26
|
+
i++;
|
|
27
|
+
} else {
|
|
28
|
+
flags[key] = true;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
// Normalize --yes to --force for compatibility
|
|
33
|
+
if (flags.yes) {
|
|
34
|
+
flags.force = true;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
return flags;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
// Resolve the @graphql-markdown/nuxt-theme package from the script's location
|
|
41
|
+
function resolvePackagePath() {
|
|
42
|
+
const scriptDir = dirname(fileURLToPath(import.meta.url));
|
|
43
|
+
const packagePath = dirname(scriptDir);
|
|
44
|
+
|
|
45
|
+
if (!existsSync(join(packagePath, "package.json"))) {
|
|
46
|
+
throw new Error(
|
|
47
|
+
`Could not find @graphql-markdown/nuxt-theme's package.json at ${packagePath} — this script's own location (bin/swizzle.mjs) should always be one level inside the package root. Is the package installation corrupted?`,
|
|
48
|
+
);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
return packagePath;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
// Get version from package.json
|
|
55
|
+
function getPackageVersion() {
|
|
56
|
+
try {
|
|
57
|
+
const packageJsonPath = join(resolvePackagePath(), "package.json");
|
|
58
|
+
const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
|
|
59
|
+
return pkg.version;
|
|
60
|
+
} catch {
|
|
61
|
+
return "unknown";
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
// Get comment syntax for file type
|
|
66
|
+
function getCommentSyntax(filepath) {
|
|
67
|
+
if (filepath.endsWith(".vue")) {
|
|
68
|
+
return "<!-- ";
|
|
69
|
+
}
|
|
70
|
+
if (filepath.endsWith(".ts") || filepath.endsWith(".js")) {
|
|
71
|
+
return "// ";
|
|
72
|
+
}
|
|
73
|
+
return "// ";
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
// Get comment close for file type
|
|
77
|
+
function getCommentClose(filepath) {
|
|
78
|
+
if (filepath.endsWith(".vue")) {
|
|
79
|
+
return " -->";
|
|
80
|
+
}
|
|
81
|
+
return "";
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
// Get version stamp comment
|
|
85
|
+
function getVersionStamp(filepath, version) {
|
|
86
|
+
const start = getCommentSyntax(filepath);
|
|
87
|
+
const close = getCommentClose(filepath);
|
|
88
|
+
return `${start}swizzled from @graphql-markdown/nuxt-theme@${version}${close}`;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
// Copy file with version stamp
|
|
92
|
+
function copyFileWithStamp(sourcePath, targetPath, version) {
|
|
93
|
+
const sourceContent = readFileSync(sourcePath, "utf-8");
|
|
94
|
+
const versionStamp = getVersionStamp(targetPath, version);
|
|
95
|
+
|
|
96
|
+
// Check if file already starts with a swizzle stamp
|
|
97
|
+
const lines = sourceContent.split("\n");
|
|
98
|
+
let contentToWrite;
|
|
99
|
+
|
|
100
|
+
if (lines[0]?.includes("swizzled from @graphql-markdown/nuxt-theme@")) {
|
|
101
|
+
// Replace existing stamp
|
|
102
|
+
contentToWrite = [versionStamp, ...lines.slice(1)].join("\n");
|
|
103
|
+
} else {
|
|
104
|
+
// Add new stamp
|
|
105
|
+
contentToWrite = `${versionStamp}\n${sourceContent}`;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
mkdirSync(dirname(targetPath), { recursive: true });
|
|
109
|
+
writeFileSync(targetPath, contentToWrite, "utf-8");
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
// Parse swizzle stamp from file
|
|
113
|
+
function parseSwizzleStamp(filepath) {
|
|
114
|
+
try {
|
|
115
|
+
const content = readFileSync(filepath, "utf-8");
|
|
116
|
+
const match =
|
|
117
|
+
/(?:<!--\s*)?swizzled from @graphql-markdown\/nuxt-theme@([^\s]+)(?:\s*-->)?/.exec(
|
|
118
|
+
content,
|
|
119
|
+
);
|
|
120
|
+
return match ? match[1] : null;
|
|
121
|
+
} catch {
|
|
122
|
+
return null;
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
// Warn about swizzled files whose stamp differs from the installed version
|
|
127
|
+
export function checkSwizzled(
|
|
128
|
+
consumerCwd,
|
|
129
|
+
currentVersion,
|
|
130
|
+
manifest = swizzleManifest,
|
|
131
|
+
) {
|
|
132
|
+
for (const entry of manifest) {
|
|
133
|
+
const targetPath = join(consumerCwd, entry.targetPath);
|
|
134
|
+
if (!existsSync(targetPath)) {
|
|
135
|
+
continue;
|
|
136
|
+
}
|
|
137
|
+
const stampedVersion = parseSwizzleStamp(targetPath);
|
|
138
|
+
if (stampedVersion && stampedVersion !== currentVersion) {
|
|
139
|
+
console.warn(
|
|
140
|
+
`${entry.id} was swizzled from ${stampedVersion}, currently installed: ${currentVersion} — review upstream changes.`,
|
|
141
|
+
);
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
// Pick the manifest entry from --component. Returns an exit code on failure.
|
|
147
|
+
export function findComponent(id, manifest = swizzleManifest) {
|
|
148
|
+
const entry = manifest.find((e) => e.id === id);
|
|
149
|
+
if (!entry) {
|
|
150
|
+
console.error(`Unknown component: ${id}`);
|
|
151
|
+
return { exitCode: 1 };
|
|
152
|
+
}
|
|
153
|
+
return { entry };
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
// Pick the manifest entry interactively (requires @clack/prompts).
|
|
157
|
+
export async function promptComponent(manifest = swizzleManifest) {
|
|
158
|
+
try {
|
|
159
|
+
const { select, isCancel } = await import("@clack/prompts");
|
|
160
|
+
|
|
161
|
+
const choice = await select({
|
|
162
|
+
message: "Which component would you like to swizzle?",
|
|
163
|
+
options: manifest.map((entry) => ({
|
|
164
|
+
value: entry.id,
|
|
165
|
+
label: `${entry.id} — ${entry.description}`,
|
|
166
|
+
})),
|
|
167
|
+
});
|
|
168
|
+
|
|
169
|
+
if (isCancel(choice)) {
|
|
170
|
+
return { exitCode: 0 };
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
return { entry: manifest.find((e) => e.id === choice) };
|
|
174
|
+
} catch {
|
|
175
|
+
console.error("Interactive mode requires @clack/prompts to be installed");
|
|
176
|
+
return { exitCode: 1 };
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
// Ask before overwriting an existing target. Returns an exit code to stop.
|
|
181
|
+
export async function confirmOverwrite(entry) {
|
|
182
|
+
try {
|
|
183
|
+
const { confirm, isCancel } = await import("@clack/prompts");
|
|
184
|
+
const shouldOverwrite = await confirm({
|
|
185
|
+
message: `${entry.id} already exists. Overwrite?`,
|
|
186
|
+
});
|
|
187
|
+
|
|
188
|
+
return isCancel(shouldOverwrite) || !shouldOverwrite ? 0 : undefined;
|
|
189
|
+
} catch {
|
|
190
|
+
console.error("Unable to confirm overwrite");
|
|
191
|
+
return 1;
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
// Run the CLI for the given flags. Returns the process exit code.
|
|
196
|
+
export async function run(flags, consumerCwd = process.cwd()) {
|
|
197
|
+
if (flags.list) {
|
|
198
|
+
console.log(JSON.stringify(swizzleManifest, null, 2));
|
|
199
|
+
return 0;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
if (flags.check) {
|
|
203
|
+
checkSwizzled(consumerCwd, getPackageVersion());
|
|
204
|
+
return 0;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
const selection = flags.component
|
|
208
|
+
? findComponent(flags.component)
|
|
209
|
+
: await promptComponent();
|
|
210
|
+
if (!selection.entry) {
|
|
211
|
+
return selection.exitCode;
|
|
212
|
+
}
|
|
213
|
+
const { entry } = selection;
|
|
214
|
+
|
|
215
|
+
const targetPath = join(consumerCwd, entry.targetPath);
|
|
216
|
+
|
|
217
|
+
if (existsSync(targetPath) && !flags.force) {
|
|
218
|
+
const stop = await confirmOverwrite(entry);
|
|
219
|
+
if (stop !== undefined) {
|
|
220
|
+
return stop;
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
copyFileWithStamp(
|
|
225
|
+
join(resolvePackagePath(), entry.sourcePath),
|
|
226
|
+
targetPath,
|
|
227
|
+
getPackageVersion(),
|
|
228
|
+
);
|
|
229
|
+
console.log(`✓ Swizzled ${entry.id} to ${targetPath}`);
|
|
230
|
+
return 0;
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
// Main CLI logic
|
|
234
|
+
export async function main(argv = process.argv.slice(2)) {
|
|
235
|
+
try {
|
|
236
|
+
process.exit(await run(parseArgs(argv)));
|
|
237
|
+
} catch (error) {
|
|
238
|
+
console.error("Error:", error.message);
|
|
239
|
+
process.exit(1);
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
// Only auto-run when executed directly (also through a bin symlink), not when imported
|
|
244
|
+
const isDirectRun =
|
|
245
|
+
process.argv[1] &&
|
|
246
|
+
realpathSync(process.argv[1]) ===
|
|
247
|
+
realpathSync(fileURLToPath(import.meta.url));
|
|
248
|
+
|
|
249
|
+
if (isDirectRun) {
|
|
250
|
+
try {
|
|
251
|
+
await main();
|
|
252
|
+
} catch (error) {
|
|
253
|
+
console.error("Fatal error:", error);
|
|
254
|
+
process.exit(1);
|
|
255
|
+
}
|
|
256
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
// content.config.ts
|
|
2
|
+
import { defineContentConfig, defineCollection } from "@nuxt/content";
|
|
3
|
+
|
|
4
|
+
export default defineContentConfig({
|
|
5
|
+
collections: {
|
|
6
|
+
// Registers the generated Markdown pages; the formatter emits `.md` so that
|
|
7
|
+
// Nuxt Content's search indexer picks them up.
|
|
8
|
+
content: defineCollection({
|
|
9
|
+
type: "page",
|
|
10
|
+
source: "api-reference/**/*.md",
|
|
11
|
+
}),
|
|
12
|
+
},
|
|
13
|
+
});
|
package/formatter.ts
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Formatter overrides handed to `graphql-markdown` (see `generate.ts`).
|
|
3
|
+
*
|
|
4
|
+
* The library loads this module by URL at generation time, so it is typed
|
|
5
|
+
* structurally: `@graphql-markdown/types` is not a direct dependency, and its
|
|
6
|
+
* `MDXString` return type is opaque and cannot be produced from here.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
interface Badge {
|
|
10
|
+
text: string;
|
|
11
|
+
classname?: string[] | string;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
interface Admonition {
|
|
15
|
+
icon?: string | null;
|
|
16
|
+
text: string;
|
|
17
|
+
title: string | null;
|
|
18
|
+
type: string;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** ` · ` instead of the default ` ● `, as text rather than a styled span. */
|
|
22
|
+
export const formatMDXBullet = (text = ""): string => {
|
|
23
|
+
return ` · ${text}`;
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
export const formatMDXBadge = ({ text }: Badge): string => {
|
|
27
|
+
const suffix = String(text).toLowerCase();
|
|
28
|
+
|
|
29
|
+
return `<mark class="gqlmd-mdx-badge gqlmd-mdx-badge-${suffix}">${text}</mark>`;
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
export const formatMDXAdmonition = ({
|
|
33
|
+
text,
|
|
34
|
+
title,
|
|
35
|
+
type,
|
|
36
|
+
}: Admonition): string => {
|
|
37
|
+
if (
|
|
38
|
+
type.toLowerCase() === "warning" &&
|
|
39
|
+
title?.toLowerCase() === "deprecated"
|
|
40
|
+
) {
|
|
41
|
+
return `<aside class="api-deprecation-callout not-prose mb-8"><span class="api-deprecated-badge">deprecated</span><span class="api-deprecation-message">${text.trim()}</span></aside>`;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
return `<fieldset class="gqlmd-mdx-admonition-fieldset"><legend class="gqlmd-mdx-admonition-legend"><span class="gqlmd-mdx-admonition-legend-type gqlmd-mdx-admonition-legend-type-${type.toLowerCase()}">${title}</span></legend><span>${text}</span></fieldset>`;
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Nuxt Content parses `.md` and `.mdx` alike, but its search indexer
|
|
49
|
+
* (`queryCollectionSearchSections`) only reads `extension = "md"` — so the
|
|
50
|
+
* generated pages have to be emitted as plain Markdown to be searchable.
|
|
51
|
+
*/
|
|
52
|
+
export const mdxExtension = ".md";
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Stamps a `kind` frontmatter field (the GraphQL entity kind being
|
|
56
|
+
* rendered — `objects`, `scalars`, `queries`, `directives`, etc.) onto every
|
|
57
|
+
* generated page, on top of the same `---`-delimited wrapping graphql-markdown's
|
|
58
|
+
* own default `formatMDXFrontmatter` produces (reimplemented inline rather
|
|
59
|
+
* than imported, since this file is loaded by URL at generation time and
|
|
60
|
+
* deliberately stays free of `@graphql-markdown/*` runtime dependencies).
|
|
61
|
+
*
|
|
62
|
+
* `useApiNavigation.ts` reads this field back to group the sidebar/landing
|
|
63
|
+
* grid by entity kind whenever a page has no folder segments left to group
|
|
64
|
+
* by — today, that's `printTypeOptions.hierarchy: "flat"`, which otherwise
|
|
65
|
+
* has nothing else to group on.
|
|
66
|
+
*/
|
|
67
|
+
export const formatMDXFrontmatter = (
|
|
68
|
+
_props: unknown,
|
|
69
|
+
formatted: string[] | null | undefined,
|
|
70
|
+
context?: { entity?: string | null },
|
|
71
|
+
): string => {
|
|
72
|
+
if (!formatted) return "";
|
|
73
|
+
const lines = context?.entity
|
|
74
|
+
? [...formatted, `kind: ${context.entity}`]
|
|
75
|
+
: formatted;
|
|
76
|
+
return ["---", ...lines, "---"].join("\n");
|
|
77
|
+
};
|
package/generate.ts
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
// generate.ts
|
|
2
|
+
import { useLogger } from "@nuxt/kit";
|
|
3
|
+
|
|
4
|
+
import { runGraphQLMarkdown } from "@graphql-markdown/cli";
|
|
5
|
+
import { DEFAULT_BASE_URL } from "./constants";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* `@graphql-markdown/types` is a transitive dependency, so the option shape is
|
|
9
|
+
* taken from the CLI's own signature rather than imported by package name.
|
|
10
|
+
*/
|
|
11
|
+
type GraphQLMarkdownOptions = Parameters<typeof runGraphQLMarkdown>[0];
|
|
12
|
+
|
|
13
|
+
/** Default loaders: GraphQL file loader. */
|
|
14
|
+
const DEFAULT_LOADERS = {
|
|
15
|
+
GraphQLFileLoader: "@graphql-tools/graphql-file-loader",
|
|
16
|
+
} as GraphQLMarkdownOptions["loaders"];
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* Factory for generating GraphQL Markdown documentation.
|
|
20
|
+
*
|
|
21
|
+
* Returns a function that, when called, generates the API reference documentation
|
|
22
|
+
* from a GraphQL schema. The returned function can be invoked during a Nuxt module's
|
|
23
|
+
* setup or from the consumer's own entry point (e.g., generate-docs.ts).
|
|
24
|
+
*
|
|
25
|
+
* @param userOptions - Configuration options for the generator:
|
|
26
|
+
* - schema: Path to the GraphQL schema file (required)
|
|
27
|
+
* - rootPath: Root directory for generated content (default: "./content")
|
|
28
|
+
* - baseURL: Base URL for the API reference (default: "api-reference")
|
|
29
|
+
* - printTypeOptions: Formatting options merged with defaults
|
|
30
|
+
* - decorators: Custom decorators for the schema output
|
|
31
|
+
* - formatter: Path/URL to custom formatter module (default: this package's formatter.ts)
|
|
32
|
+
* - loaders: Custom schema loaders (default: GraphQLFileLoader)
|
|
33
|
+
* @returns A function that generates the documentation when called
|
|
34
|
+
*/
|
|
35
|
+
export const createGenerateDocs = (userOptions: {
|
|
36
|
+
schema: string;
|
|
37
|
+
rootPath?: string;
|
|
38
|
+
baseURL?: string;
|
|
39
|
+
printTypeOptions?: Partial<GraphQLMarkdownOptions["printTypeOptions"]>;
|
|
40
|
+
decorators?: NonNullable<GraphQLMarkdownOptions["decorators"]>;
|
|
41
|
+
formatter?: string;
|
|
42
|
+
loaders?: NonNullable<GraphQLMarkdownOptions["loaders"]>;
|
|
43
|
+
}): (() => Promise<void>) => {
|
|
44
|
+
const {
|
|
45
|
+
schema,
|
|
46
|
+
rootPath = "./content",
|
|
47
|
+
baseURL = DEFAULT_BASE_URL,
|
|
48
|
+
printTypeOptions,
|
|
49
|
+
decorators,
|
|
50
|
+
formatter = new URL("./formatter.ts", import.meta.url).href,
|
|
51
|
+
loaders = DEFAULT_LOADERS,
|
|
52
|
+
} = userOptions;
|
|
53
|
+
|
|
54
|
+
const logger = useLogger("gqlmd-generate");
|
|
55
|
+
|
|
56
|
+
// Merge printTypeOptions with the layer's own defaults
|
|
57
|
+
const mergedPrintTypeOptions: GraphQLMarkdownOptions["printTypeOptions"] = {
|
|
58
|
+
parentTypePrefix: false,
|
|
59
|
+
typeBadges: true,
|
|
60
|
+
...printTypeOptions,
|
|
61
|
+
};
|
|
62
|
+
|
|
63
|
+
const options: GraphQLMarkdownOptions = {
|
|
64
|
+
// Core paths
|
|
65
|
+
schema,
|
|
66
|
+
rootPath,
|
|
67
|
+
baseURL,
|
|
68
|
+
linkRoot: "/",
|
|
69
|
+
formatter,
|
|
70
|
+
|
|
71
|
+
// Formatting fallback options to bypass the internal configuration setup
|
|
72
|
+
loaders,
|
|
73
|
+
|
|
74
|
+
// Layout extraction flags with defaults merged with user options
|
|
75
|
+
printTypeOptions: mergedPrintTypeOptions,
|
|
76
|
+
|
|
77
|
+
// Custom decorators, if provided
|
|
78
|
+
...(decorators && { decorators }),
|
|
79
|
+
};
|
|
80
|
+
|
|
81
|
+
return async () => {
|
|
82
|
+
try {
|
|
83
|
+
await runGraphQLMarkdown(options, {}, import.meta.resolve("consola"));
|
|
84
|
+
|
|
85
|
+
logger.info(`GraphQL Markdown generated in ${rootPath}/${baseURL}/`);
|
|
86
|
+
} catch (error) {
|
|
87
|
+
logger.error("Generation failed");
|
|
88
|
+
throw new Error("GraphQL Markdown generation failed", { cause: error });
|
|
89
|
+
}
|
|
90
|
+
};
|
|
91
|
+
};
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
import { resolve } from "node:path";
|
|
2
|
+
import { pathToFileURL } from "node:url";
|
|
3
|
+
import { defineNuxtModule, useNuxt } from "@nuxt/kit";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Generates GraphQL API documentation before \@nuxt/content indexes the
|
|
7
|
+
* content directory.
|
|
8
|
+
*
|
|
9
|
+
* The generation itself is an ordinary function call into the generator — the
|
|
10
|
+
* programmatic entry point the layer advertises, and consuming projects' own
|
|
11
|
+
* dogfooding of it. What has to be deliberate is *when* it runs.
|
|
12
|
+
*
|
|
13
|
+
* On a cold build (fresh clone, no generated files yet), a `build:before` hook
|
|
14
|
+
* is too late: \@nuxt/content parses the content directory during its own module
|
|
15
|
+
* setup, so the collection is indexed from a directory that does not exist yet
|
|
16
|
+
* and the generated pages 404. It only appears to work once a previous run has
|
|
17
|
+
* left the files behind.
|
|
18
|
+
*
|
|
19
|
+
* FIX: run generation directly in this module's own `setup()`, awaited, and
|
|
20
|
+
* list this module before `@nuxt/content` in the layer's `nuxt.config.ts`
|
|
21
|
+
* `modules` array. Nuxt's `installModules` (in \@nuxt/kit) installs modules
|
|
22
|
+
* sequentially in a plain `for...of` loop with `await` on each one — verified
|
|
23
|
+
* by reading `installModules`' source directly (node_modules/\@nuxt/kit/dist/
|
|
24
|
+
* index.mjs) — so a module earlier in the resolved list is fully installed,
|
|
25
|
+
* setup() included, before the next one starts. Layer modules are also
|
|
26
|
+
* confirmed to resolve before the consuming app's own modules: `resolveModules`
|
|
27
|
+
* (in the `nuxt` package) builds the modules Map from
|
|
28
|
+
* `nuxt.options._layers.map(l => l.config).reverse()`, so an extended layer's
|
|
29
|
+
* config (later in `_layers`) is processed first and its modules land earlier
|
|
30
|
+
* in the Map's insertion order, which `installModules` then honors.
|
|
31
|
+
*
|
|
32
|
+
* An earlier version of this module tried registering a
|
|
33
|
+
* `nuxt.hook("modules:before", ...)` listener instead, reasoning that hook
|
|
34
|
+
* fires "before any module's setup". That is true, but backwards for a module
|
|
35
|
+
* trying to listen for it FROM one of its own setup() calls: `modules:before` is called once,
|
|
36
|
+
* before `resolveModules`/`installModules` even run — so by the time this
|
|
37
|
+
* module's own `setup()` executes (which is inside `installModules`), the
|
|
38
|
+
* `modules:before` hook has already fired and the listener registered here
|
|
39
|
+
* would never run. This was caught by actually running the fixture's cold
|
|
40
|
+
* build and finding `content/` was never created — the hook design looked
|
|
41
|
+
* more "correct" on paper but was empirically wrong; the plain direct-call
|
|
42
|
+
* design below is what `graphql-markdown-docs/modules/demo.ts` (the reference
|
|
43
|
+
* implementation this was adapted from) actually does, and it works.
|
|
44
|
+
*
|
|
45
|
+
* A consuming project provides a `generate-docs.ts` export at its root (or a
|
|
46
|
+
* custom path via `nuxt.config.ts`'s `gqlmdGenerate.entry` option) with a
|
|
47
|
+
* `generate()` function. This module invokes it at the right time in the
|
|
48
|
+
* lifecycle.
|
|
49
|
+
*/
|
|
50
|
+
export default defineNuxtModule<{ entry?: string }>({
|
|
51
|
+
meta: { name: "gqlmd-generate", configKey: "gqlmdGenerate" },
|
|
52
|
+
defaults: { entry: "./generate-docs.ts" },
|
|
53
|
+
async setup(options) {
|
|
54
|
+
const nuxt = useNuxt();
|
|
55
|
+
const entryPath = resolve(nuxt.options.rootDir, options.entry!);
|
|
56
|
+
|
|
57
|
+
// Editing generate-docs.ts itself restarts the dev server and
|
|
58
|
+
// regenerates. This module has no way to know which schema file(s) the
|
|
59
|
+
// consumer's generate-docs.ts points at, so it cannot watch those too —
|
|
60
|
+
// a consumer whose workflow depends on schema-file-triggered restarts
|
|
61
|
+
// still needs their own `watch` entry for it, same as before this
|
|
62
|
+
// module existed.
|
|
63
|
+
nuxt.options.watch.push(entryPath);
|
|
64
|
+
|
|
65
|
+
// Verified in T5's fixture cold-build test: plain dynamic import() of a
|
|
66
|
+
// .ts file works here because nuxi's own process bootstraps through
|
|
67
|
+
// jiti, which installs Node loader hooks for the whole process — not
|
|
68
|
+
// something this module sets up itself.
|
|
69
|
+
const { generate } = await import(pathToFileURL(entryPath).href);
|
|
70
|
+
await generate();
|
|
71
|
+
},
|
|
72
|
+
});
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
import { readdir } from "node:fs/promises";
|
|
2
|
+
import { join, relative, sep } from "node:path";
|
|
3
|
+
|
|
4
|
+
import { defineNuxtModule, useNuxt } from "@nuxt/kit";
|
|
5
|
+
import { DEFAULT_BASE_URL } from "../constants";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Enumerates every generated content route for the prerenderer.
|
|
9
|
+
*
|
|
10
|
+
* Nitro's `crawlLinks` only reaches a page if something links to it. The
|
|
11
|
+
* reference layout uses `UContentNavigation` with collapsible sections, so
|
|
12
|
+
* nested pages never appear in the server-rendered HTML the crawler reads.
|
|
13
|
+
* Relying on crawlLinks alone silently drops most nested API pages — the site
|
|
14
|
+
* generates successfully but serves 404s for entire branches of the reference.
|
|
15
|
+
*
|
|
16
|
+
* This module walks the generated content directory and extracts all routes
|
|
17
|
+
* directly, registering them with Nitro's prerenderer to ensure nothing gets
|
|
18
|
+
* missed.
|
|
19
|
+
*
|
|
20
|
+
* The mapping from file to route is the same one \@nuxt/content applies, so the
|
|
21
|
+
* directory can be walked directly rather than queried:
|
|
22
|
+
*
|
|
23
|
+
* content/api-reference/queries/user.md -\> /api-reference/queries/user
|
|
24
|
+
* content/api-reference/types/objects/user.md -\> /api-reference/types/objects/user
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
export const walk = async (dir: string): Promise<string[]> => {
|
|
28
|
+
const out: string[] = [];
|
|
29
|
+
try {
|
|
30
|
+
for (const entry of await readdir(dir, { withFileTypes: true })) {
|
|
31
|
+
if (entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
|
|
32
|
+
const full = join(dir, entry.name);
|
|
33
|
+
if (entry.isDirectory()) {
|
|
34
|
+
out.push(...(await walk(full))); // NOSONAR sequential recursive walk keeps route order deterministic
|
|
35
|
+
} else if (entry.name.endsWith(".md")) {
|
|
36
|
+
out.push(full);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
} catch {
|
|
40
|
+
// Directory does not exist yet; that's ok.
|
|
41
|
+
}
|
|
42
|
+
return out;
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Maps a content file path to its final route.
|
|
47
|
+
* Special case: any `.../generated.md` becomes the route for its own
|
|
48
|
+
* directory — `content/api-reference/generated.md` -\> `/api-reference`, and
|
|
49
|
+
* for a multi-schema namespace, `content/api-reference/schema-a/generated.md`
|
|
50
|
+
* -\> `/api-reference/schema-a`, with no assumption about how many segments
|
|
51
|
+
* precede `generated`. "generated" is only ever emitted once per
|
|
52
|
+
* `createGenerateDocs` call, at that call's own baseURL root, so "drop the
|
|
53
|
+
* trailing `generated` segment" is correct regardless of nesting depth — a
|
|
54
|
+
* strict generalization of the old exactly-2-segments check, which is why
|
|
55
|
+
* the existing single-schema fixture test still passes unmodified against
|
|
56
|
+
* this version.
|
|
57
|
+
*/
|
|
58
|
+
export const routeFor = (
|
|
59
|
+
contentDir: string,
|
|
60
|
+
file: string,
|
|
61
|
+
): string | undefined => {
|
|
62
|
+
const relativePath = relative(contentDir, file);
|
|
63
|
+
const segments = relativePath.replace(/\.md$/, "").split(sep);
|
|
64
|
+
|
|
65
|
+
if (segments.at(-1) === "generated") {
|
|
66
|
+
return `/${segments.slice(0, -1).join("/")}`;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
// All other pages: map directly
|
|
70
|
+
return `/${segments.join("/")}`;
|
|
71
|
+
};
|
|
72
|
+
|
|
73
|
+
export default defineNuxtModule({
|
|
74
|
+
meta: {
|
|
75
|
+
name: "gqlmd-prerender",
|
|
76
|
+
},
|
|
77
|
+
setup() {
|
|
78
|
+
const nuxt = useNuxt();
|
|
79
|
+
|
|
80
|
+
nuxt.hook("nitro:init", (nitro) => {
|
|
81
|
+
nitro.hooks.hook("prerender:routes", async (routes) => {
|
|
82
|
+
// The content root where generated markdown lives
|
|
83
|
+
const contentRoot = join(nuxt.options.rootDir, "content");
|
|
84
|
+
|
|
85
|
+
for (const file of await walk(contentRoot)) {
|
|
86
|
+
const route = routeFor(contentRoot, file);
|
|
87
|
+
if (route) routes.add(route);
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
// The bare shared-prefix root (e.g. `/api-reference`) has no backing
|
|
91
|
+
// content file when every schema is generated under a nested baseURL
|
|
92
|
+
// (a multi-schema setup) — [...slug].vue's namespace-selector
|
|
93
|
+
// fallback still needs to be reachable there. A no-op/duplicate add
|
|
94
|
+
// for the default single-schema case, since that route is already
|
|
95
|
+
// registered by the walk above via its own `generated.md`.
|
|
96
|
+
const appConfig = nuxt.options.appConfig as {
|
|
97
|
+
gqlmd?: { baseURL?: string };
|
|
98
|
+
};
|
|
99
|
+
const baseURL = appConfig.gqlmd?.baseURL ?? DEFAULT_BASE_URL;
|
|
100
|
+
routes.add(`/${baseURL}`);
|
|
101
|
+
});
|
|
102
|
+
});
|
|
103
|
+
},
|
|
104
|
+
});
|
package/nuxt.config.ts
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { fileURLToPath } from "node:url";
|
|
2
|
+
import { join } from "node:path";
|
|
3
|
+
import { defineNuxtConfig } from "nuxt/config";
|
|
4
|
+
|
|
5
|
+
const layerDir = fileURLToPath(new URL(".", import.meta.url));
|
|
6
|
+
|
|
7
|
+
export default defineNuxtConfig({
|
|
8
|
+
modules: [
|
|
9
|
+
join(layerDir, "modules/generate"),
|
|
10
|
+
"@nuxt/content",
|
|
11
|
+
"@nuxt/ui",
|
|
12
|
+
join(layerDir, "modules/prerender"),
|
|
13
|
+
],
|
|
14
|
+
css: [join(layerDir, "app/assets/css/main.css")],
|
|
15
|
+
content: {},
|
|
16
|
+
});
|