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
package/README.md
CHANGED
|
@@ -1,36 +1,90 @@
|
|
|
1
1
|
# create-graphql-markdown-docs
|
|
2
2
|
|
|
3
|
-
Interactive
|
|
3
|
+
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://github.com/graphql-markdown/graphql-markdown/tree/main/packages/nuxt-theme) layer.
|
|
4
|
+
|
|
5
|
+
Full guide: [graphql-markdown.dev/docs/get-started](https://graphql-markdown.dev/docs/get-started).
|
|
4
6
|
|
|
5
7
|
## Quick start
|
|
6
8
|
|
|
9
|
+
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
|
+
|
|
7
11
|
```bash
|
|
8
12
|
npm create graphql-markdown-docs@latest
|
|
13
|
+
# or pass the project directory directly
|
|
14
|
+
npm create graphql-markdown-docs@latest my-docs
|
|
9
15
|
```
|
|
10
16
|
|
|
11
|
-
|
|
17
|
+
To create a new site, follow the interactive prompts to:
|
|
12
18
|
|
|
13
|
-
1. Choose a project directory
|
|
19
|
+
1. Choose a project directory — press Enter to accept `my-graphql-docs`. It must not exist yet or must be empty; a non-empty directory is rejected and you're asked again.
|
|
14
20
|
2. Provide a GraphQL schema, or use the bundled example.
|
|
15
21
|
3. Confirm the package manager (auto-detected from how you invoked the command; only asked if detection fails).
|
|
16
22
|
4. Optionally customize the site title and primary color.
|
|
17
23
|
5. Install dependencies.
|
|
18
|
-
6. Initialize a git repository.
|
|
24
|
+
6. Initialize a git repository (skipped when the project is already inside one, e.g. a monorepo).
|
|
25
|
+
|
|
26
|
+
## Add to an existing site
|
|
27
|
+
|
|
28
|
+
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
|
+
|
|
30
|
+
```bash
|
|
31
|
+
cd my-starlight-site
|
|
32
|
+
npm create graphql-markdown-docs@latest
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
If you run the command without a directory inside a non-empty folder, it asks whether to add GraphQL-Markdown to this project or create a new one in a subfolder. `--new` and `--existing` force one mode or the other.
|
|
36
|
+
|
|
37
|
+
In wire mode the CLI:
|
|
38
|
+
|
|
39
|
+
1. Detects the framework from `package.json`, or asks you to choose one (`generic` for anything unlisted).
|
|
40
|
+
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
|
+
3. Suggests a link root for the generated pages.
|
|
42
|
+
4. Writes a `.graphqlrc` file and a `gqlmd` script that runs `gqlmd graphql-to-doc`.
|
|
43
|
+
5. Prints the next step for your framework, such as adding a sidebar or navigation entry.
|
|
44
|
+
|
|
45
|
+
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
|
+
|
|
47
|
+
For CI or scripting, pass the required options and skip the prompts:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
npm create graphql-markdown-docs@latest . -- --yes --schema ./schema.graphql --output src/content/docs/api --install
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
With `--yes`, `--schema` and `--output` are required, and so is `--framework` when the framework cannot be detected from `package.json`.
|
|
54
|
+
|
|
55
|
+
### Supported frameworks (existing sites)
|
|
56
|
+
|
|
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 MDX | Any folder you choose | Framework-neutral `.mdx` pages (plain HTML, no components); links relative to pages. |
|
|
70
|
+
| Generic | Any folder you choose | Any Markdown/MDX site — you set the link root. |
|
|
19
71
|
|
|
20
72
|
## Schema sources
|
|
21
73
|
|
|
22
74
|
Point `--schema` (or the equivalent prompt) at any of the following — the CLI detects which [graphql-tools loader](https://github.com/ardatan/graphql-tools/tree/master/packages/loaders) it needs and adds that dependency to the scaffolded project automatically:
|
|
23
75
|
|
|
24
|
-
| Schema source
|
|
25
|
-
|
|
|
26
|
-
| Local `.graphql`/`.gql` file
|
|
27
|
-
| Local `.json` introspection result | `./introspection.json`
|
|
28
|
-
| Local code-first schema
|
|
29
|
-
| Introspection/SDL endpoint
|
|
30
|
-
| Git-hosted file
|
|
31
|
-
| GitHub-hosted file
|
|
76
|
+
| Schema source | Example | Loader added |
|
|
77
|
+
| ---------------------------------- | ---------------------------------------------- | --------------------------------------------------------- |
|
|
78
|
+
| Local `.graphql`/`.gql` file | `./schema/api.graphql` | None — `@graphql-markdown/nuxt-theme`'s built-in default. |
|
|
79
|
+
| Local `.json` introspection result | `./introspection.json` | `@graphql-tools/json-file-loader` |
|
|
80
|
+
| Local code-first schema | `./schema.ts` | `@graphql-tools/code-file-loader` |
|
|
81
|
+
| Introspection/SDL endpoint | `https://api.example.com/graphql` | `@graphql-tools/url-loader` |
|
|
82
|
+
| Git-hosted file | `git:branch:path/schema.graphql` | `@graphql-tools/git-loader` |
|
|
83
|
+
| GitHub-hosted file | `github:owner/repo#branch:path/schema.graphql` | `@graphql-tools/github-loader` |
|
|
84
|
+
|
|
85
|
+
`github:` sources call the GitHub API and need a token: set the `GITHUB_TOKEN` environment variable before generating the docs (the scaffolded config reads it).
|
|
32
86
|
|
|
33
|
-
A local file is copied into the scaffolded project's `schema/` directory; a remote source is referenced as-is, with no local file to copy.
|
|
87
|
+
A local SDL/JSON file is copied into the scaffolded project's `schema/` directory; a remote source is referenced as-is, with no local file to copy. For Nuxt, `generate-docs.ts` is rewritten to match and `nuxt.config.ts`'s `watch` entry points at the local file (or is removed for a remote source); for Docusaurus, `.graphqlrc` is rewritten. Local code-first schemas are referenced in place rather than copied, so their imports keep working.
|
|
34
88
|
|
|
35
89
|
## Non-interactive mode
|
|
36
90
|
|
|
@@ -42,18 +96,39 @@ npm create graphql-markdown-docs@latest -- --yes --dir ./my-docs --schema ./sche
|
|
|
42
96
|
|
|
43
97
|
### Flags
|
|
44
98
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
|
48
|
-
|
|
|
49
|
-
|
|
|
50
|
-
| `--
|
|
51
|
-
| `--
|
|
52
|
-
| `--
|
|
53
|
-
| `--
|
|
54
|
-
| `--no-install` |
|
|
55
|
-
|
|
|
56
|
-
|
|
|
99
|
+
#### Shared
|
|
100
|
+
|
|
101
|
+
| Flag | Description |
|
|
102
|
+
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
103
|
+
| `[dir]`, `-d, --dir <path>` | Target folder (default: ask, or the current folder with `--existing`). |
|
|
104
|
+
| `--new` \| `--existing` | Force scaffold or wire mode (default: picked from the folder). |
|
|
105
|
+
| `--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`). |
|
|
106
|
+
| `--schema <source>` | Schema source: `<path\|url\|git:\|github:>`. See the table above. |
|
|
107
|
+
| `--pm <name>` | Package manager: `npm` \| `pnpm` \| `yarn` \| `bun`. Otherwise detected from the invoking command, then from lockfiles. |
|
|
108
|
+
| `--install` / `--no-install` | Install dependencies (or skip it). Wire mode installs nothing unless `--install` is passed. |
|
|
109
|
+
| `-y, --yes` | Accept defaults and skip all prompts. |
|
|
110
|
+
| `-h, --help` | Show usage and exit. |
|
|
111
|
+
| `-v, --version` | Print the CLI version and exit. |
|
|
112
|
+
|
|
113
|
+
#### Scaffold only
|
|
114
|
+
|
|
115
|
+
| Flag | Description |
|
|
116
|
+
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
117
|
+
| `--example` | Use the bundled example schema (the default when `--schema` is omitted). |
|
|
118
|
+
| `--title <text>` | Site title (Nuxt: `app.config.ts`'s `gqlmd.siteTitle`; Docusaurus: `docusaurus.config.js`'s `title` and navbar title). |
|
|
119
|
+
| `--color <name>` | Primary color, Nuxt only (ignored with a warning for Docusaurus). Any Nuxt UI / Tailwind color name (e.g. `violet`, `emerald`, `blue`). Sets `app.config.ts`'s `ui.colors.primary`. |
|
|
120
|
+
| `--no-git` | Skip git repository initialization. |
|
|
121
|
+
|
|
122
|
+
#### Wire only
|
|
123
|
+
|
|
124
|
+
| Flag | Description |
|
|
125
|
+
| --------------------- | ------------------------------------------------------------------------- |
|
|
126
|
+
| `--formatter <name>` | Formatter module or path (default: the framework's own formatter preset). |
|
|
127
|
+
| `--output <folder>` | Folder for the generated docs, relative to the project. |
|
|
128
|
+
| `--link-root <route>` | Route prefix used in generated links. |
|
|
129
|
+
| `--site-base <route>` | Base path the site is served from. |
|
|
130
|
+
| `--script <name>` | `package.json` script to add (default: `gqlmd`). |
|
|
131
|
+
| `--dry-run` | Show what would be written without writing it. |
|
|
57
132
|
|
|
58
133
|
## What's included
|
|
59
134
|
|
|
@@ -76,9 +151,15 @@ With `--framework docusaurus`, the scaffold replaces the standalone `graphql-mar
|
|
|
76
151
|
|
|
77
152
|
Then run `npm run doc` to generate the docs and `npm start` to serve them.
|
|
78
153
|
|
|
154
|
+
## Telemetry
|
|
155
|
+
|
|
156
|
+
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.
|
|
157
|
+
|
|
158
|
+
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).
|
|
159
|
+
|
|
79
160
|
## Documentation
|
|
80
161
|
|
|
81
|
-
- [`@graphql-markdown/nuxt-theme`](
|
|
162
|
+
- [`@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.
|
|
82
163
|
- [GraphQL-Markdown documentation](https://graphql-markdown.dev)
|
|
83
164
|
- [Nuxt documentation](https://nuxt.com)
|
|
84
165
|
|