@graphql-markdown/nuxt-theme 0.0.0-stage → 0.1.1

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 (35) hide show
  1. package/README.md +196 -2
  2. package/app/app-config.d.ts +15 -0
  3. package/app/app.config.ts +22 -0
  4. package/app/assets/css/main.css +85 -0
  5. package/app/components/ApiCodeColumn.vue +53 -0
  6. package/app/components/ApiDocumentContent.vue +45 -0
  7. package/app/components/ApiNamespaceLanding.vue +29 -0
  8. package/app/components/ApiOverviewGrid.vue +38 -0
  9. package/app/components/ApiSinglePageEntry.vue +75 -0
  10. package/app/components/ApiSinglePageSection.vue +32 -0
  11. package/app/components/SchemaCodeCard.vue +68 -0
  12. package/app/components/SiteFooter.vue +13 -0
  13. package/app/components/SiteHeader.vue +31 -0
  14. package/app/composables/useApiCodeCards.ts +96 -0
  15. package/app/composables/useApiDocument.ts +69 -0
  16. package/app/composables/useApiNavigation.ts +212 -0
  17. package/app/composables/useApiReferencePage.ts +164 -0
  18. package/app/composables/useApiSinglePage.ts +320 -0
  19. package/app/composables/useClipboardCopy.ts +56 -0
  20. package/app/composables/useHierarchyMode.ts +48 -0
  21. package/app/layouts/reference.vue +128 -0
  22. package/app/pages/api-reference/[...slug].vue +233 -0
  23. package/app/utils/api-document.ts +329 -0
  24. package/app/utils/mdc.ts +60 -0
  25. package/app/utils/navigation-tree.ts +28 -0
  26. package/bin/swizzle.mjs +256 -0
  27. package/content.config.ts +13 -0
  28. package/formatter.ts +77 -0
  29. package/generate.ts +91 -0
  30. package/modules/generate.ts +72 -0
  31. package/modules/prerender.ts +104 -0
  32. package/nuxt.config.ts +16 -0
  33. package/package.json +81 -4
  34. package/swizzle.manifest.mjs +84 -0
  35. package/swizzle.manifest.ts +11 -0
@@ -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 `&nbsp;·&nbsp;${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
+ });