create-graphql-markdown-docs 0.1.0 → 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.
- package/README.md +100 -26
- package/lib/create.mjs +495 -670
- package/lib/frameworks/docusaurus.mjs +66 -0
- package/lib/frameworks/index.mjs +53 -0
- package/lib/frameworks/links.mjs +102 -0
- package/lib/frameworks/nuxt.mjs +266 -0
- package/lib/frameworks/presets.mjs +133 -0
- package/lib/helpers.mjs +83 -0
- package/lib/project.mjs +136 -0
- package/lib/rewrites/graphqlrc.mjs +61 -0
- package/lib/rewrites/lines.mjs +18 -0
- package/lib/schema.mjs +102 -0
- package/lib/target.mjs +95 -0
- package/lib/tasks.mjs +154 -0
- package/lib/wire/deps.mjs +38 -0
- package/lib/wire/plan.mjs +241 -0
- package/lib/wire/steps.mjs +333 -0
- package/lib/wire/yaml.mjs +93 -0
- package/package.json +2 -2
- package/templates/docusaurus/gitignore +20 -0
- package/templates/docusaurus/package.json +1 -1
- package/templates/nuxt/gitignore +30 -0
- package/templates/nuxt/package.json +1 -1
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
|
|
4
|
+
import { writeGraphqlrc } from "../rewrites/graphqlrc.mjs";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Rewrite the Docusaurus template's docusaurus.config.js site title.
|
|
8
|
+
*/
|
|
9
|
+
export function writeDocusaurusConfig(tempDir, titleOverride) {
|
|
10
|
+
if (!titleOverride) {
|
|
11
|
+
return; // No changes needed
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
const configPath = path.join(tempDir, "docusaurus.config.js");
|
|
15
|
+
const originalContent = fs.readFileSync(configPath, "utf-8");
|
|
16
|
+
const searchString = 'title: "My API",';
|
|
17
|
+
const navbarSearchString = 'title: "GraphQL-Markdown",';
|
|
18
|
+
|
|
19
|
+
// A replacement identical to the original (e.g. the title is already
|
|
20
|
+
// "My API") is fine; only a missing search string means template drift.
|
|
21
|
+
if (!originalContent.includes(searchString)) {
|
|
22
|
+
throw new Error(
|
|
23
|
+
`Expected to find and replace '${searchString}' in ${configPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
|
|
24
|
+
);
|
|
25
|
+
}
|
|
26
|
+
if (!originalContent.includes(navbarSearchString)) {
|
|
27
|
+
throw new Error(
|
|
28
|
+
`Expected to find and replace 'title: "GraphQL-Markdown",' in ${configPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
|
|
29
|
+
);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
const updated = originalContent
|
|
33
|
+
.replace(searchString, () => `title: ${JSON.stringify(titleOverride)},`)
|
|
34
|
+
.replace(
|
|
35
|
+
navbarSearchString,
|
|
36
|
+
() => `title: ${JSON.stringify(titleOverride)},`,
|
|
37
|
+
);
|
|
38
|
+
|
|
39
|
+
fs.writeFileSync(configPath, updated);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Docusaurus scaffold descriptor (templates/docusaurus). */
|
|
43
|
+
export const docusaurus = {
|
|
44
|
+
id: "docusaurus",
|
|
45
|
+
name: "Docusaurus",
|
|
46
|
+
label: "Docusaurus",
|
|
47
|
+
hint: "React + MDX, classic docs site",
|
|
48
|
+
formatter: "@graphql-markdown/formatters/docusaurus",
|
|
49
|
+
detect: ["@docusaurus/core"],
|
|
50
|
+
links: "router",
|
|
51
|
+
contentRoot: "docs",
|
|
52
|
+
contentRoute: "/docs",
|
|
53
|
+
outputHint: "Docusaurus reads content from docs/",
|
|
54
|
+
nextSteps: ({ outputDir }) =>
|
|
55
|
+
`Add the API docs to a sidebar (e.g. autogenerated from \`${outputDir}\`), or use the @graphql-markdown/docusaurus plugin — add it to \`plugins\` in docusaurus.config.*, it reads the same .graphqlrc.`,
|
|
56
|
+
scaffold: {
|
|
57
|
+
runScripts: ["doc", "start"],
|
|
58
|
+
copyExcludes: [],
|
|
59
|
+
supportsColor: false,
|
|
60
|
+
// The Docusaurus README already documents editing .graphqlrc generically.
|
|
61
|
+
apply(tempDir, { schemaRef, loader, title }) {
|
|
62
|
+
writeDocusaurusConfig(tempDir, title);
|
|
63
|
+
writeGraphqlrc(tempDir, schemaRef, loader);
|
|
64
|
+
},
|
|
65
|
+
},
|
|
66
|
+
};
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import { docusaurus } from "./docusaurus.mjs";
|
|
2
|
+
import { nuxt } from "./nuxt.mjs";
|
|
3
|
+
import {
|
|
4
|
+
docfx,
|
|
5
|
+
fumadocs,
|
|
6
|
+
generic,
|
|
7
|
+
honkit,
|
|
8
|
+
hugo,
|
|
9
|
+
mdbook,
|
|
10
|
+
mkdocs,
|
|
11
|
+
starlight,
|
|
12
|
+
vocs,
|
|
13
|
+
} from "./presets.mjs";
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* @typedef {object} FrameworkDescriptor
|
|
17
|
+
* @property {string} id
|
|
18
|
+
* @property {string} name
|
|
19
|
+
* @property {string} label
|
|
20
|
+
* @property {string} [hint]
|
|
21
|
+
* @property {string} [formatter]
|
|
22
|
+
* @property {string} [createCommand]
|
|
23
|
+
* @property {string[]} [detect]
|
|
24
|
+
* @property {string} [outputHint]
|
|
25
|
+
* @property {"relative" | "router" | "absolute"} [links]
|
|
26
|
+
* @property {string} [contentRoot]
|
|
27
|
+
* @property {string} [contentRoute]
|
|
28
|
+
* @property {(ctx: { outputDir: string, route?: string }) => string} nextSteps
|
|
29
|
+
* @property {object} [scaffold]
|
|
30
|
+
*/
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Supported scaffold targets; each key maps to `templates/<framework>`.
|
|
34
|
+
* `scaffold.runScripts` are the package scripts to run after install, in order.
|
|
35
|
+
*/
|
|
36
|
+
export const FRAMEWORKS = { nuxt, docusaurus };
|
|
37
|
+
|
|
38
|
+
/** Every framework descriptor available in wire mode, keyed by id. */
|
|
39
|
+
export const WIRE_FRAMEWORKS = {
|
|
40
|
+
docusaurus,
|
|
41
|
+
starlight,
|
|
42
|
+
fumadocs,
|
|
43
|
+
vocs,
|
|
44
|
+
honkit,
|
|
45
|
+
hugo,
|
|
46
|
+
mkdocs,
|
|
47
|
+
docfx,
|
|
48
|
+
mdbook,
|
|
49
|
+
nuxt,
|
|
50
|
+
generic,
|
|
51
|
+
};
|
|
52
|
+
|
|
53
|
+
export const DEFAULT_FRAMEWORK = "nuxt";
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
import path from "node:path";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Normalize an output folder: forward slashes, no leading "./", no trailing "/".
|
|
5
|
+
* @param {string} output
|
|
6
|
+
* @returns {string}
|
|
7
|
+
*/
|
|
8
|
+
export function normalizeOutput(output) {
|
|
9
|
+
const normalized = output.replaceAll("\\", "/").replace(/^\.\//, "");
|
|
10
|
+
let end = normalized.length;
|
|
11
|
+
while (end > 0 && normalized[end - 1] === "/") {
|
|
12
|
+
end--;
|
|
13
|
+
}
|
|
14
|
+
return normalized.slice(0, end);
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Join URL segments into a route with a leading "/" and no trailing "/" (except "/").
|
|
19
|
+
* @param {...string} parts
|
|
20
|
+
* @returns {string}
|
|
21
|
+
*/
|
|
22
|
+
export function joinRoute(...parts) {
|
|
23
|
+
const joined = `/${parts.join("/")}`.replace(/\/+/g, "/");
|
|
24
|
+
return joined.length > 1 ? joined.replace(/\/$/, "") : joined;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Split an output folder into the content root path and the base URL segment.
|
|
29
|
+
* When the output IS the content root, the baseURL is "." because a non-"."
|
|
30
|
+
* value would add an extra URL segment.
|
|
31
|
+
* @param {{ contentRoot?: string }} descriptor
|
|
32
|
+
* @param {string} output
|
|
33
|
+
* @returns {{ rootPath: string, baseURL: string }}
|
|
34
|
+
*/
|
|
35
|
+
export function splitOutput(descriptor, output) {
|
|
36
|
+
const out = normalizeOutput(output);
|
|
37
|
+
if (descriptor.contentRoot && out === descriptor.contentRoot) {
|
|
38
|
+
return { rootPath: out, baseURL: "." };
|
|
39
|
+
}
|
|
40
|
+
return {
|
|
41
|
+
rootPath: path.posix.dirname(out),
|
|
42
|
+
baseURL: path.posix.basename(out),
|
|
43
|
+
};
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function getOutputRest(root, output) {
|
|
47
|
+
if (root === ".") {
|
|
48
|
+
return `/${output}`;
|
|
49
|
+
}
|
|
50
|
+
if (output === root) {
|
|
51
|
+
return "";
|
|
52
|
+
}
|
|
53
|
+
if (!output.startsWith(`${root}/`)) {
|
|
54
|
+
return undefined;
|
|
55
|
+
}
|
|
56
|
+
return output.slice(root.length);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function getOutputRoute(outputRoute, baseURL) {
|
|
60
|
+
return baseURL === "."
|
|
61
|
+
? outputRoute
|
|
62
|
+
: joinRoute(path.posix.dirname(outputRoute));
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Suggest a link root for router/absolute link frameworks, or undefined.
|
|
67
|
+
* @param {{ links?: string, contentRoot?: string, contentRoute?: string }} descriptor
|
|
68
|
+
* @param {string} output
|
|
69
|
+
* @param {{ siteBase?: string }} [options]
|
|
70
|
+
* @returns {string | undefined}
|
|
71
|
+
*/
|
|
72
|
+
export function suggestLinkRoot(descriptor, output, { siteBase = "/" } = {}) {
|
|
73
|
+
if (descriptor.links !== "router" && descriptor.links !== "absolute") {
|
|
74
|
+
return undefined;
|
|
75
|
+
}
|
|
76
|
+
if (!descriptor.contentRoot) {
|
|
77
|
+
return undefined;
|
|
78
|
+
}
|
|
79
|
+
const out = normalizeOutput(output);
|
|
80
|
+
const rest = getOutputRest(descriptor.contentRoot, out);
|
|
81
|
+
if (rest === undefined) {
|
|
82
|
+
return undefined;
|
|
83
|
+
}
|
|
84
|
+
const outputRoute = joinRoute(descriptor.contentRoute ?? "/", rest);
|
|
85
|
+
const { baseURL } = splitOutput(descriptor, out);
|
|
86
|
+
const route = getOutputRoute(outputRoute, baseURL);
|
|
87
|
+
return descriptor.links === "absolute" ? joinRoute(siteBase, route) : route;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* Resolve rootPath, baseURL and linkRoot for an output folder in one call.
|
|
92
|
+
* @param {object} descriptor
|
|
93
|
+
* @param {string} output
|
|
94
|
+
* @param {{ siteBase?: string }} [options]
|
|
95
|
+
* @returns {{ rootPath: string, baseURL: string, linkRoot: string | undefined }}
|
|
96
|
+
*/
|
|
97
|
+
export function resolveLinkWiring(descriptor, output, options) {
|
|
98
|
+
return {
|
|
99
|
+
...splitOutput(descriptor, output),
|
|
100
|
+
linkRoot: suggestLinkRoot(descriptor, output, options),
|
|
101
|
+
};
|
|
102
|
+
}
|
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
|
|
4
|
+
import {
|
|
5
|
+
EXAMPLE_SCHEMA_REF,
|
|
6
|
+
defaultSchemaLine,
|
|
7
|
+
isRemoteSchemaSource,
|
|
8
|
+
} from "../schema.mjs";
|
|
9
|
+
import { findIndentedLine } from "../rewrites/lines.mjs";
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Rewrite app.config.ts with custom title and/or color overrides.
|
|
13
|
+
*/
|
|
14
|
+
export function writeAppConfig(tempDir, titleOverride, colorOverride) {
|
|
15
|
+
if (!titleOverride && !colorOverride) {
|
|
16
|
+
return; // No changes needed
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
const appConfigPath = path.join(tempDir, "app", "app.config.ts");
|
|
20
|
+
let appConfig = fs.readFileSync(appConfigPath, "utf-8");
|
|
21
|
+
const originalContent = appConfig;
|
|
22
|
+
|
|
23
|
+
if (titleOverride) {
|
|
24
|
+
const searchString = "siteTitle: 'My API'";
|
|
25
|
+
|
|
26
|
+
// A replacement identical to the original (e.g. the title is already
|
|
27
|
+
// "My API") is fine; only a missing search string means template drift.
|
|
28
|
+
if (!originalContent.includes(searchString)) {
|
|
29
|
+
throw new Error(
|
|
30
|
+
`Expected to find and replace "${searchString}" in ${appConfigPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
|
|
31
|
+
);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
appConfig = appConfig.replace(
|
|
35
|
+
searchString,
|
|
36
|
+
() => `siteTitle: ${JSON.stringify(titleOverride)}`,
|
|
37
|
+
);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
if (colorOverride) {
|
|
41
|
+
// The template ships no `ui.colors` block at all (the layer's own
|
|
42
|
+
// violet/zinc defaults apply via `extends` until overridden) — add
|
|
43
|
+
// one rather than trying to replace a value that isn't there.
|
|
44
|
+
const beforeColorOverride = appConfig;
|
|
45
|
+
const searchString = "export default defineAppConfig({";
|
|
46
|
+
appConfig = appConfig.replace(
|
|
47
|
+
searchString,
|
|
48
|
+
() =>
|
|
49
|
+
`${searchString}\n ui: {\n colors: {\n primary: ${JSON.stringify(colorOverride)},\n },\n },`,
|
|
50
|
+
);
|
|
51
|
+
if (appConfig === beforeColorOverride) {
|
|
52
|
+
throw new Error(
|
|
53
|
+
`Expected to find and replace "${searchString}" in ${appConfigPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
|
|
54
|
+
);
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
fs.writeFileSync(appConfigPath, appConfig);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** Single-quoted JS/TS string literal with backslashes, quotes and newlines escaped. */
|
|
62
|
+
function toSingleQuotedLiteral(value) {
|
|
63
|
+
const escaped = value
|
|
64
|
+
.replace(/[\\']/g, (c) => `\\${c}`)
|
|
65
|
+
.replaceAll("\n", String.raw`\n`)
|
|
66
|
+
.replaceAll("\r", String.raw`\r`);
|
|
67
|
+
return `'${escaped}'`;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Rewrite generate-docs.ts to use the resolved schema path and loader.
|
|
72
|
+
*/
|
|
73
|
+
export function writeGenerateDocs(tempDir, schemaRef, loader) {
|
|
74
|
+
const generateDocsPath = path.join(tempDir, "generate-docs.ts");
|
|
75
|
+
const originalContent = fs.readFileSync(generateDocsPath, "utf-8");
|
|
76
|
+
|
|
77
|
+
// The default (bundled example, GraphQLFileLoader) needs no `loaders` option
|
|
78
|
+
// at all — createGenerateDocs already defaults to it — so only inject
|
|
79
|
+
// one when the detected loader differs.
|
|
80
|
+
const defaultSchema = `${defaultSchemaLine},`;
|
|
81
|
+
const schemaLiteral = toSingleQuotedLiteral(schemaRef);
|
|
82
|
+
const packageLiteral = toSingleQuotedLiteral(loader.package);
|
|
83
|
+
// Loaders needing an API token get it as a loadSchema option through
|
|
84
|
+
// the `{ module, options }` form of the loader entry.
|
|
85
|
+
const loaderEntry = loader.tokenEnvVar
|
|
86
|
+
? `{ module: ${packageLiteral}, options: { token: process.env.${loader.tokenEnvVar} } }`
|
|
87
|
+
: packageLiteral;
|
|
88
|
+
const replacementLines = loader.isDefault
|
|
89
|
+
? [`schema: ${schemaLiteral},`]
|
|
90
|
+
: [
|
|
91
|
+
`schema: ${schemaLiteral},`,
|
|
92
|
+
`loaders: { ${loader.className}: ${loaderEntry} },`,
|
|
93
|
+
];
|
|
94
|
+
|
|
95
|
+
// Only require a match when a change is expected (the default needs none).
|
|
96
|
+
const found = findIndentedLine(originalContent, defaultSchema);
|
|
97
|
+
if (!found) {
|
|
98
|
+
if (replacementLines.join("\n") === defaultSchema) return;
|
|
99
|
+
throw new Error(
|
|
100
|
+
`Expected to find and replace "${defaultSchema}" in ${generateDocsPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
|
|
101
|
+
);
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
const { line, indent } = found;
|
|
105
|
+
const updated = originalContent.replace(line, () =>
|
|
106
|
+
replacementLines.map((entry) => indent + entry).join("\n"),
|
|
107
|
+
);
|
|
108
|
+
|
|
109
|
+
fs.writeFileSync(generateDocsPath, updated);
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* Removes the layer's `watch: [...]` block (and its leading comment) using
|
|
114
|
+
* linear string scanning, replacing it with a single newline. Returns the
|
|
115
|
+
* input unchanged when the block isn't found.
|
|
116
|
+
*/
|
|
117
|
+
export function removeWatchBlock(content) {
|
|
118
|
+
const marker = "// The layer's gqlmd-generate module";
|
|
119
|
+
const markerIdx = content.indexOf(marker);
|
|
120
|
+
if (markerIdx === -1) return content;
|
|
121
|
+
const watchIdx = content.indexOf("watch: [", markerIdx);
|
|
122
|
+
if (watchIdx === -1) return content;
|
|
123
|
+
const lineStart = content.lastIndexOf("\n", watchIdx);
|
|
124
|
+
if (lineStart < markerIdx || content.slice(lineStart + 1, watchIdx).trim()) {
|
|
125
|
+
return content;
|
|
126
|
+
}
|
|
127
|
+
const closeIdx = content.indexOf("]", watchIdx);
|
|
128
|
+
if (closeIdx === -1 || !content.startsWith(",\n", closeIdx + 1)) {
|
|
129
|
+
return content;
|
|
130
|
+
}
|
|
131
|
+
let start = markerIdx;
|
|
132
|
+
while (start > 0 && /\s/.test(content[start - 1])) start--;
|
|
133
|
+
return `${content.slice(0, start)}\n${content.slice(closeIdx + 3)}`;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* Rewrite nuxt.config.ts's `watch` entry and/or schema filename to match the resolved schema.
|
|
138
|
+
*/
|
|
139
|
+
export function writeNuxtConfig(tempDir, schemaRef, isRemoteSource) {
|
|
140
|
+
const nuxtConfigPath = path.join(tempDir, "nuxt.config.ts");
|
|
141
|
+
const originalContent = fs.readFileSync(nuxtConfigPath, "utf-8");
|
|
142
|
+
|
|
143
|
+
let updated = originalContent;
|
|
144
|
+
|
|
145
|
+
if (isRemoteSource) {
|
|
146
|
+
// A remote schema source (URL/git/github) has no local file to watch at all —
|
|
147
|
+
// dev-server restarts on schema change simply aren't available for those,
|
|
148
|
+
// so the entry is dropped rather than left pointing at a path that no longer
|
|
149
|
+
// means anything.
|
|
150
|
+
const beforeWatchRemoval = updated;
|
|
151
|
+
updated = removeWatchBlock(updated);
|
|
152
|
+
|
|
153
|
+
if (updated === beforeWatchRemoval) {
|
|
154
|
+
throw new Error(
|
|
155
|
+
`Expected to find and replace the watch block in ${nuxtConfigPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
|
|
156
|
+
);
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
const beforeImportRemoval = updated;
|
|
160
|
+
updated = updated.replace(
|
|
161
|
+
'import { fileURLToPath } from "node:url";\n\n',
|
|
162
|
+
"",
|
|
163
|
+
);
|
|
164
|
+
|
|
165
|
+
if (updated === beforeImportRemoval) {
|
|
166
|
+
throw new Error(
|
|
167
|
+
`Expected to find and replace the fileURLToPath import in ${nuxtConfigPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
|
|
168
|
+
);
|
|
169
|
+
}
|
|
170
|
+
} else {
|
|
171
|
+
// Local schema: replace the example filename with the actual one.
|
|
172
|
+
// Only validate if we expect a change (schemaRef differs from the default).
|
|
173
|
+
const beforeSchemaReplace = updated;
|
|
174
|
+
updated = updated.replace(EXAMPLE_SCHEMA_REF, () => schemaRef);
|
|
175
|
+
|
|
176
|
+
if (schemaRef !== EXAMPLE_SCHEMA_REF && updated === beforeSchemaReplace) {
|
|
177
|
+
throw new Error(
|
|
178
|
+
`Expected to find and replace "${EXAMPLE_SCHEMA_REF}" in ${nuxtConfigPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
|
|
179
|
+
);
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
fs.writeFileSync(nuxtConfigPath, updated);
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* Rewrite README.md's schema section to document the actual schema source.
|
|
188
|
+
*/
|
|
189
|
+
export function writeReadme(tempDir, schemaPath, schemaRef, loader) {
|
|
190
|
+
if (!schemaPath) {
|
|
191
|
+
return; // No custom schema, keep the template's instructions
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
const readmePath = path.join(tempDir, "README.md");
|
|
195
|
+
const originalContent = fs.readFileSync(readmePath, "utf-8");
|
|
196
|
+
const schemaSectionRe = /### Your GraphQL Schema\n\n[\s\S]*?(?=\n### |\n## )/;
|
|
197
|
+
|
|
198
|
+
const githubNote = loader.tokenEnvVar
|
|
199
|
+
? `\nGitHub sources require an API token: set the \`${loader.tokenEnvVar}\` environment variable before running \`generate\`, \`dev\` or \`build\`.\n`
|
|
200
|
+
: "";
|
|
201
|
+
const replacement = isRemoteSchemaSource(schemaRef)
|
|
202
|
+
? `### Your GraphQL Schema\n\nThis project reads its schema from \`${schemaRef}\` via ${loader.package} (${loader.className}) — configured in \`generate-docs.ts\`. There is no local schema file to edit; point \`generate-docs.ts\`'s \`schema\` option at a different source to change it.\n${githubNote}`
|
|
203
|
+
: `### Your GraphQL Schema\n\nYour schema lives at \`${schemaRef}\`. To point at a different file, update both \`generate-docs.ts\`'s \`schema\` option and \`nuxt.config.ts\`'s \`watch\` entry.\n`;
|
|
204
|
+
|
|
205
|
+
const updated = originalContent.replace(schemaSectionRe, () => replacement);
|
|
206
|
+
|
|
207
|
+
if (updated === originalContent) {
|
|
208
|
+
throw new Error(
|
|
209
|
+
`Expected to find and replace the schema section in ${readmePath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
|
|
210
|
+
);
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
fs.writeFileSync(readmePath, updated);
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/** Nuxt UI / Tailwind color names offered for the primary color. */
|
|
217
|
+
const COLORS = [
|
|
218
|
+
"blue",
|
|
219
|
+
"sky",
|
|
220
|
+
"cyan",
|
|
221
|
+
"teal",
|
|
222
|
+
"emerald",
|
|
223
|
+
"green",
|
|
224
|
+
"lime",
|
|
225
|
+
"amber",
|
|
226
|
+
"orange",
|
|
227
|
+
"red",
|
|
228
|
+
"rose",
|
|
229
|
+
"pink",
|
|
230
|
+
"fuchsia",
|
|
231
|
+
"purple",
|
|
232
|
+
"indigo",
|
|
233
|
+
"slate",
|
|
234
|
+
"zinc",
|
|
235
|
+
"neutral",
|
|
236
|
+
];
|
|
237
|
+
|
|
238
|
+
/** Nuxt scaffold descriptor (templates/nuxt). */
|
|
239
|
+
export const nuxt = {
|
|
240
|
+
id: "nuxt",
|
|
241
|
+
name: "Nuxt",
|
|
242
|
+
label: "Nuxt (@graphql-markdown/nuxt-theme)",
|
|
243
|
+
hint: "Nuxt UI theme, live reload on schema changes",
|
|
244
|
+
detect: ["nuxt", "docus"],
|
|
245
|
+
links: "router",
|
|
246
|
+
contentRoot: "content",
|
|
247
|
+
contentRoute: "/",
|
|
248
|
+
outputHint: "Nuxt (@graphql-markdown/nuxt-theme) reads content from content/",
|
|
249
|
+
nextSteps: ({ outputDir, route }) =>
|
|
250
|
+
`Nuxt Content serves \`${outputDir}\` at \`${route}\`; add a navigation link to it.`,
|
|
251
|
+
scaffold: {
|
|
252
|
+
runScripts: ["dev"],
|
|
253
|
+
copyExcludes: [/^\.nuxt$/, /^\.output$/],
|
|
254
|
+
supportsColor: true,
|
|
255
|
+
colors: COLORS,
|
|
256
|
+
defaultColor: "violet",
|
|
257
|
+
apply(tempDir, { schemaRef, schemaPath, loader, title, color }) {
|
|
258
|
+
writeAppConfig(tempDir, title, color);
|
|
259
|
+
writeGenerateDocs(tempDir, schemaRef, loader);
|
|
260
|
+
writeNuxtConfig(tempDir, schemaRef, isRemoteSchemaSource(schemaRef));
|
|
261
|
+
// README.md is independent of package.json, so running it here (before
|
|
262
|
+
// the shared writePackageJson) is equivalent to running it after.
|
|
263
|
+
writeReadme(tempDir, schemaPath, schemaRef, loader);
|
|
264
|
+
},
|
|
265
|
+
},
|
|
266
|
+
};
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Wire-only framework descriptors (no `scaffold` key): these presets are
|
|
3
|
+
* referenced by the wire mode but are not scaffolded by this package.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/** Astro Starlight preset. */
|
|
7
|
+
export const starlight = {
|
|
8
|
+
id: "starlight",
|
|
9
|
+
name: "Astro Starlight",
|
|
10
|
+
label: "Astro Starlight",
|
|
11
|
+
formatter: "@graphql-markdown/formatters/starlight",
|
|
12
|
+
createCommand: "npm create astro@latest -- --template starlight",
|
|
13
|
+
detect: ["@astrojs/starlight"],
|
|
14
|
+
links: "absolute",
|
|
15
|
+
contentRoot: "src/content/docs",
|
|
16
|
+
contentRoute: "/",
|
|
17
|
+
outputHint: "Astro Starlight reads content from src/content/docs/",
|
|
18
|
+
nextSteps: ({ outputDir }) =>
|
|
19
|
+
`Add a sidebar group in astro.config.*: { label: 'API', autogenerate: { directory: '${outputDir}' } }.`,
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
/** Fumadocs preset. */
|
|
23
|
+
export const fumadocs = {
|
|
24
|
+
id: "fumadocs",
|
|
25
|
+
name: "Fumadocs",
|
|
26
|
+
label: "Fumadocs",
|
|
27
|
+
formatter: "@graphql-markdown/formatters/fumadocs",
|
|
28
|
+
createCommand: "npm create fumadocs-app@latest",
|
|
29
|
+
detect: ["fumadocs-core", "fumadocs-ui"],
|
|
30
|
+
links: "router",
|
|
31
|
+
contentRoot: "content/docs",
|
|
32
|
+
contentRoute: "/docs",
|
|
33
|
+
outputHint: "Fumadocs reads content from content/docs/",
|
|
34
|
+
nextSteps: ({ outputDir }) =>
|
|
35
|
+
`Add the folder to \`pages\` in the parent meta.json of \`${outputDir}\` (or let Fumadocs list it).`,
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
/** Vocs preset. */
|
|
39
|
+
export const vocs = {
|
|
40
|
+
id: "vocs",
|
|
41
|
+
name: "Vocs",
|
|
42
|
+
label: "Vocs",
|
|
43
|
+
formatter: "@graphql-markdown/formatters/vocs",
|
|
44
|
+
createCommand: "npm create vocs@latest",
|
|
45
|
+
detect: ["vocs"],
|
|
46
|
+
links: "router",
|
|
47
|
+
contentRoot: "docs/pages",
|
|
48
|
+
contentRoute: "/",
|
|
49
|
+
outputHint: "Vocs reads content from docs/pages/",
|
|
50
|
+
nextSteps: ({ route }) =>
|
|
51
|
+
`Add a sidebar entry in vocs.config.* linking to \`${route}\`.`,
|
|
52
|
+
};
|
|
53
|
+
|
|
54
|
+
/** HonKit preset. */
|
|
55
|
+
export const honkit = {
|
|
56
|
+
id: "honkit",
|
|
57
|
+
name: "HonKit",
|
|
58
|
+
label: "HonKit",
|
|
59
|
+
formatter: "@graphql-markdown/formatters/honkit",
|
|
60
|
+
createCommand: "npx honkit init",
|
|
61
|
+
detect: ["honkit"],
|
|
62
|
+
links: "absolute",
|
|
63
|
+
contentRoot: ".",
|
|
64
|
+
contentRoute: "/",
|
|
65
|
+
outputHint: "HonKit reads content from the project root",
|
|
66
|
+
nextSteps: () => "List the generated pages in SUMMARY.md.",
|
|
67
|
+
};
|
|
68
|
+
|
|
69
|
+
/** Hugo preset. */
|
|
70
|
+
export const hugo = {
|
|
71
|
+
id: "hugo",
|
|
72
|
+
name: "Hugo",
|
|
73
|
+
label: "Hugo",
|
|
74
|
+
formatter: "@graphql-markdown/formatters/hugo",
|
|
75
|
+
createCommand: "hugo new site <dir>",
|
|
76
|
+
detect: ["hugo-bin", "hugo-extended"],
|
|
77
|
+
links: "absolute",
|
|
78
|
+
contentRoot: "content",
|
|
79
|
+
contentRoute: "/",
|
|
80
|
+
outputHint: "Hugo reads content from content/",
|
|
81
|
+
nextSteps: ({ route }) =>
|
|
82
|
+
`Add a menu entry in your Hugo config pointing to \`${route}\`.`,
|
|
83
|
+
};
|
|
84
|
+
|
|
85
|
+
/** MkDocs preset. */
|
|
86
|
+
export const mkdocs = {
|
|
87
|
+
id: "mkdocs",
|
|
88
|
+
name: "MkDocs",
|
|
89
|
+
label: "MkDocs",
|
|
90
|
+
formatter: "@graphql-markdown/formatters/mkdocs",
|
|
91
|
+
createCommand: "mkdocs new <dir>",
|
|
92
|
+
links: "relative",
|
|
93
|
+
contentRoot: "docs",
|
|
94
|
+
outputHint: "MkDocs reads content from docs/",
|
|
95
|
+
nextSteps: ({ outputDir }) =>
|
|
96
|
+
`Add \`${outputDir}\` to \`nav\` in mkdocs.yml (or omit \`nav\` to list pages automatically).`,
|
|
97
|
+
};
|
|
98
|
+
|
|
99
|
+
/** DocFX preset. */
|
|
100
|
+
export const docfx = {
|
|
101
|
+
id: "docfx",
|
|
102
|
+
name: "DocFX",
|
|
103
|
+
label: "DocFX",
|
|
104
|
+
formatter: "@graphql-markdown/formatters/docfx",
|
|
105
|
+
createCommand: "docfx init",
|
|
106
|
+
links: "relative",
|
|
107
|
+
contentRoot: "docs",
|
|
108
|
+
outputHint: "DocFX reads content from docs/",
|
|
109
|
+
nextSteps: ({ outputDir }) => `Add \`${outputDir}\` to toc.yml.`,
|
|
110
|
+
};
|
|
111
|
+
|
|
112
|
+
/** mdBook preset. */
|
|
113
|
+
export const mdbook = {
|
|
114
|
+
id: "mdbook",
|
|
115
|
+
name: "mdBook",
|
|
116
|
+
label: "mdBook",
|
|
117
|
+
formatter: "@graphql-markdown/formatters/mdbook",
|
|
118
|
+
createCommand: "mdbook init <dir>",
|
|
119
|
+
links: "relative",
|
|
120
|
+
contentRoot: "src",
|
|
121
|
+
outputHint: "mdBook reads content from src/",
|
|
122
|
+
nextSteps: () =>
|
|
123
|
+
"List the generated pages in src/SUMMARY.md — mdBook only builds listed pages.",
|
|
124
|
+
};
|
|
125
|
+
|
|
126
|
+
/** Generic Markdown fallback (no formatter preset). */
|
|
127
|
+
export const generic = {
|
|
128
|
+
id: "generic",
|
|
129
|
+
name: "Other / generic Markdown",
|
|
130
|
+
label: "Other / generic Markdown",
|
|
131
|
+
nextSteps: ({ outputDir }) =>
|
|
132
|
+
`Point your site navigation at \`${outputDir}\`. Manual wiring guide: https://graphql-markdown.dev`,
|
|
133
|
+
};
|