create-graphql-markdown-docs 1.0.0 → 1.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.
package/README.md CHANGED
@@ -1,6 +1,9 @@
1
1
  # create-graphql-markdown-docs
2
2
 
3
- Interactive CLI that either creates a ready-to-run [GraphQL Markdown](https://graphql-markdown.dev) API reference site (Nuxt or Docusaurus) or adds GraphQL-Markdown to an existing documentation site. The Nuxt preset is built on the [`@graphql-markdown/nuxt-theme`](https://github.com/graphql-markdown/graphql-markdown/tree/main/packages/nuxt-theme) layer.
3
+ [![Latest Version](https://img.shields.io/npm/v/create-graphql-markdown-docs?style=flat)](https://www.npmjs.com/package/create-graphql-markdown-docs)
4
+ [![GitHub License](https://img.shields.io/github/license/graphql-markdown/graphql-markdown?style=flat)](https://raw.githubusercontent.com/graphql-markdown/graphql-markdown/main/LICENSE)
5
+
6
+ Interactive CLI that either creates a new [GraphQL-Markdown](https://graphql-markdown.dev) project (a ready-to-run Nuxt or Docusaurus API reference site, or plain Markdown or MDX output) or adds GraphQL-Markdown to an existing documentation site. The Nuxt preset is built on the [`@graphql-markdown/nuxt-theme`](https://www.npmjs.com/package/@graphql-markdown/nuxt-theme) layer.
4
7
 
5
8
  Full guide: [graphql-markdown.dev/docs/get-started](https://graphql-markdown.dev/docs/get-started).
6
9
 
@@ -8,7 +11,7 @@ Full guide: [graphql-markdown.dev/docs/get-started](https://graphql-markdown.dev
8
11
 
9
12
  Run it in an empty or new folder to create a new site, or inside an existing project to add GraphQL-Markdown to it (see [Add to an existing site](#add-to-an-existing-site)):
10
13
 
11
- ```bash
14
+ ```shell
12
15
  npm create graphql-markdown-docs@latest
13
16
  # or pass the project directory directly
14
17
  npm create graphql-markdown-docs@latest my-docs
@@ -27,7 +30,7 @@ To create a new site, follow the interactive prompts to:
27
30
 
28
31
  Run the same command inside a folder that already contains a project. The CLI detects it and adds GraphQL-Markdown to it (wire mode):
29
32
 
30
- ```bash
33
+ ```shell
31
34
  cd my-starlight-site
32
35
  npm create graphql-markdown-docs@latest
33
36
  ```
@@ -39,14 +42,14 @@ In wire mode the CLI:
39
42
  1. Detects the framework from `package.json`, or asks you to choose one (`generic` for anything unlisted).
40
43
  2. Asks for the schema (a path, glob or URL, written as you enter it) and the output folder. The output folder is always asked, never guessed.
41
44
  3. Suggests a link root for the generated pages.
42
- 4. Writes a `.graphqlrc` file and a `docs:api` script that runs `gqlmd graphql-to-doc`.
45
+ 4. Writes a `.graphqlrc` file and a `gqlmd` script that runs `gqlmd graphql-to-doc`.
43
46
  5. Prints the next step for your framework, such as adding a sidebar or navigation entry.
44
47
 
45
48
  It never edits your framework configuration files and never overwrites existing files. If the project already has a GraphQL config, the CLI prints the block to merge into it instead. It installs nothing unless you pass `--install`; otherwise it prints the install command. Use `--dry-run` to see what it would write without writing anything.
46
49
 
47
50
  For CI or scripting, pass the required options and skip the prompts:
48
51
 
49
- ```bash
52
+ ```shell
50
53
  npm create graphql-markdown-docs@latest . -- --yes --schema ./schema.graphql --output src/content/docs/api --install
51
54
  ```
52
55
 
@@ -54,19 +57,20 @@ With `--yes`, `--schema` and `--output` are required, and so is `--framework` wh
54
57
 
55
58
  ### Supported frameworks (existing sites)
56
59
 
57
- | Framework | Typical output folder | Notes |
58
- | --------------- | ---------------------- | --------------------------------------------------------- |
59
- | Docusaurus | `docs/api` | Router links; the suggested link root follows the route. |
60
- | Nuxt | `content/api` | Router links; the suggested link root follows the route. |
61
- | Astro Starlight | `src/content/docs/api` | Set `--site-base` if the site is served under a sub-path. |
62
- | Fumadocs | `content/docs/api` | Router links; the suggested link root follows the route. |
63
- | Vocs | `docs/pages/api` | Router links; the suggested link root follows the route. |
64
- | HonKit | `api` | Set `--site-base` if the site is served under a sub-path. |
65
- | Hugo | `content/api` | Set `--site-base` if the site is served under a sub-path. |
66
- | MkDocs | `docs/api` | Links relative to pages. |
67
- | DocFX | `docs/api` | Links relative to pages. |
68
- | mdBook | `src/api` | Links relative to pages. |
69
- | Generic | Any folder you choose | Any Markdown/MDX site — you set the link root. |
60
+ | Framework | Typical output folder | Notes |
61
+ | --------------- | ---------------------- | ------------------------------------------------------------------------------------ |
62
+ | Docusaurus | `docs/api` | Router links; the suggested link root follows the route. |
63
+ | Nuxt | `content/api` | Router links; the suggested link root follows the route. |
64
+ | Astro Starlight | `src/content/docs/api` | Set `--site-base` if the site is served under a sub-path. |
65
+ | Fumadocs | `content/docs/api` | Router links; the suggested link root follows the route. |
66
+ | Vocs | `docs/pages/api` | Router links; the suggested link root follows the route. |
67
+ | HonKit | `api` | Set `--site-base` if the site is served under a sub-path. |
68
+ | Hugo | `content/api` | Set `--site-base` if the site is served under a sub-path. |
69
+ | MkDocs | `docs/api` | Links relative to pages. |
70
+ | DocFX | `docs/api` | Links relative to pages. |
71
+ | mdBook | `src/api` | Links relative to pages. |
72
+ | Generic MDX | Any folder you choose | Framework-neutral `.mdx` pages (plain HTML, no components); links relative to pages. |
73
+ | Generic | Any folder you choose | Any Markdown/MDX site — you set the link root. |
70
74
 
71
75
  ## Schema sources
72
76
 
@@ -89,7 +93,7 @@ A local SDL/JSON file is copied into the scaffolded project's `schema/` director
89
93
 
90
94
  For CI/CD or scripting, use `--yes`:
91
95
 
92
- ```bash
96
+ ```shell
93
97
  npm create graphql-markdown-docs@latest -- --yes --dir ./my-docs --schema ./schema.graphql --no-install --no-git
94
98
  ```
95
99
 
@@ -97,17 +101,17 @@ npm create graphql-markdown-docs@latest -- --yes --dir ./my-docs --schema ./sche
97
101
 
98
102
  #### Shared
99
103
 
100
- | Flag | Description |
101
- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102
- | `[dir]`, `-d, --dir <path>` | Target folder (default: ask, or the current folder with `--existing`). |
103
- | `--new` \| `--existing` | Force scaffold or wire mode (default: picked from the folder). |
104
- | `--framework <name>` | Scaffold: `nuxt` \| `docusaurus` (default `nuxt`). Wire: `docusaurus` \| `starlight` \| `fumadocs` \| `vocs` \| `honkit` \| `hugo` \| `mkdocs` \| `docfx` \| `mdbook` \| `nuxt` \| `generic`. |
105
- | `--schema <source>` | Schema source: `<path\|url\|git:\|github:>`. See the table above. |
106
- | `--pm <name>` | Package manager: `npm` \| `pnpm` \| `yarn` \| `bun`. Otherwise detected from the invoking command, then from lockfiles. |
107
- | `--install` / `--no-install` | Install dependencies (or skip it). Wire mode installs nothing unless `--install` is passed. |
108
- | `-y, --yes` | Accept defaults and skip all prompts. |
109
- | `-h, --help` | Show usage and exit. |
110
- | `-v, --version` | Print the CLI version and exit. |
104
+ | Flag | Description |
105
+ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
106
+ | `[dir]`, `-d, --dir <path>` | Target folder (default: ask, or the current folder with `--existing`). |
107
+ | `--new` \| `--existing` | Force scaffold or wire mode (default: picked from the folder). |
108
+ | `--framework <name>` | Scaffold: `nuxt` \| `docusaurus` \| `markdown` \| `mdx` (default `nuxt`; `generic` is accepted as `markdown`). Wire: `docusaurus` \| `starlight` \| `fumadocs` \| `vocs` \| `honkit` \| `hugo` \| `mkdocs` \| `docfx` \| `mdbook` \| `nuxt` \| `mdx` \| `generic` (`markdown` is accepted as `generic`). |
109
+ | `--schema <source>` | Schema source: `<path\|url\|git:\|github:>`. See the table above. |
110
+ | `--pm <name>` | Package manager: `npm` \| `pnpm` \| `yarn` \| `bun`. Otherwise detected from the invoking command, then from lockfiles. |
111
+ | `--install` / `--no-install` | Install dependencies (or skip it). Wire mode installs nothing unless `--install` is passed. |
112
+ | `-y, --yes` | Accept defaults and skip all prompts. |
113
+ | `-h, --help` | Show usage and exit. |
114
+ | `-v, --version` | Print the CLI version and exit. |
111
115
 
112
116
  #### Scaffold only
113
117
 
@@ -126,12 +130,14 @@ npm create graphql-markdown-docs@latest -- --yes --dir ./my-docs --schema ./sche
126
130
  | `--output <folder>` | Folder for the generated docs, relative to the project. |
127
131
  | `--link-root <route>` | Route prefix used in generated links. |
128
132
  | `--site-base <route>` | Base path the site is served from. |
129
- | `--script <name>` | `package.json` script to add (default: `docs:api`). |
133
+ | `--script <name>` | `package.json` script to add (default: `gqlmd`). |
130
134
  | `--dry-run` | Show what would be written without writing it. |
131
135
 
132
136
  ## What's included
133
137
 
134
- The scaffolded project is a real, complete Nuxt 4 project:
138
+ ### Nuxt
139
+
140
+ The default scaffold is a complete Nuxt 4 project:
135
141
 
136
142
  - `nuxt.config.ts` — extends `@graphql-markdown/nuxt-theme`, nothing else required.
137
143
  - `content.config.ts` — required in every consuming project (not inherited from the layer — see the theme's own README for why).
@@ -139,7 +145,7 @@ The scaffolded project is a real, complete Nuxt 4 project:
139
145
  - `schema/` — your schema, or the bundled example.
140
146
  - `app/app.config.ts` / `app/pages/index.vue` — a minimal landing page and theme override point, yours to edit.
141
147
 
142
- ## Docusaurus
148
+ ### Docusaurus
143
149
 
144
150
  With `--framework docusaurus`, the scaffold replaces the standalone `graphql-markdown/template` repo:
145
151
 
@@ -150,12 +156,20 @@ With `--framework docusaurus`, the scaffold replaces the standalone `graphql-mar
150
156
 
151
157
  Then run `npm run doc` to generate the docs and `npm start` to serve them.
152
158
 
159
+ ## Telemetry
160
+
161
+ The scaffolder reports one anonymous event per run (scaffold or wire): the framework, mode and schema loader type, with custom strings, URLs and paths masked. No schema content is sent. Nothing is sent on `--dry-run`. The first run shows a notice.
162
+
163
+ Opt out with the `--no-telemetry` flag, `DO_NOT_TRACK=1`, or `gqlmd telemetry disable`. See [what is collected](https://graphql-markdown.dev/docs/telemetry).
164
+
153
165
  ## Documentation
154
166
 
155
- - [`@graphql-markdown/nuxt-theme`](https://github.com/graphql-markdown/graphql-markdown/tree/main/packages/nuxt-theme) — the layer this scaffolds, including the full customization/swizzling reference.
167
+ - [`@graphql-markdown/nuxt-theme`](https://www.npmjs.com/package/@graphql-markdown/nuxt-theme) — the layer this scaffolds, including the full customization/swizzling reference.
156
168
  - [GraphQL-Markdown documentation](https://graphql-markdown.dev)
157
169
  - [Nuxt documentation](https://nuxt.com)
158
170
 
159
171
  ## License
160
172
 
161
- MIT
173
+ GraphQL-Markdown packages are 100% free and open-source, under the [MIT license](https://github.com/graphql-markdown/graphql-markdown/blob/main/LICENSE).
174
+
175
+ This package is [Treeware](https://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/graphql-markdown/graphql-markdown) to thank us for our work. By contributing to the Treeware forest, you'll be creating employment for local families and restoring wildlife habitats.
package/lib/create.mjs CHANGED
@@ -7,6 +7,7 @@ import * as prompts from "@clack/prompts";
7
7
 
8
8
  import {
9
9
  DEFAULT_FRAMEWORK,
10
+ FRAMEWORK_ALIASES,
10
11
  FRAMEWORKS,
11
12
  WIRE_FRAMEWORKS,
12
13
  } from "./frameworks/index.mjs";
@@ -31,10 +32,11 @@ import {
31
32
  isRemoteSchemaSource,
32
33
  validateGraphQLSchema,
33
34
  } from "./schema.mjs";
35
+ import { reportTelemetry } from "./telemetry.mjs";
34
36
  import { WIRE_STEPS, printWireOutro } from "./wire/steps.mjs";
35
37
  import { flagModeError, isEffectivelyEmpty, modeFor } from "./target.mjs";
36
38
  import {
37
- INSTALL_COMMANDS,
39
+ SUPPORTED_PACKAGE_MANAGERS,
38
40
  initGitRepo,
39
41
  installDependencies,
40
42
  isGitAvailable,
@@ -45,6 +47,15 @@ const colorFrameworkNames = Object.values(FRAMEWORKS)
45
47
  .filter((fw) => fw.scaffold.supportsColor)
46
48
  .map((fw) => fw.name);
47
49
 
50
+ const aliasText = [
51
+ ...Object.entries(FRAMEWORK_ALIASES.scaffold).map(
52
+ ([alias, id]) => `${alias} = ${id} (scaffold)`,
53
+ ),
54
+ ...Object.entries(FRAMEWORK_ALIASES.wire).map(
55
+ ([alias, id]) => `${alias} = ${id} (wire)`,
56
+ ),
57
+ ].join(", ");
58
+
48
59
  const HELP_TEXT = `Usage: create-graphql-markdown-docs [dir] [options]
49
60
 
50
61
  An empty or missing folder creates a new project (scaffold); a folder with
@@ -55,9 +66,11 @@ Shared:
55
66
  --new | --existing Force scaffold or wire mode (default: picked from the folder)
56
67
  --framework <name> Scaffold: ${Object.keys(FRAMEWORKS).join(" | ")} (default: ${DEFAULT_FRAMEWORK})
57
68
  Wire: ${Object.keys(WIRE_FRAMEWORKS).join(" | ")}
69
+ Aliases: ${aliasText}
58
70
  --schema <source> Schema source: <path|url|git:|github:>
59
71
  --pm <name> Package manager: npm | pnpm | yarn | bun
60
72
  --install / --no-install Install dependencies (or skip it)
73
+ --no-telemetry Do not send anonymous usage telemetry
61
74
  -y, --yes Accept defaults and skip all prompts
62
75
  -h, --help Show this help
63
76
  -v, --version Show the version
@@ -73,7 +86,7 @@ Wire only:
73
86
  --output <folder> Folder for the generated docs, relative to the project
74
87
  --link-root <route> Route prefix used in generated links
75
88
  --site-base <route> Base path the site is served from
76
- --script <name> package.json script to add (default: docs:api)
89
+ --script <name> package.json script to add (default: gqlmd)
77
90
  --dry-run Show what would be written without writing it
78
91
  `;
79
92
 
@@ -108,6 +121,7 @@ export function parseCliArgs(argv) {
108
121
  script: { type: "string" },
109
122
  "dry-run": { type: "boolean" },
110
123
  "no-git": { type: "boolean" },
124
+ "no-telemetry": { type: "boolean" },
111
125
  yes: { type: "boolean", short: "y" },
112
126
  help: { type: "boolean", short: "h" },
113
127
  version: { type: "boolean", short: "v" },
@@ -128,15 +142,17 @@ export function parseCliArgs(argv) {
128
142
 
129
143
  /** Fails on an unsupported --pm value. */
130
144
  function validatePackageManager(args) {
131
- if (args.pm && !Object.hasOwn(INSTALL_COMMANDS, args.pm)) {
145
+ if (args.pm && !SUPPORTED_PACKAGE_MANAGERS.includes(args.pm)) {
132
146
  fail(
133
- `Invalid --pm "${args.pm}" — expected one of: ${Object.keys(INSTALL_COMMANDS).join(", ")}.`,
147
+ `Invalid --pm "${args.pm}" — expected one of: ${SUPPORTED_PACKAGE_MANAGERS.join(", ")}.`,
134
148
  );
135
149
  }
136
150
  }
137
151
 
138
152
  async function resolveFramework(args) {
139
153
  if (args.framework) {
154
+ const aliases = FRAMEWORK_ALIASES.scaffold;
155
+ if (Object.hasOwn(aliases, args.framework)) return aliases[args.framework];
140
156
  if (
141
157
  !Object.hasOwn(FRAMEWORKS, args.framework) &&
142
158
  Object.hasOwn(WIRE_FRAMEWORKS, args.framework)
@@ -380,6 +396,13 @@ function initialColor(args, fw) {
380
396
  return color;
381
397
  }
382
398
 
399
+ /** Whether the template has nothing to customize (no title, no color). */
400
+ export function hasNoCustomization(fw) {
401
+ return (
402
+ fw.scaffold.supportsTitle === false && fw.scaffold.supportsColor === false
403
+ );
404
+ }
405
+
383
406
  /** Whether the user wants to customize title/color interactively. */
384
407
  async function wantsCustomization(fw) {
385
408
  const answer = unlessCancelled(
@@ -395,6 +418,12 @@ async function wantsCustomization(fw) {
395
418
 
396
419
  /** Optional title and color customization. */
397
420
  async function promptCustomization(args, fw) {
421
+ if (hasNoCustomization(fw)) {
422
+ if (args.title) {
423
+ prompts.log.warn(`--title does not apply to ${fw.name} — ignoring it.`);
424
+ }
425
+ return { title: "", color: initialColor(args, fw) };
426
+ }
398
427
  let title = args.title ?? "";
399
428
  let color = initialColor(args, fw);
400
429
  if (args.yes || !(await wantsCustomization(fw))) {
@@ -468,7 +497,8 @@ const SCAFFOLD_STEPS = [
468
497
  {
469
498
  id: "createProject",
470
499
  title: "Create project",
471
- run(ctx) {
500
+ async run(ctx) {
501
+ await reportTelemetry(ctx);
472
502
  applyTemplate(ctx.tempDir, ctx);
473
503
  moveIntoPlace(ctx.tempDir, ctx.projectDir);
474
504
  prompts.log.success("Project created successfully!");
@@ -52,7 +52,7 @@ export const docusaurus = {
52
52
  contentRoute: "/docs",
53
53
  outputHint: "Docusaurus reads content from docs/",
54
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.`,
55
+ `Add the API docs to a sidebar (e.g. autogenerated from \`${outputDir}\`).`,
56
56
  scaffold: {
57
57
  runScripts: ["doc", "start"],
58
58
  copyExcludes: [],
@@ -1,4 +1,5 @@
1
1
  import { docusaurus } from "./docusaurus.mjs";
2
+ import { markdown, mdx } from "./markdown.mjs";
2
3
  import { nuxt } from "./nuxt.mjs";
3
4
  import {
4
5
  docfx,
@@ -30,10 +31,11 @@ import {
30
31
  */
31
32
 
32
33
  /**
33
- * Supported scaffold targets; each key maps to `templates/<framework>`.
34
+ * Supported scaffold targets; each key maps to `templates/<framework>`, unless
35
+ * `scaffold.template` overrides it (mdx uses the markdown template).
34
36
  * `scaffold.runScripts` are the package scripts to run after install, in order.
35
37
  */
36
- export const FRAMEWORKS = { nuxt, docusaurus };
38
+ export const FRAMEWORKS = { nuxt, docusaurus, markdown, mdx };
37
39
 
38
40
  /** Every framework descriptor available in wire mode, keyed by id. */
39
41
  export const WIRE_FRAMEWORKS = {
@@ -47,7 +49,18 @@ export const WIRE_FRAMEWORKS = {
47
49
  docfx,
48
50
  mdbook,
49
51
  nuxt,
52
+ mdx,
50
53
  generic,
51
54
  };
52
55
 
56
+ /**
57
+ * Accepted `--framework` aliases per mode: alias -> framework id in that mode.
58
+ * Scaffolding has no "generic" template (plain Markdown is its equivalent);
59
+ * wiring has no "markdown" target (generic is its equivalent).
60
+ */
61
+ export const FRAMEWORK_ALIASES = {
62
+ scaffold: { generic: "markdown" },
63
+ wire: { markdown: "generic" },
64
+ };
65
+
53
66
  export const DEFAULT_FRAMEWORK = "nuxt";
@@ -0,0 +1,75 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+
4
+ import { writeGraphqlrc } from "../rewrites/graphqlrc.mjs";
5
+ import { findIndentedLine } from "../rewrites/lines.mjs";
6
+
7
+ const MDX_FORMATTER = "@graphql-markdown/formatters/mdx";
8
+ // Must match the @graphql-markdown/formatters release that ships `./mdx`.
9
+ const FORMATTERS_RANGE = "^1.2.1";
10
+
11
+ /** Adds the mdx formatter to .graphqlrc, right before the `loaders:` line. */
12
+ export function writeMdxFormatter(tempDir) {
13
+ const graphqlrcPath = path.join(tempDir, ".graphqlrc");
14
+ const content = fs.readFileSync(graphqlrcPath, "utf-8");
15
+ const found = findIndentedLine(content, "loaders:");
16
+ if (!found) {
17
+ throw new Error(
18
+ `Expected to find "loaders:" in ${graphqlrcPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
19
+ );
20
+ }
21
+ const { line, indent } = found;
22
+ fs.writeFileSync(
23
+ graphqlrcPath,
24
+ content.replace(
25
+ line,
26
+ () => `${indent}formatter: '${MDX_FORMATTER}'\n${line}`,
27
+ ),
28
+ );
29
+
30
+ const pkgPath = path.join(tempDir, "package.json");
31
+ const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
32
+ pkg.dependencies["@graphql-markdown/formatters"] = FORMATTERS_RANGE;
33
+ fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
34
+ }
35
+
36
+ const nextSteps = ({ outputDir }) =>
37
+ `Point your site navigation at \`${outputDir}\`. Manual wiring guide: https://graphql-markdown.dev`;
38
+
39
+ /** Plain Markdown scaffold descriptor (templates/markdown). */
40
+ export const markdown = {
41
+ id: "markdown",
42
+ name: "Markdown",
43
+ label: "Markdown (plain .md files)",
44
+ hint: "No site — just Markdown files in docs/",
45
+ scaffold: {
46
+ template: "markdown",
47
+ runScripts: ["doc"],
48
+ copyExcludes: [],
49
+ supportsColor: false,
50
+ supportsTitle: false,
51
+ apply(tempDir, { schemaRef, loader }) {
52
+ writeGraphqlrc(tempDir, schemaRef, loader);
53
+ },
54
+ },
55
+ };
56
+
57
+ /** Plain MDX scaffold and wire descriptor (templates/markdown + mdx formatter). */
58
+ export const mdx = {
59
+ ...markdown,
60
+ id: "mdx",
61
+ name: "MDX",
62
+ label: "MDX (plain .mdx files)",
63
+ hint: "Framework-neutral .mdx pages (plain HTML, no components)",
64
+ formatter: MDX_FORMATTER,
65
+ links: "relative",
66
+ contentRoot: "docs",
67
+ nextSteps,
68
+ scaffold: {
69
+ ...markdown.scaffold,
70
+ apply(tempDir, { schemaRef, loader }) {
71
+ writeGraphqlrc(tempDir, schemaRef, loader);
72
+ writeMdxFormatter(tempDir);
73
+ },
74
+ },
75
+ };
package/lib/helpers.mjs CHANGED
@@ -7,7 +7,7 @@ import {
7
7
  } from "package-manager-detector";
8
8
 
9
9
  import { isRemoteSchemaSource } from "./schema.mjs";
10
- import { INSTALL_COMMANDS } from "./tasks.mjs";
10
+ import { SUPPORTED_PACKAGE_MANAGERS } from "./tasks.mjs";
11
11
 
12
12
  export const DOCS_URL = "https://graphql-markdown.dev";
13
13
 
@@ -62,10 +62,10 @@ export function validateSchemaSource(value) {
62
62
  export async function resolvePackageManager(args, cwd = process.cwd()) {
63
63
  if (args.pm) return args.pm;
64
64
  // Set when launched via `<pm> create`, so it reflects what the user ran.
65
- const agent = getUserAgent()?.split("/")[0];
66
- if (agent && Object.hasOwn(INSTALL_COMMANDS, agent)) return agent;
65
+ const agent = getUserAgent();
66
+ if (agent && SUPPORTED_PACKAGE_MANAGERS.includes(agent)) return agent;
67
67
  const detected = await detectPackageManager({ cwd });
68
- if (detected?.name && Object.hasOwn(INSTALL_COMMANDS, detected.name)) {
68
+ if (detected?.name && SUPPORTED_PACKAGE_MANAGERS.includes(detected.name)) {
69
69
  return detected.name;
70
70
  }
71
71
  if (args.yes) return "npm";
package/lib/project.mjs CHANGED
@@ -99,10 +99,11 @@ export function applyTemplate(tempDir, ctx) {
99
99
  const { framework, projectDir, schemaPath, loader, title, color } = ctx;
100
100
  const fw = FRAMEWORKS[framework];
101
101
 
102
- copyDirRecursive(path.join(templatesRoot, framework), tempDir, [
103
- /^node_modules$/,
104
- ...fw.scaffold.copyExcludes,
105
- ]);
102
+ copyDirRecursive(
103
+ path.join(templatesRoot, fw.scaffold.template ?? framework),
104
+ tempDir,
105
+ [/^node_modules$/, ...fw.scaffold.copyExcludes],
106
+ );
106
107
 
107
108
  // npm strips `.gitignore` from published tarballs, so templates ship it as
108
109
  // `gitignore` and it is renamed back here.
package/lib/tasks.mjs CHANGED
@@ -1,36 +1,29 @@
1
1
  import { spawn } from "node:child_process";
2
2
 
3
3
  import * as prompts from "@clack/prompts";
4
+ import { resolveCommand } from "package-manager-detector/commands";
4
5
 
5
6
  /**
6
- * Maps each package manager to its install command and arguments.
7
- * Each entry is [command, args] to be passed to spawn().
7
+ * Package managers supported by the scaffolder.
8
8
  */
9
- export const INSTALL_COMMANDS = {
10
- npm: ["npm", ["install"]],
11
- pnpm: ["pnpm", ["install"]],
12
- yarn: ["yarn", []],
13
- bun: ["bun", ["install"]],
14
- };
9
+ export const SUPPORTED_PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
15
10
 
16
- /**
17
- * Maps each package manager to the command that adds dev dependencies.
18
- * Each entry is [command, args]; the packages are appended to args.
19
- */
20
- const ADD_DEV_COMMANDS = {
21
- npm: ["npm", ["install", "--save-dev"]],
22
- pnpm: ["pnpm", ["add", "--save-dev"]],
23
- yarn: ["yarn", ["add", "--dev"]],
24
- bun: ["bun", ["add", "--dev"]],
25
- };
11
+ function resolveOrNpm(packageManager, intent, args) {
12
+ const agent = SUPPORTED_PACKAGE_MANAGERS.includes(packageManager)
13
+ ? packageManager
14
+ : "npm";
15
+ const resolved = resolveCommand(agent, intent, args);
16
+ if (!resolved) {
17
+ throw new Error(`Unsupported ${intent} command for ${agent}`);
18
+ }
19
+ return [resolved.command, resolved.args];
20
+ }
26
21
 
27
22
  function addDevArgs(packageManager, packages, { workspaceRoot = false } = {}) {
28
- const [command, args] =
29
- ADD_DEV_COMMANDS[packageManager] ?? ADD_DEV_COMMANDS.npm;
30
23
  const rootFlag = workspaceRoot
31
24
  ? ({ pnpm: ["-w"], yarn: ["-W"] }[packageManager] ?? [])
32
25
  : [];
33
- return [command, [...args, ...rootFlag, ...packages]];
26
+ return resolveOrNpm(packageManager, "add", ["-D", ...rootFlag, ...packages]);
34
27
  }
35
28
 
36
29
  /**
@@ -73,14 +66,13 @@ export async function isGitAvailable() {
73
66
  */
74
67
  export async function installDependencies(packageManager, projectDir) {
75
68
  prompts.log.info(`Installing dependencies with ${packageManager}...`);
76
- const [command, args] =
77
- INSTALL_COMMANDS[packageManager] ?? INSTALL_COMMANDS.npm;
69
+ const [command, args] = resolveOrNpm(packageManager, "install", []);
78
70
  await runCommand(command, args, { cwd: projectDir });
79
71
  prompts.log.success("Dependencies installed!");
80
72
  }
81
73
 
82
74
  /**
83
- * Command line that adds packages as dev dependencies, e.g. "bun add --dev a b".
75
+ * Command line that adds packages as dev dependencies, e.g. "bun add -D a b".
84
76
  * @param {string} packageManager
85
77
  * @param {string[]} packages
86
78
  * @returns {string}
@@ -0,0 +1,46 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+
4
+ import { note } from "@clack/prompts";
5
+ import { track } from "@graphql-markdown/telemetry";
6
+
7
+ import { packageRoot } from "./project.mjs";
8
+ import { EXAMPLE_SCHEMA_REF } from "./schema.mjs";
9
+
10
+ const PKG_NAME = "create-graphql-markdown-docs";
11
+
12
+ /** The prompt answers worth reporting; the telemetry package masks custom values. */
13
+ function configFor(ctx) {
14
+ if (ctx.mode === "wire") {
15
+ return { schema: ctx.schemaRef, linkRoot: ctx.linkRoot };
16
+ }
17
+ return { schema: ctx.schemaPath ?? EXAMPLE_SCHEMA_REF };
18
+ }
19
+
20
+ /**
21
+ * Reports one anonymous create event (`create_scaffold` or `create_wire`).
22
+ * Never throws: telemetry must not affect a run. The full notice is shown
23
+ * as a clack note written to stderr, so stdout stays clean. Nothing is sent on `--dry-run`.
24
+ */
25
+ export async function reportTelemetry(ctx) {
26
+ if (ctx.args?.["dry-run"]) return;
27
+ try {
28
+ const { version } = JSON.parse(
29
+ fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8"),
30
+ );
31
+ await track({
32
+ event: ctx.mode === "wire" ? "create_wire" : "create_scaffold",
33
+ trigger: "create",
34
+ pkg: PKG_NAME,
35
+ pkgVersion: version,
36
+ target: ctx.framework,
37
+ mode: ctx.mode,
38
+ config: configFor(ctx),
39
+ option: ctx.args["no-telemetry"] ? false : undefined,
40
+ onFullNotice: (notice) =>
41
+ note(notice, "Telemetry", { output: process.stderr }),
42
+ });
43
+ } catch {
44
+ // telemetry must never affect a run
45
+ }
46
+ }
package/lib/wire/plan.mjs CHANGED
@@ -36,7 +36,7 @@ const GRAPHQL_CONFIG_FILES = [
36
36
  /**
37
37
  * Inspect a project directory for package.json and an existing GraphQL config.
38
38
  * @param {string} projectDir
39
- * @returns {{ packageJson: object | null, packageJsonIndent: string | number, existingConfig: string | null }}
39
+ * @returns {{ packageJson: object | null, packageJsonIndent: string | number, existingConfig: string | null, workspaceRoot: boolean, pnpmWorkspace: boolean, yarnBerry: boolean }}
40
40
  */
41
41
  export function inspectProject(projectDir) {
42
42
  let packageJson = null;
@@ -56,10 +56,21 @@ export function inspectProject(projectDir) {
56
56
  if (!existingConfig && packageJson && "graphql" in packageJson) {
57
57
  existingConfig = "package.json#graphql";
58
58
  }
59
+ const pnpmWorkspace = fs.existsSync(
60
+ path.join(projectDir, "pnpm-workspace.yaml"),
61
+ );
62
+ const workspaceRoot =
63
+ Boolean(packageJson && "workspaces" in packageJson) || pnpmWorkspace;
64
+ const yarnBerry =
65
+ fs.existsSync(path.join(projectDir, ".yarnrc.yml")) ||
66
+ /^yarn@(?:[2-9]|\d{2,})\./.test(packageJson?.packageManager ?? "");
59
67
  return {
60
68
  packageJson,
61
69
  packageJsonIndent,
62
70
  existingConfig: existingConfig ?? null,
71
+ workspaceRoot,
72
+ pnpmWorkspace,
73
+ yarnBerry,
63
74
  };
64
75
  }
65
76
 
@@ -155,6 +166,9 @@ export function buildGraphqlrc({
155
166
  };
156
167
  }
157
168
 
169
+ /** Default package.json script added in wire mode; namespaced to avoid clashes. */
170
+ export const DEFAULT_SCRIPT_NAME = "gqlmd";
171
+
158
172
  /**
159
173
  * Plan the files and package.json changes needed to wire a project.
160
174
  * @param {object} inputs Arguments for buildGraphqlrc.
@@ -162,7 +176,11 @@ export function buildGraphqlrc({
162
176
  * @param {{ scriptName?: string }} [options]
163
177
  * @returns {{ files: { path: string, content: string }[], mergeBlock?: string, script: object, warnings: string[] }}
164
178
  */
165
- export function planWire(inputs, project, { scriptName = "docs:api" } = {}) {
179
+ export function planWire(
180
+ inputs,
181
+ project,
182
+ { scriptName = DEFAULT_SCRIPT_NAME } = {},
183
+ ) {
166
184
  const config = buildGraphqlrc(inputs);
167
185
  const warnings = [];
168
186
  let files = [];
@@ -4,7 +4,7 @@ import path from "node:path";
4
4
 
5
5
  import * as prompts from "@clack/prompts";
6
6
 
7
- import { WIRE_FRAMEWORKS } from "../frameworks/index.mjs";
7
+ import { FRAMEWORK_ALIASES, WIRE_FRAMEWORKS } from "../frameworks/index.mjs";
8
8
  import { normalizeOutput, suggestLinkRoot } from "../frameworks/links.mjs";
9
9
  import {
10
10
  DOCS_URL,
@@ -14,12 +14,14 @@ import {
14
14
  unlessCancelled,
15
15
  validateSchemaSource,
16
16
  } from "../helpers.mjs";
17
+ import { reportTelemetry } from "../telemetry.mjs";
17
18
  import { detectLoader } from "../schema.mjs";
18
19
  import { addDevCommand, addDevDependencies } from "../tasks.mjs";
19
20
  import { detectFrameworks, toSchemaRef } from "../target.mjs";
20
21
  import { requiredPackages } from "./deps.mjs";
21
22
  import {
22
23
  applyWirePlan,
24
+ DEFAULT_SCRIPT_NAME,
23
25
  formatWirePlan,
24
26
  inspectProject,
25
27
  planWire,
@@ -70,6 +72,8 @@ async function resolveWireFramework(ctx) {
70
72
  const { args, detected } = ctx;
71
73
  const requested = requestedFramework(args);
72
74
  if (requested) {
75
+ const aliases = FRAMEWORK_ALIASES.wire;
76
+ if (Object.hasOwn(aliases, requested)) return aliases[requested];
73
77
  if (!Object.hasOwn(WIRE_FRAMEWORKS, requested)) {
74
78
  fail(
75
79
  `Invalid --framework "${requested}" — expected one of: ${Object.keys(WIRE_FRAMEWORKS).join(", ")}.`,
@@ -205,7 +209,8 @@ function planDependencies(ctx) {
205
209
  }
206
210
  }
207
211
 
208
- function writePlan(ctx) {
212
+ async function writePlan(ctx) {
213
+ await reportTelemetry(ctx);
209
214
  const { args, projectDir, project, descriptor } = ctx;
210
215
  const plan = planWire(
211
216
  {
@@ -244,7 +249,7 @@ export const WIRE_STEPS = [
244
249
  run(ctx) {
245
250
  ctx.project = inspectProject(ctx.projectDir);
246
251
  ctx.detected = detectFrameworks(ctx.project.packageJson);
247
- ctx.scriptName = ctx.args.script || "docs:api";
252
+ ctx.scriptName = ctx.args.script || DEFAULT_SCRIPT_NAME;
248
253
  preflight(ctx);
249
254
  },
250
255
  },
@@ -280,19 +285,40 @@ export const WIRE_STEPS = [
280
285
  when: (ctx) =>
281
286
  Boolean(ctx.args.install) && !ctx.args["dry-run"] && needsInstall(ctx),
282
287
  run: (ctx) =>
283
- addDevDependencies(ctx.packageManager, ctx.projectDir, ctx.packages),
288
+ addDevDependencies(
289
+ ctx.packageManager,
290
+ ctx.projectDir,
291
+ ctx.packages,
292
+ addDevOptions(ctx),
293
+ ),
284
294
  catchUp: (ctx) =>
285
295
  needsInstall(ctx)
286
- ? [addDevCommand(ctx.packageManager, ctx.packages)]
296
+ ? [addDevCommand(ctx.packageManager, ctx.packages, addDevOptions(ctx))]
287
297
  : [],
288
298
  },
289
299
  ];
290
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
+
291
313
  /** Prints the closing summary for wire mode; `outcomes` are the step results. */
292
314
  export function printWireOutro(ctx, outcomes = []) {
293
315
  if (ctx.args["dry-run"]) {
294
316
  if (needsInstall(ctx)) {
295
- const command = addDevCommand(ctx.packageManager, ctx.packages);
317
+ const command = addDevCommand(
318
+ ctx.packageManager,
319
+ ctx.packages,
320
+ addDevOptions(ctx),
321
+ );
296
322
  prompts.log.info(
297
323
  ctx.args.install
298
324
  ? `Would install: ${command}`
@@ -306,7 +332,7 @@ export function printWireOutro(ctx, outcomes = []) {
306
332
  const hasScript = plan.script.name || plan.script.skipped?.includes("exists");
307
333
  const generate = hasScript
308
334
  ? `${ctx.packageManager} run ${scriptName}`
309
- : "npx -p @graphql-markdown/cli gqlmd graphql-to-doc";
335
+ : "npx -p @graphql-markdown/cli@latest gqlmd graphql-to-doc";
310
336
  // Commands for steps that did not finish (e.g. the install), then the generate step.
311
337
  const catchUp = outcomes
312
338
  .filter((outcome) => outcome.status !== "done" && outcome.catchUp)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-graphql-markdown-docs",
3
- "version": "1.0.0",
3
+ "version": "1.1.1",
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",
@@ -32,8 +32,8 @@
32
32
  "build": "echo \"no build step — bin/, lib/ and templates/ ship as source\"",
33
33
  "lint": "eslint --config ../../packages/tooling-config/eslint/config.ts \"bin/**/*.mjs\" \"lib/**/*.mjs\" \"tests/**/*.ts\"",
34
34
  "lint:fix": "eslint --config ../../packages/tooling-config/eslint/config.ts \"bin/**/*.mjs\" \"lib/**/*.mjs\" \"tests/**/*.ts\" --fix",
35
- "prettier": "prettier \"bin/**/*.mjs\" \"lib/**/*.mjs\" \"tests/**/*.ts\" --check",
36
- "prettier:fix": "prettier \"bin/**/*.mjs\" \"lib/**/*.mjs\" \"tests/**/*.ts\" --write",
35
+ "prettier": "prettier \"bin/**/*.mjs\" \"lib/**/*.mjs\" \"tests/**/*.ts\" README.md --check",
36
+ "prettier:fix": "prettier \"bin/**/*.mjs\" \"lib/**/*.mjs\" \"tests/**/*.ts\" README.md --write",
37
37
  "test": "vitest run --passWithNoTests",
38
38
  "test:unit": "vitest run --passWithNoTests tests/unit",
39
39
  "test:integration": "vitest run --passWithNoTests tests/integration",
@@ -47,14 +47,15 @@
47
47
  ],
48
48
  "dependencies": {
49
49
  "@clack/prompts": "^1.0.0",
50
- "graphql": "^16.8.0",
51
- "package-manager-detector": "^1.0.0"
50
+ "@graphql-markdown/telemetry": "^0.1.1",
51
+ "graphql": "^16.8.0 || ^17.0.0",
52
+ "package-manager-detector": "^1.8.0"
52
53
  },
53
54
  "devDependencies": {
54
55
  "@graphql-markdown/tooling-config": "^1.0.0"
55
56
  },
56
57
  "engines": {
57
- "node": ">=22.12.0"
58
+ "node": ">=22.18.0"
58
59
  },
59
60
  "publishConfig": {
60
61
  "access": "public"
@@ -15,11 +15,11 @@
15
15
  "dependencies": {
16
16
  "@docusaurus/core": "^3.10.0",
17
17
  "@docusaurus/preset-classic": "^3.10.0",
18
- "@graphql-markdown/docusaurus": "^1.38.1",
19
- "@graphql-tools/graphql-file-loader": "^8.0.0",
18
+ "@graphql-markdown/docusaurus": "^1.39.1",
19
+ "@graphql-tools/graphql-file-loader": "^8.1.21 || ^9.0.6",
20
20
  "@mdx-js/react": "^3.1.1",
21
- "graphql": "^16.13.2",
22
- "graphql-config": "^5.1.6",
21
+ "graphql": "^16.13.2 || ^17.0.0",
22
+ "graphql-config": "^6.0.0",
23
23
  "prism-react-renderer": "^2.4.1",
24
24
  "react": "^19.0.0",
25
25
  "react-dom": "^19.0.0"
@@ -37,7 +37,7 @@
37
37
  ]
38
38
  },
39
39
  "engines": {
40
- "node": ">=20.0"
40
+ "node": ">=22.18.0"
41
41
  },
42
42
  "overrides": {
43
43
  "webpackbar": "^7.0.0"
@@ -0,0 +1,9 @@
1
+ schema: './schema/example.graphql'
2
+ extensions:
3
+ graphql-markdown:
4
+ rootPath: './docs'
5
+ baseURL: '.'
6
+ loaders:
7
+ GraphQLFileLoader: '@graphql-tools/graphql-file-loader'
8
+ printTypeOptions:
9
+ deprecated: 'group'
@@ -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.1",
9
+ "@graphql-tools/graphql-file-loader": "^8.1.21 || ^9.0.6",
10
+ "graphql": "^16.13.2 || ^17.0.0",
11
+ "graphql-config": "^6.0.0"
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
+ }
@@ -11,15 +11,15 @@
11
11
  "preview": "nuxi preview"
12
12
  },
13
13
  "dependencies": {
14
- "@graphql-markdown/nuxt-theme": "^0.1.3",
14
+ "@graphql-markdown/nuxt-theme": "^0.2.1",
15
15
  "@nuxt/content": "^3.16.0",
16
16
  "@nuxt/ui": "^4.11.0",
17
17
  "better-sqlite3": "^13.0.3",
18
- "nuxt": "^4.5.2",
18
+ "nuxt": "^4.6.0",
19
19
  "tailwindcss": "^4.3.3"
20
20
  },
21
21
  "devDependencies": {},
22
22
  "engines": {
23
- "node": ">=22.12.0"
23
+ "node": ">=22.18.0"
24
24
  }
25
25
  }