create-graphql-markdown-docs 0.1.1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,36 +1,89 @@
1
1
  # create-graphql-markdown-docs
2
2
 
3
- Interactive scaffolding CLI that generates a ready-to-run [GraphQL Markdown](https://graphql-markdown.dev) + Nuxt or Docusaurus API reference site; the Nuxt preset is built on the [`@graphql-markdown/nuxt-theme`](../nuxt-theme) layer.
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.
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
- Follow the interactive prompts to:
17
+ To create a new site, follow the interactive prompts to:
12
18
 
13
- 1. Choose a project directory (must not already exist, or must be empty — the CLI refuses to touch a non-empty 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 `docs:api` 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 | Any folder you choose | Any Markdown/MDX site — you set the link root. |
19
70
 
20
71
  ## Schema sources
21
72
 
22
73
  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
74
 
24
- | Schema source | Example | Loader added |
25
- | --- | --- | --- |
26
- | Local `.graphql`/`.gql` file | `./schema/api.graphql` | None — `@graphql-markdown/nuxt-theme`'s built-in default. |
27
- | Local `.json` introspection result | `./introspection.json` | `@graphql-tools/json-file-loader` |
28
- | Local code-first schema | `./schema.ts` | `@graphql-tools/code-file-loader` |
29
- | Introspection/SDL endpoint | `https://api.example.com/graphql` | `@graphql-tools/url-loader` |
30
- | Git-hosted file | `git:branch:path/schema.graphql` | `@graphql-tools/git-loader` |
31
- | GitHub-hosted file | `github:owner/repo#branch:path/schema.graphql` | `@graphql-tools/github-loader` |
75
+ | Schema source | Example | Loader added |
76
+ | ---------------------------------- | ---------------------------------------------- | --------------------------------------------------------- |
77
+ | Local `.graphql`/`.gql` file | `./schema/api.graphql` | None — `@graphql-markdown/nuxt-theme`'s built-in default. |
78
+ | Local `.json` introspection result | `./introspection.json` | `@graphql-tools/json-file-loader` |
79
+ | Local code-first schema | `./schema.ts` | `@graphql-tools/code-file-loader` |
80
+ | Introspection/SDL endpoint | `https://api.example.com/graphql` | `@graphql-tools/url-loader` |
81
+ | Git-hosted file | `git:branch:path/schema.graphql` | `@graphql-tools/git-loader` |
82
+ | GitHub-hosted file | `github:owner/repo#branch:path/schema.graphql` | `@graphql-tools/github-loader` |
83
+
84
+ `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
85
 
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. Either way, `generate-docs.ts` and `nuxt.config.ts`'s `watch` entry are both written to match — never left pointing at the bundled `schema/example.graphql` once a real schema is provided.
86
+ 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
87
 
35
88
  ## Non-interactive mode
36
89
 
@@ -42,18 +95,39 @@ npm create graphql-markdown-docs@latest -- --yes --dir ./my-docs --schema ./sche
42
95
 
43
96
  ### Flags
44
97
 
45
- | Flag | Description |
46
- | --- | --- |
47
- | `--framework <nuxt\|docusaurus>` | Framework preset. Default `nuxt`; asked first in interactive mode when omitted. |
48
- | `--dir <path>` | Project directory. Default `./my-graphql-docs`. Must not already exist and be non-empty — the CLI exits with an error rather than overwrite anything. |
49
- | `--schema <path-or-url>` | Schema source — see the table above. |
50
- | `--example` | Use the bundled example schema (the default when `--schema` is omitted). |
51
- | `--pm <npm\|pnpm\|yarn\|bun>` | Package manager to use; otherwise auto-detected. |
52
- | `--title <name>` | Site title (Nuxt: `app.config.ts`'s `gqlmd.siteTitle`; Docusaurus: `docusaurus.config.js`'s `title`). |
53
- | `--color <name>` | Nuxt only (ignored with a warning for Docusaurus). Primary color — any Nuxt UI / Tailwind color name (e.g. `violet`, `emerald`, `blue`). Sets `app.config.ts`'s `ui.colors.primary`. |
54
- | `--no-install` | Skip dependency installation. |
55
- | `--no-git` | Skip git repository initialization. |
56
- | `--yes` | Accept all defaults; fully non-interactive. |
98
+ #### Shared
99
+
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. |
111
+
112
+ #### Scaffold only
113
+
114
+ | Flag | Description |
115
+ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
116
+ | `--example` | Use the bundled example schema (the default when `--schema` is omitted). |
117
+ | `--title <text>` | Site title (Nuxt: `app.config.ts`'s `gqlmd.siteTitle`; Docusaurus: `docusaurus.config.js`'s `title` and navbar title). |
118
+ | `--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`. |
119
+ | `--no-git` | Skip git repository initialization. |
120
+
121
+ #### Wire only
122
+
123
+ | Flag | Description |
124
+ | --------------------- | ------------------------------------------------------------------------- |
125
+ | `--formatter <name>` | Formatter module or path (default: the framework's own formatter preset). |
126
+ | `--output <folder>` | Folder for the generated docs, relative to the project. |
127
+ | `--link-root <route>` | Route prefix used in generated links. |
128
+ | `--site-base <route>` | Base path the site is served from. |
129
+ | `--script <name>` | `package.json` script to add (default: `docs:api`). |
130
+ | `--dry-run` | Show what would be written without writing it. |
57
131
 
58
132
  ## What's included
59
133
 
@@ -78,7 +152,7 @@ Then run `npm run doc` to generate the docs and `npm start` to serve them.
78
152
 
79
153
  ## Documentation
80
154
 
81
- - [`@graphql-markdown/nuxt-theme`](../nuxt-theme) — the layer this scaffolds, including the full customization/swizzling reference.
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.
82
156
  - [GraphQL-Markdown documentation](https://graphql-markdown.dev)
83
157
  - [Nuxt documentation](https://nuxt.com)
84
158