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 +49 -35
- package/lib/create.mjs +35 -5
- package/lib/frameworks/docusaurus.mjs +1 -1
- package/lib/frameworks/index.mjs +15 -2
- package/lib/frameworks/markdown.mjs +75 -0
- package/lib/helpers.mjs +4 -4
- package/lib/project.mjs +5 -4
- package/lib/tasks.mjs +16 -24
- package/lib/telemetry.mjs +46 -0
- package/lib/wire/plan.mjs +20 -2
- package/lib/wire/steps.mjs +33 -7
- package/package.json +7 -6
- package/templates/docusaurus/package.json +5 -5
- 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/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
# create-graphql-markdown-docs
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/create-graphql-markdown-docs)
|
|
4
|
+
[](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
|
-
```
|
|
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
|
-
```
|
|
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 `
|
|
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
|
-
```
|
|
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
|
|
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
|
-
```
|
|
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: `
|
|
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
|
-
|
|
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
|
-
|
|
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://
|
|
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
|
-
|
|
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:
|
|
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 && !
|
|
145
|
+
if (args.pm && !SUPPORTED_PACKAGE_MANAGERS.includes(args.pm)) {
|
|
132
146
|
fail(
|
|
133
|
-
`Invalid --pm "${args.pm}" — expected one of: ${
|
|
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}\`)
|
|
55
|
+
`Add the API docs to a sidebar (e.g. autogenerated from \`${outputDir}\`).`,
|
|
56
56
|
scaffold: {
|
|
57
57
|
runScripts: ["doc", "start"],
|
|
58
58
|
copyExcludes: [],
|
package/lib/frameworks/index.mjs
CHANGED
|
@@ -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 {
|
|
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()
|
|
66
|
-
if (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 &&
|
|
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(
|
|
103
|
-
|
|
104
|
-
|
|
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
|
-
*
|
|
7
|
-
* Each entry is [command, args] to be passed to spawn().
|
|
7
|
+
* Package managers supported by the scaffolder.
|
|
8
8
|
*/
|
|
9
|
-
export const
|
|
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
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
const
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
|
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
|
|
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(
|
|
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 = [];
|
package/lib/wire/steps.mjs
CHANGED
|
@@ -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 ||
|
|
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(
|
|
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(
|
|
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.
|
|
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": "^
|
|
51
|
-
"
|
|
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.
|
|
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.
|
|
19
|
-
"@graphql-tools/graphql-file-loader": "^8.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": "^
|
|
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": ">=
|
|
40
|
+
"node": ">=22.18.0"
|
|
41
41
|
},
|
|
42
42
|
"overrides": {
|
|
43
43
|
"webpackbar": "^7.0.0"
|
|
@@ -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
|
|
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.
|
|
18
|
+
"nuxt": "^4.6.0",
|
|
19
19
|
"tailwindcss": "^4.3.3"
|
|
20
20
|
},
|
|
21
21
|
"devDependencies": {},
|
|
22
22
|
"engines": {
|
|
23
|
-
"node": ">=22.
|
|
23
|
+
"node": ">=22.18.0"
|
|
24
24
|
}
|
|
25
25
|
}
|