create-graphql-markdown-docs 0.0.0-stage → 0.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,3 +1,87 @@
1
- # Temporary Holding Version
1
+ # create-graphql-markdown-docs
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.
4
+
5
+ ## Quick start
6
+
7
+ ```bash
8
+ npm create graphql-markdown-docs@latest
9
+ ```
10
+
11
+ Follow the interactive prompts to:
12
+
13
+ 1. Choose a project directory (must not already exist, or must be empty — the CLI refuses to touch a non-empty directory).
14
+ 2. Provide a GraphQL schema, or use the bundled example.
15
+ 3. Confirm the package manager (auto-detected from how you invoked the command; only asked if detection fails).
16
+ 4. Optionally customize the site title and primary color.
17
+ 5. Install dependencies.
18
+ 6. Initialize a git repository.
19
+
20
+ ## Schema sources
21
+
22
+ 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
+
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` |
32
+
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.
34
+
35
+ ## Non-interactive mode
36
+
37
+ For CI/CD or scripting, use `--yes`:
38
+
39
+ ```bash
40
+ npm create graphql-markdown-docs@latest -- --yes --dir ./my-docs --schema ./schema.graphql --no-install --no-git
41
+ ```
42
+
43
+ ### Flags
44
+
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. |
57
+
58
+ ## What's included
59
+
60
+ The scaffolded project is a real, complete Nuxt 4 project:
61
+
62
+ - `nuxt.config.ts` — extends `@graphql-markdown/nuxt-theme`, nothing else required.
63
+ - `content.config.ts` — required in every consuming project (not inherited from the layer — see the theme's own README for why).
64
+ - `generate-docs.ts` — calls the theme's `createGenerateDocs` factory with your schema (and, if applicable, the loader it needs).
65
+ - `schema/` — your schema, or the bundled example.
66
+ - `app/app.config.ts` / `app/pages/index.vue` — a minimal landing page and theme override point, yours to edit.
67
+
68
+ ## Docusaurus
69
+
70
+ With `--framework docusaurus`, the scaffold replaces the standalone `graphql-markdown/template` repo:
71
+
72
+ - `docusaurus.config.js` — Docusaurus 3 with the classic preset and `@graphql-markdown/docusaurus`.
73
+ - `.graphqlrc` — schema and loader configuration (rewritten for your `--schema`).
74
+ - `schema/` — your schema, or the bundled example.
75
+ - `static/index.md`, `src/css/custom.css`, `babel.config.js` — landing page, styling and build config.
76
+
77
+ Then run `npm run doc` to generate the docs and `npm start` to serve them.
78
+
79
+ ## Documentation
80
+
81
+ - [`@graphql-markdown/nuxt-theme`](../nuxt-theme) — the layer this scaffolds, including the full customization/swizzling reference.
82
+ - [GraphQL-Markdown documentation](https://graphql-markdown.dev)
83
+ - [Nuxt documentation](https://nuxt.com)
84
+
85
+ ## License
86
+
87
+ MIT
package/bin/create.mjs ADDED
@@ -0,0 +1,5 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { run } from "../lib/create.mjs";
4
+
5
+ process.exitCode = await run();