create-graphql-markdown-docs 0.1.1 → 1.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 +107 -26
- package/lib/create.mjs +525 -670
- package/lib/frameworks/docusaurus.mjs +66 -0
- package/lib/frameworks/index.mjs +66 -0
- package/lib/frameworks/links.mjs +102 -0
- package/lib/frameworks/markdown.mjs +75 -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 +137 -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 +146 -0
- package/lib/telemetry.mjs +46 -0
- package/lib/wire/deps.mjs +38 -0
- package/lib/wire/plan.mjs +259 -0
- package/lib/wire/steps.mjs +359 -0
- package/lib/wire/yaml.mjs +93 -0
- package/package.json +5 -4
- package/templates/docusaurus/gitignore +20 -0
- package/templates/docusaurus/package.json +1 -1
- package/templates/markdown/.graphqlrc +9 -0
- package/templates/markdown/README.md +13 -0
- package/templates/markdown/docs/.gitkeep +0 -0
- package/templates/markdown/gitignore +1 -0
- package/templates/markdown/package.json +13 -0
- package/templates/markdown/schema/example.graphql +55 -0
- package/templates/nuxt/gitignore +30 -0
- package/templates/nuxt/package.json +2 -2
|
@@ -0,0 +1,359 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import { createRequire } from "node:module";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
|
|
5
|
+
import * as prompts from "@clack/prompts";
|
|
6
|
+
|
|
7
|
+
import { FRAMEWORK_ALIASES, WIRE_FRAMEWORKS } from "../frameworks/index.mjs";
|
|
8
|
+
import { normalizeOutput, suggestLinkRoot } from "../frameworks/links.mjs";
|
|
9
|
+
import {
|
|
10
|
+
DOCS_URL,
|
|
11
|
+
fail,
|
|
12
|
+
failureNote,
|
|
13
|
+
resolvePackageManager,
|
|
14
|
+
unlessCancelled,
|
|
15
|
+
validateSchemaSource,
|
|
16
|
+
} from "../helpers.mjs";
|
|
17
|
+
import { reportTelemetry } from "../telemetry.mjs";
|
|
18
|
+
import { detectLoader } from "../schema.mjs";
|
|
19
|
+
import { addDevCommand, addDevDependencies } from "../tasks.mjs";
|
|
20
|
+
import { detectFrameworks, toSchemaRef } from "../target.mjs";
|
|
21
|
+
import { requiredPackages } from "./deps.mjs";
|
|
22
|
+
import {
|
|
23
|
+
applyWirePlan,
|
|
24
|
+
DEFAULT_SCRIPT_NAME,
|
|
25
|
+
formatWirePlan,
|
|
26
|
+
inspectProject,
|
|
27
|
+
planWire,
|
|
28
|
+
validateOutput,
|
|
29
|
+
} from "./plan.mjs";
|
|
30
|
+
|
|
31
|
+
const labelOf = (id) => WIRE_FRAMEWORKS[id].label;
|
|
32
|
+
|
|
33
|
+
/** Whether wire mode has dependencies to add: a package.json and packages not yet listed. */
|
|
34
|
+
const needsInstall = (ctx) => {
|
|
35
|
+
return Boolean(ctx.project.packageJson) && ctx.packages.length > 0;
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
/** Frameworks found in package.json plus the --framework value (empty counts as absent). */
|
|
39
|
+
function requestedFramework(args) {
|
|
40
|
+
return args.framework || undefined;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** With --yes, everything that cannot be guessed must be passed as a flag. */
|
|
44
|
+
function preflight(ctx) {
|
|
45
|
+
const { args } = ctx;
|
|
46
|
+
if (!args.yes) return;
|
|
47
|
+
const missing = [];
|
|
48
|
+
if (!args.schema) missing.push("--schema");
|
|
49
|
+
if (!args.output) missing.push("--output");
|
|
50
|
+
if (!requestedFramework(args) && ctx.detected.length !== 1) {
|
|
51
|
+
missing.push("--framework");
|
|
52
|
+
}
|
|
53
|
+
if (missing.length === 0) return;
|
|
54
|
+
let message = `Missing required options to add GraphQL-Markdown without prompts: ${missing.join(", ")}.`;
|
|
55
|
+
if (ctx.detected.length > 1) {
|
|
56
|
+
message += ` Detected: ${ctx.detected.map(labelOf).join(", ")}.`;
|
|
57
|
+
} else if (ctx.detected.length === 0) {
|
|
58
|
+
message += " Use --framework generic for an unlisted framework.";
|
|
59
|
+
}
|
|
60
|
+
fail(message);
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
function frameworkOptions(ids) {
|
|
64
|
+
return ids.map((id) => ({
|
|
65
|
+
value: id,
|
|
66
|
+
label: WIRE_FRAMEWORKS[id].label,
|
|
67
|
+
hint: WIRE_FRAMEWORKS[id].hint,
|
|
68
|
+
}));
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
async function resolveWireFramework(ctx) {
|
|
72
|
+
const { args, detected } = ctx;
|
|
73
|
+
const requested = requestedFramework(args);
|
|
74
|
+
if (requested) {
|
|
75
|
+
const aliases = FRAMEWORK_ALIASES.wire;
|
|
76
|
+
if (Object.hasOwn(aliases, requested)) return aliases[requested];
|
|
77
|
+
if (!Object.hasOwn(WIRE_FRAMEWORKS, requested)) {
|
|
78
|
+
fail(
|
|
79
|
+
`Invalid --framework "${requested}" — expected one of: ${Object.keys(WIRE_FRAMEWORKS).join(", ")}.`,
|
|
80
|
+
);
|
|
81
|
+
}
|
|
82
|
+
return requested;
|
|
83
|
+
}
|
|
84
|
+
if (detected.length === 1 && args.yes) {
|
|
85
|
+
prompts.log.info(`Detected ${labelOf(detected[0])}`);
|
|
86
|
+
return detected[0];
|
|
87
|
+
}
|
|
88
|
+
const all = Object.keys(WIRE_FRAMEWORKS);
|
|
89
|
+
const select = (options, initialValue) =>
|
|
90
|
+
prompts.select({
|
|
91
|
+
message: "Which framework does this project use?",
|
|
92
|
+
options,
|
|
93
|
+
initialValue,
|
|
94
|
+
});
|
|
95
|
+
if (detected.length === 1) {
|
|
96
|
+
return unlessCancelled(await select(frameworkOptions(all), detected[0]));
|
|
97
|
+
}
|
|
98
|
+
if (detected.length > 1) {
|
|
99
|
+
return unlessCancelled(await select(frameworkOptions(detected)));
|
|
100
|
+
}
|
|
101
|
+
return unlessCancelled(await select(frameworkOptions(all), "generic"));
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
async function resolveWireSchema(ctx) {
|
|
105
|
+
const { args, projectDir } = ctx;
|
|
106
|
+
let source = args.schema?.trim();
|
|
107
|
+
if (source) {
|
|
108
|
+
const problem = validateSchemaSource(source);
|
|
109
|
+
if (problem) fail(problem);
|
|
110
|
+
} else {
|
|
111
|
+
source = unlessCancelled(
|
|
112
|
+
await prompts.text({
|
|
113
|
+
message: "Schema source (path, glob or URL)",
|
|
114
|
+
validate: validateSchemaSource,
|
|
115
|
+
}),
|
|
116
|
+
).trim();
|
|
117
|
+
}
|
|
118
|
+
ctx.schemaRef = toSchemaRef(source, projectDir);
|
|
119
|
+
ctx.loader = detectLoader(source);
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
async function resolveWireOutput(ctx) {
|
|
123
|
+
const { args, projectDir, descriptor } = ctx;
|
|
124
|
+
let output = args.output;
|
|
125
|
+
if (output === undefined) {
|
|
126
|
+
const hint = descriptor.outputHint ? ` (${descriptor.outputHint})` : "";
|
|
127
|
+
output = unlessCancelled(
|
|
128
|
+
await prompts.text({
|
|
129
|
+
message: `Output folder for the generated docs${hint}`,
|
|
130
|
+
validate: (value) => validateOutput(projectDir, value).error,
|
|
131
|
+
}),
|
|
132
|
+
);
|
|
133
|
+
}
|
|
134
|
+
const { error, warning } = validateOutput(projectDir, output);
|
|
135
|
+
if (error) fail(error);
|
|
136
|
+
if (warning) prompts.log.warn(warning);
|
|
137
|
+
ctx.output = output.trim();
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
async function resolveSiteBase(ctx) {
|
|
141
|
+
const { args } = ctx;
|
|
142
|
+
if (args["site-base"] !== undefined) return args["site-base"];
|
|
143
|
+
if (args.yes) return "/";
|
|
144
|
+
const answer = unlessCancelled(
|
|
145
|
+
await prompts.text({
|
|
146
|
+
message: "Base path the site is served from",
|
|
147
|
+
placeholder: "/",
|
|
148
|
+
defaultValue: "/",
|
|
149
|
+
}),
|
|
150
|
+
);
|
|
151
|
+
return answer.trim() || "/";
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
async function resolveLinkRoot(ctx) {
|
|
155
|
+
const { args } = ctx;
|
|
156
|
+
if (args["link-root"] !== undefined) {
|
|
157
|
+
return args["link-root"].trim() || null;
|
|
158
|
+
}
|
|
159
|
+
const suggestion = suggestLinkRoot(ctx.descriptor, ctx.output, {
|
|
160
|
+
siteBase: ctx.siteBase,
|
|
161
|
+
});
|
|
162
|
+
if (args.yes) return suggestion;
|
|
163
|
+
const answer = unlessCancelled(
|
|
164
|
+
await prompts.text({
|
|
165
|
+
message: "Link root (route of the generated docs, blank for none)",
|
|
166
|
+
initialValue: suggestion,
|
|
167
|
+
}),
|
|
168
|
+
);
|
|
169
|
+
return answer.trim() || null;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
async function resolveWireLinks(ctx) {
|
|
173
|
+
const { links } = ctx.descriptor;
|
|
174
|
+
if (links === "relative") return;
|
|
175
|
+
if (links === "absolute") ctx.siteBase = await resolveSiteBase(ctx);
|
|
176
|
+
ctx.linkRoot = await resolveLinkRoot(ctx);
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/** Warns when the requested formatter cannot be found yet. */
|
|
180
|
+
function checkFormatter(ctx) {
|
|
181
|
+
const name = ctx.args.formatter;
|
|
182
|
+
if (!name) return;
|
|
183
|
+
if (name.startsWith(".") || name.startsWith("/")) {
|
|
184
|
+
if (!fs.existsSync(path.resolve(ctx.projectDir, name))) {
|
|
185
|
+
prompts.log.warn(`${name} does not exist.`);
|
|
186
|
+
}
|
|
187
|
+
return;
|
|
188
|
+
}
|
|
189
|
+
try {
|
|
190
|
+
createRequire(path.join(ctx.projectDir, "package.json")).resolve(name);
|
|
191
|
+
} catch {
|
|
192
|
+
prompts.log.warn(`${name} is not installed in the project yet.`);
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/** Works out the packages wire mode needs and warns when --install has no package.json to use. */
|
|
197
|
+
function planDependencies(ctx) {
|
|
198
|
+
const { args, project, descriptor, loader } = ctx;
|
|
199
|
+
ctx.packages = requiredPackages({
|
|
200
|
+
descriptor,
|
|
201
|
+
loader,
|
|
202
|
+
formatter: args.formatter,
|
|
203
|
+
packageJson: project.packageJson,
|
|
204
|
+
});
|
|
205
|
+
if (args.install && !project.packageJson) {
|
|
206
|
+
prompts.log.warn(
|
|
207
|
+
"--install ignored: there is no package.json — run the generator with npx instead.",
|
|
208
|
+
);
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
async function writePlan(ctx) {
|
|
213
|
+
await reportTelemetry(ctx);
|
|
214
|
+
const { args, projectDir, project, descriptor } = ctx;
|
|
215
|
+
const plan = planWire(
|
|
216
|
+
{
|
|
217
|
+
descriptor,
|
|
218
|
+
schema: ctx.schemaRef,
|
|
219
|
+
loader: ctx.loader,
|
|
220
|
+
output: ctx.output,
|
|
221
|
+
linkRoot: ctx.linkRoot,
|
|
222
|
+
siteBase: ctx.siteBase,
|
|
223
|
+
formatter: args.formatter,
|
|
224
|
+
},
|
|
225
|
+
project,
|
|
226
|
+
{ scriptName: ctx.scriptName },
|
|
227
|
+
);
|
|
228
|
+
ctx.plan = plan;
|
|
229
|
+
checkFormatter(ctx);
|
|
230
|
+
planDependencies(ctx);
|
|
231
|
+
if (args["dry-run"]) {
|
|
232
|
+
prompts.note(formatWirePlan(plan), "Dry run — nothing written");
|
|
233
|
+
return;
|
|
234
|
+
}
|
|
235
|
+
for (const file of applyWirePlan(projectDir, plan, project)) {
|
|
236
|
+
prompts.log.success(`Wrote ${file}`);
|
|
237
|
+
}
|
|
238
|
+
for (const warning of plan.warnings) prompts.log.warn(warning);
|
|
239
|
+
if (plan.mergeBlock) {
|
|
240
|
+
prompts.note(plan.mergeBlock, "Merge into your existing GraphQL config");
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
/** Ordered steps that add GraphQL-Markdown to an existing project. */
|
|
245
|
+
export const WIRE_STEPS = [
|
|
246
|
+
{
|
|
247
|
+
id: "inspect",
|
|
248
|
+
title: "Inspect project",
|
|
249
|
+
run(ctx) {
|
|
250
|
+
ctx.project = inspectProject(ctx.projectDir);
|
|
251
|
+
ctx.detected = detectFrameworks(ctx.project.packageJson);
|
|
252
|
+
ctx.scriptName = ctx.args.script || DEFAULT_SCRIPT_NAME;
|
|
253
|
+
preflight(ctx);
|
|
254
|
+
},
|
|
255
|
+
},
|
|
256
|
+
{
|
|
257
|
+
id: "framework",
|
|
258
|
+
title: "Choose framework",
|
|
259
|
+
async run(ctx) {
|
|
260
|
+
ctx.framework = await resolveWireFramework(ctx);
|
|
261
|
+
ctx.descriptor = WIRE_FRAMEWORKS[ctx.framework];
|
|
262
|
+
},
|
|
263
|
+
},
|
|
264
|
+
{ id: "schema", title: "Choose schema", run: resolveWireSchema },
|
|
265
|
+
{ id: "output", title: "Choose output folder", run: resolveWireOutput },
|
|
266
|
+
{ id: "links", title: "Configure links", run: resolveWireLinks },
|
|
267
|
+
{ id: "write", title: "Write configuration", run: writePlan },
|
|
268
|
+
{
|
|
269
|
+
id: "packageManager",
|
|
270
|
+
title: "Choose package manager",
|
|
271
|
+
when: (ctx) =>
|
|
272
|
+
Boolean(ctx.project.packageJson) &&
|
|
273
|
+
(!ctx.args["dry-run"] || ctx.packages.length > 0),
|
|
274
|
+
async run(ctx) {
|
|
275
|
+
ctx.packageManager = await resolvePackageManager(
|
|
276
|
+
ctx.args,
|
|
277
|
+
ctx.projectDir,
|
|
278
|
+
);
|
|
279
|
+
},
|
|
280
|
+
},
|
|
281
|
+
{
|
|
282
|
+
id: "install",
|
|
283
|
+
title: "Install dev dependencies",
|
|
284
|
+
optional: true,
|
|
285
|
+
when: (ctx) =>
|
|
286
|
+
Boolean(ctx.args.install) && !ctx.args["dry-run"] && needsInstall(ctx),
|
|
287
|
+
run: (ctx) =>
|
|
288
|
+
addDevDependencies(
|
|
289
|
+
ctx.packageManager,
|
|
290
|
+
ctx.projectDir,
|
|
291
|
+
ctx.packages,
|
|
292
|
+
addDevOptions(ctx),
|
|
293
|
+
),
|
|
294
|
+
catchUp: (ctx) =>
|
|
295
|
+
needsInstall(ctx)
|
|
296
|
+
? [addDevCommand(ctx.packageManager, ctx.packages, addDevOptions(ctx))]
|
|
297
|
+
: [],
|
|
298
|
+
},
|
|
299
|
+
];
|
|
300
|
+
|
|
301
|
+
/** Options for adding dev deps; yarn berry has no -W workspace-root flag. */
|
|
302
|
+
function addDevOptions(ctx) {
|
|
303
|
+
const { project, packageManager } = ctx;
|
|
304
|
+
const workspaceRoot =
|
|
305
|
+
packageManager === "pnpm"
|
|
306
|
+
? Boolean(project.pnpmWorkspace)
|
|
307
|
+
: packageManager === "yarn"
|
|
308
|
+
? Boolean(project.packageJson?.workspaces) && !project.yarnBerry
|
|
309
|
+
: false;
|
|
310
|
+
return { workspaceRoot };
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/** Prints the closing summary for wire mode; `outcomes` are the step results. */
|
|
314
|
+
export function printWireOutro(ctx, outcomes = []) {
|
|
315
|
+
if (ctx.args["dry-run"]) {
|
|
316
|
+
if (needsInstall(ctx)) {
|
|
317
|
+
const command = addDevCommand(
|
|
318
|
+
ctx.packageManager,
|
|
319
|
+
ctx.packages,
|
|
320
|
+
addDevOptions(ctx),
|
|
321
|
+
);
|
|
322
|
+
prompts.log.info(
|
|
323
|
+
ctx.args.install
|
|
324
|
+
? `Would install: ${command}`
|
|
325
|
+
: `Install with: ${command}`,
|
|
326
|
+
);
|
|
327
|
+
}
|
|
328
|
+
prompts.outro("Dry run complete — nothing was written.");
|
|
329
|
+
return;
|
|
330
|
+
}
|
|
331
|
+
const { plan, scriptName, descriptor } = ctx;
|
|
332
|
+
const hasScript = plan.script.name || plan.script.skipped?.includes("exists");
|
|
333
|
+
const generate = hasScript
|
|
334
|
+
? `${ctx.packageManager} run ${scriptName}`
|
|
335
|
+
: "npx -p @graphql-markdown/cli@latest gqlmd graphql-to-doc";
|
|
336
|
+
// Commands for steps that did not finish (e.g. the install), then the generate step.
|
|
337
|
+
const catchUp = outcomes
|
|
338
|
+
.filter((outcome) => outcome.status !== "done" && outcome.catchUp)
|
|
339
|
+
.flatMap(({ step }) => step.catchUp?.(ctx) ?? []);
|
|
340
|
+
const steps = [
|
|
341
|
+
...catchUp,
|
|
342
|
+
generate,
|
|
343
|
+
descriptor.nextSteps({
|
|
344
|
+
outputDir: normalizeOutput(ctx.output),
|
|
345
|
+
route: ctx.linkRoot,
|
|
346
|
+
}),
|
|
347
|
+
];
|
|
348
|
+
const { tokenEnvVar } = ctx.loader;
|
|
349
|
+
const tokenHint = tokenEnvVar
|
|
350
|
+
? `\nNote: set the ${tokenEnvVar} environment variable so the GitHub schema can be loaded.\n`
|
|
351
|
+
: "";
|
|
352
|
+
const list = steps.map((step, i) => ` ${i + 1}. ${step}`).join("\n");
|
|
353
|
+
prompts.outro(`
|
|
354
|
+
${failureNote(outcomes)}Next steps:
|
|
355
|
+
${list}
|
|
356
|
+
${tokenHint}
|
|
357
|
+
Documentation: ${DOCS_URL}
|
|
358
|
+
`);
|
|
359
|
+
}
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
const BARE_KEY = /^[A-Za-z_][\w-]*$/;
|
|
2
|
+
|
|
3
|
+
const INDENT = " ";
|
|
4
|
+
|
|
5
|
+
const quoteSingle = (text) => `'${text.replaceAll("'", "''")}'`;
|
|
6
|
+
|
|
7
|
+
const isPlainObject = (value) => {
|
|
8
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) {
|
|
9
|
+
return false;
|
|
10
|
+
}
|
|
11
|
+
const proto = Object.getPrototypeOf(value);
|
|
12
|
+
return proto === Object.prototype || proto === null;
|
|
13
|
+
};
|
|
14
|
+
|
|
15
|
+
const describeType = (value) => {
|
|
16
|
+
if (Array.isArray(value)) {
|
|
17
|
+
return "array";
|
|
18
|
+
}
|
|
19
|
+
return typeof value;
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
const formatKey = (key) => (BARE_KEY.test(key) ? key : quoteSingle(key));
|
|
23
|
+
|
|
24
|
+
const formatScalar = (value, path) => {
|
|
25
|
+
if (value === null) {
|
|
26
|
+
return "null";
|
|
27
|
+
}
|
|
28
|
+
switch (typeof value) {
|
|
29
|
+
case "string":
|
|
30
|
+
return quoteSingle(value);
|
|
31
|
+
case "boolean":
|
|
32
|
+
return String(value);
|
|
33
|
+
case "number":
|
|
34
|
+
if (!Number.isFinite(value)) {
|
|
35
|
+
throw new TypeError(
|
|
36
|
+
`Unsupported value at ${path}: non-finite number ${value}`,
|
|
37
|
+
);
|
|
38
|
+
}
|
|
39
|
+
return String(value);
|
|
40
|
+
default:
|
|
41
|
+
throw new TypeError(
|
|
42
|
+
`Unsupported value at ${path}: ${describeType(value)}`,
|
|
43
|
+
);
|
|
44
|
+
}
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
const serializeObject = (object, depth, parentPath, lines) => {
|
|
48
|
+
const pad = INDENT.repeat(depth);
|
|
49
|
+
for (const key of Object.keys(object)) {
|
|
50
|
+
const value = object[key];
|
|
51
|
+
if (value === undefined) {
|
|
52
|
+
continue;
|
|
53
|
+
}
|
|
54
|
+
const path = parentPath ? `${parentPath}.${key}` : key;
|
|
55
|
+
const head = `${pad}${formatKey(key)}`;
|
|
56
|
+
if (isPlainObject(value)) {
|
|
57
|
+
if (Object.keys(value).length === 0) {
|
|
58
|
+
lines.push(`${head}: {}`);
|
|
59
|
+
} else {
|
|
60
|
+
lines.push(`${head}:`);
|
|
61
|
+
serializeObject(value, depth + 1, path, lines);
|
|
62
|
+
}
|
|
63
|
+
} else {
|
|
64
|
+
lines.push(`${head}: ${formatScalar(value, path)}`);
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
};
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Minimal YAML serializer for `.graphqlrc` files.
|
|
71
|
+
*
|
|
72
|
+
* Exists so that `npm create` does not need a YAML dependency: the generated
|
|
73
|
+
* config only uses plain objects, strings, booleans, finite numbers and null.
|
|
74
|
+
* Strings are always single-quoted, `undefined` values are omitted, and arrays
|
|
75
|
+
* or other unsupported types throw a TypeError naming the offending key path.
|
|
76
|
+
*
|
|
77
|
+
* @param {Record<string, unknown>} value Plain object to serialize.
|
|
78
|
+
* @returns {string} YAML text with 2-space indentation and a single trailing newline.
|
|
79
|
+
* @throws {TypeError} When the top level is not an object or a nested value is unsupported.
|
|
80
|
+
*/
|
|
81
|
+
export const toYaml = (value) => {
|
|
82
|
+
if (!isPlainObject(value)) {
|
|
83
|
+
throw new TypeError(
|
|
84
|
+
`toYaml expects a plain object at the top level, received ${describeType(value)}`,
|
|
85
|
+
);
|
|
86
|
+
}
|
|
87
|
+
const lines = [];
|
|
88
|
+
serializeObject(value, 0, "", lines);
|
|
89
|
+
if (lines.length === 0) {
|
|
90
|
+
return "{}\n";
|
|
91
|
+
}
|
|
92
|
+
return `${lines.join("\n")}\n`;
|
|
93
|
+
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-graphql-markdown-docs",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "Create a new GraphQL API documentation site with GraphQL Markdown and Nuxt or Docusaurus",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"homepage": "https://graphql-markdown.dev",
|
|
@@ -47,11 +47,12 @@
|
|
|
47
47
|
],
|
|
48
48
|
"dependencies": {
|
|
49
49
|
"@clack/prompts": "^1.0.0",
|
|
50
|
-
"graphql": "^
|
|
51
|
-
"
|
|
50
|
+
"@graphql-markdown/telemetry": "^0.1.0",
|
|
51
|
+
"graphql": "^16.8.0 || ^17.0.0",
|
|
52
|
+
"package-manager-detector": "^1.8.0"
|
|
52
53
|
},
|
|
53
54
|
"devDependencies": {
|
|
54
|
-
"@graphql-markdown/tooling-config": ""
|
|
55
|
+
"@graphql-markdown/tooling-config": "^1.0.0"
|
|
55
56
|
},
|
|
56
57
|
"engines": {
|
|
57
58
|
"node": ">=22.12.0"
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Dependencies
|
|
2
|
+
/node_modules
|
|
3
|
+
|
|
4
|
+
# Production
|
|
5
|
+
/build
|
|
6
|
+
|
|
7
|
+
# Generated files
|
|
8
|
+
.docusaurus
|
|
9
|
+
.cache-loader
|
|
10
|
+
|
|
11
|
+
# Misc
|
|
12
|
+
.DS_Store
|
|
13
|
+
.env.local
|
|
14
|
+
.env.development.local
|
|
15
|
+
.env.test.local
|
|
16
|
+
.env.production.local
|
|
17
|
+
|
|
18
|
+
npm-debug.log*
|
|
19
|
+
yarn-debug.log*
|
|
20
|
+
yarn-error.log*
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
"dependencies": {
|
|
16
16
|
"@docusaurus/core": "^3.10.0",
|
|
17
17
|
"@docusaurus/preset-classic": "^3.10.0",
|
|
18
|
-
"@graphql-markdown/docusaurus": "^1.
|
|
18
|
+
"@graphql-markdown/docusaurus": "^1.39.0",
|
|
19
19
|
"@graphql-tools/graphql-file-loader": "^8.0.0",
|
|
20
20
|
"@mdx-js/react": "^3.1.1",
|
|
21
21
|
"graphql": "^16.13.2",
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# GraphQL-Markdown docs
|
|
2
|
+
|
|
3
|
+
API documentation generated with [GraphQL-Markdown](https://graphql-markdown.dev). The pages are plain files written to `docs/` (`.md`, or `.mdx` for the MDX variant), with no site framework attached.
|
|
4
|
+
|
|
5
|
+
## Generate
|
|
6
|
+
|
|
7
|
+
```shell
|
|
8
|
+
npm run doc
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
### Your GraphQL Schema
|
|
12
|
+
|
|
13
|
+
The schema is configured in `.graphqlrc` (see the [documentation](https://graphql-markdown.dev/docs/configuration#graphql-config)). By default it reads the bundled `schema/example.graphql`. To change it, edit `schema` in `.graphqlrc` (a local file, or a URL, `git:` or `github:` reference) and declare the matching [graphql-tools loader](https://github.com/ardatan/graphql-tools/tree/master/packages/loaders) under `loaders`. Then run `npm run doc` again.
|
|
File without changes
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
node_modules/
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "graphql-markdown-docs",
|
|
3
|
+
"private": true,
|
|
4
|
+
"scripts": {
|
|
5
|
+
"doc": "gqlmd graphql-to-doc"
|
|
6
|
+
},
|
|
7
|
+
"dependencies": {
|
|
8
|
+
"@graphql-markdown/cli": "^1.2.0",
|
|
9
|
+
"@graphql-tools/graphql-file-loader": "^8.0.0",
|
|
10
|
+
"graphql": "^16.13.2",
|
|
11
|
+
"graphql-config": "^5.1.6"
|
|
12
|
+
}
|
|
13
|
+
}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
"""
|
|
2
|
+
A simple example GraphQL schema demonstrating the GraphQL Markdown theme.
|
|
3
|
+
"""
|
|
4
|
+
scalar DateTime
|
|
5
|
+
|
|
6
|
+
"""
|
|
7
|
+
The root query type for the API.
|
|
8
|
+
"""
|
|
9
|
+
type Query {
|
|
10
|
+
"""
|
|
11
|
+
Retrieve a user by their ID.
|
|
12
|
+
"""
|
|
13
|
+
user(id: ID!): User
|
|
14
|
+
|
|
15
|
+
"""
|
|
16
|
+
List all available users.
|
|
17
|
+
"""
|
|
18
|
+
users: [User!]!
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
"""
|
|
22
|
+
A user in the system.
|
|
23
|
+
"""
|
|
24
|
+
type User {
|
|
25
|
+
"""
|
|
26
|
+
The unique identifier for this user.
|
|
27
|
+
"""
|
|
28
|
+
id: ID!
|
|
29
|
+
|
|
30
|
+
"""
|
|
31
|
+
The user's name.
|
|
32
|
+
"""
|
|
33
|
+
name: String!
|
|
34
|
+
|
|
35
|
+
"""
|
|
36
|
+
The user's email address.
|
|
37
|
+
"""
|
|
38
|
+
email: String!
|
|
39
|
+
|
|
40
|
+
"""
|
|
41
|
+
When this user account was created.
|
|
42
|
+
"""
|
|
43
|
+
createdAt: DateTime!
|
|
44
|
+
|
|
45
|
+
"""
|
|
46
|
+
The user's profile picture URL.
|
|
47
|
+
@deprecated Use `avatar` instead.
|
|
48
|
+
"""
|
|
49
|
+
profilePictureUrl: String @deprecated(reason: "Use avatar field instead")
|
|
50
|
+
|
|
51
|
+
"""
|
|
52
|
+
The user's avatar profile picture.
|
|
53
|
+
"""
|
|
54
|
+
avatar: String
|
|
55
|
+
}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Dependencies
|
|
2
|
+
node_modules/
|
|
3
|
+
|
|
4
|
+
# Nuxt build/generate artifacts
|
|
5
|
+
.nuxt/
|
|
6
|
+
.output/
|
|
7
|
+
dist/
|
|
8
|
+
|
|
9
|
+
# Generated content
|
|
10
|
+
content/api-reference/
|
|
11
|
+
|
|
12
|
+
# Environment variables
|
|
13
|
+
.env
|
|
14
|
+
.env.local
|
|
15
|
+
.env.*.local
|
|
16
|
+
|
|
17
|
+
# IDE and editor
|
|
18
|
+
.vscode/
|
|
19
|
+
.idea/
|
|
20
|
+
*.swp
|
|
21
|
+
*.swo
|
|
22
|
+
*~
|
|
23
|
+
.DS_Store
|
|
24
|
+
|
|
25
|
+
# Logs
|
|
26
|
+
*.log
|
|
27
|
+
npm-debug.log*
|
|
28
|
+
yarn-debug.log*
|
|
29
|
+
yarn-error.log*
|
|
30
|
+
pnpm-debug.log*
|
|
@@ -11,11 +11,11 @@
|
|
|
11
11
|
"preview": "nuxi preview"
|
|
12
12
|
},
|
|
13
13
|
"dependencies": {
|
|
14
|
-
"@graphql-markdown/nuxt-theme": "^0.
|
|
14
|
+
"@graphql-markdown/nuxt-theme": "^0.2.0",
|
|
15
15
|
"@nuxt/content": "^3.16.0",
|
|
16
16
|
"@nuxt/ui": "^4.11.0",
|
|
17
17
|
"better-sqlite3": "^13.0.3",
|
|
18
|
-
"nuxt": "^4.
|
|
18
|
+
"nuxt": "^4.6.0",
|
|
19
19
|
"tailwindcss": "^4.3.3"
|
|
20
20
|
},
|
|
21
21
|
"devDependencies": {},
|