@graphql-markdown/nuxt-theme 0.2.0 → 0.2.2
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,15 +1,20 @@
|
|
|
1
1
|
# @graphql-markdown/nuxt-theme
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/@graphql-markdown/nuxt-theme)
|
|
4
|
+
[](https://raw.githubusercontent.com/graphql-markdown/graphql-markdown/main/LICENSE)
|
|
5
|
+
|
|
3
6
|
A Nuxt layer that turns a GraphQL schema into a browsable API reference site — built on [GraphQL-Markdown](https://graphql-markdown.dev/), [Nuxt Content](https://content.nuxt.com/), and [Nuxt UI](https://ui.nuxt.com/). Extend it from your own Nuxt project and you get the two-column reference layout (prose on the left, schema definitions and examples on the right), navigation, search, and generation wired up — no theme code of your own required to start.
|
|
4
7
|
|
|
5
|
-
For the CLI that scaffolds a project around this layer in one command, see [`create-graphql-markdown-docs`](
|
|
8
|
+
For the CLI that scaffolds a project around this layer in one command, see [`create-graphql-markdown-docs`](https://www.npmjs.com/package/create-graphql-markdown-docs).
|
|
6
9
|
|
|
7
|
-
##
|
|
10
|
+
## Installation
|
|
8
11
|
|
|
9
|
-
```
|
|
12
|
+
```shell
|
|
10
13
|
npm install @graphql-markdown/nuxt-theme
|
|
11
14
|
```
|
|
12
15
|
|
|
16
|
+
## Quick start
|
|
17
|
+
|
|
13
18
|
```ts
|
|
14
19
|
// nuxt.config.ts
|
|
15
20
|
export default defineNuxtConfig({
|
|
@@ -111,7 +116,7 @@ This view isn't meant to scale indefinitely: every entry's definition and exampl
|
|
|
111
116
|
|
|
112
117
|
For changes config and CSS can't reach — different markup, different components entirely — eject a file into your own project with:
|
|
113
118
|
|
|
114
|
-
```
|
|
119
|
+
```shell
|
|
115
120
|
npx gqlmd-swizzle # interactive picker
|
|
116
121
|
npx gqlmd-swizzle --list # list swizzlable components as JSON
|
|
117
122
|
npx gqlmd-swizzle --component SiteHeader # non-interactive
|
|
@@ -141,9 +146,7 @@ A swizzled file is copied into your project at the same relative path (Nuxt's ow
|
|
|
141
146
|
|
|
142
147
|
## Multi-schema setups
|
|
143
148
|
|
|
144
|
-
Two or more schemas can share one site as distinct, fully isolated sections —
|
|
145
|
-
call `createGenerateDocs` once per schema, each with its own `baseURL`
|
|
146
|
-
nested under the same shared prefix:
|
|
149
|
+
Two or more schemas can share one site as distinct, fully isolated sections — call `createGenerateDocs` once per schema, each with its own `baseURL` nested under the same shared prefix:
|
|
147
150
|
|
|
148
151
|
```ts
|
|
149
152
|
// generate-docs.ts
|
|
@@ -164,21 +167,11 @@ export const generate = async () => {
|
|
|
164
167
|
};
|
|
165
168
|
```
|
|
166
169
|
|
|
167
|
-
`content.config.ts` needs no changes — its glob (`api-reference/**/*.md`)
|
|
168
|
-
already matches any nesting depth, so one collection covers every schema.
|
|
169
|
-
Navigation, search, and the landing page all derive their structure from
|
|
170
|
-
however deep each generated page's path actually is under `gqlmd.baseURL`,
|
|
171
|
-
so `billing` and `inventory` render as separate top-level sections with their
|
|
172
|
-
own section/group levels underneath, not merged or collapsed.
|
|
170
|
+
`content.config.ts` needs no changes — its glob (`api-reference/**/*.md`) already matches any nesting depth, so one collection covers every schema. Navigation, search, and the landing page all derive their structure from however deep each generated page's path actually is under `gqlmd.baseURL`, so `billing` and `inventory` render as separate top-level sections with their own section/group levels underneath, not merged or collapsed.
|
|
173
171
|
|
|
174
|
-
Each schema gets its own landing page automatically (at `/api-reference/billing`,
|
|
175
|
-
`/api-reference/inventory`) — there's no extra config for this, every
|
|
176
|
-
`createGenerateDocs` call already produces one. The bare shared prefix
|
|
177
|
-
(`/api-reference` itself, when nothing is generated directly there) falls
|
|
178
|
-
back to a "choose a namespace" page listing every top-level section.
|
|
172
|
+
Each schema gets its own landing page automatically (at `/api-reference/billing`, `/api-reference/inventory`) — there's no extra config for this, every `createGenerateDocs` call already produces one. The bare shared prefix (`/api-reference` itself, when nothing is generated directly there) falls back to a "choose a namespace" page listing every top-level section.
|
|
179
173
|
|
|
180
|
-
**These three settings are independent by design, not auto-synced — keep
|
|
181
|
-
them in agreement yourself:**
|
|
174
|
+
**These three settings are independent by design, not auto-synced — keep them in agreement yourself:**
|
|
182
175
|
|
|
183
176
|
| Setting | Where | Purpose |
|
|
184
177
|
| --------------------------------- | ----------------------------------- | -------------------------------------------------------------------- |
|
|
@@ -186,12 +179,7 @@ them in agreement yourself:**
|
|
|
186
179
|
| `gqlmd.baseURL` | `app.config.ts` | The shared prefix the UI resolves navigation/search/landing against. |
|
|
187
180
|
| `source` glob prefix | `content.config.ts` | What Nuxt Content actually indexes. |
|
|
188
181
|
|
|
189
|
-
They can't be synced automatically: `content.config.ts`'s glob is evaluated
|
|
190
|
-
statically by Nuxt Content, in a context neither the build-time generator nor
|
|
191
|
-
the runtime Vue UI can reach. In practice this only matters if you change
|
|
192
|
-
`gqlmd.baseURL` away from the default `"api-reference"` — every
|
|
193
|
-
`createGenerateDocs` call's `baseURL` still needs to start with whatever you
|
|
194
|
-
set it to, and `content.config.ts`'s glob prefix needs to match.
|
|
182
|
+
They can't be synced automatically: `content.config.ts`'s glob is evaluated statically by Nuxt Content, in a context neither the build-time generator nor the runtime Vue UI can reach. In practice this only matters if you change `gqlmd.baseURL` away from the default `"api-reference"` — every `createGenerateDocs` call's `baseURL` still needs to start with whatever you set it to, and `content.config.ts`'s glob prefix needs to match.
|
|
195
183
|
|
|
196
184
|
## Fixed contract (not configurable in this version)
|
|
197
185
|
|
|
@@ -206,4 +194,6 @@ Two things remain load-bearing assumptions rather than options, by design for no
|
|
|
206
194
|
|
|
207
195
|
## License
|
|
208
196
|
|
|
209
|
-
MIT.
|
|
197
|
+
GraphQL-Markdown packages are 100% free and open-source, under the [MIT license](https://github.com/graphql-markdown/graphql-markdown/blob/main/LICENSE).
|
|
198
|
+
|
|
199
|
+
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.
|
|
@@ -79,12 +79,13 @@ const { copy: copyVariables, copyButtonProps: variablesCopyButtonProps } =
|
|
|
79
79
|
</script>
|
|
80
80
|
|
|
81
81
|
<style>
|
|
82
|
-
/*
|
|
83
|
-
|
|
84
|
-
|
|
82
|
+
/* The card supplies background and spacing; Shiki's inline `<pre>` style is
|
|
83
|
+
removed by a transformer, so no `!important` is needed. The selectors reach
|
|
84
|
+
into `v-html` output, so they cannot be scoped. */
|
|
85
|
+
/* fallow-ignore-next-line css-selector-complexity -- targets Shiki v-html output */
|
|
85
86
|
.blueprint-code pre {
|
|
86
|
-
background: transparent
|
|
87
|
-
color: var(--gqlmd-code-text)
|
|
87
|
+
background: transparent;
|
|
88
|
+
color: var(--gqlmd-code-text);
|
|
88
89
|
line-height: normal;
|
|
89
90
|
margin: 0;
|
|
90
91
|
padding: 0;
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { codeToHtml } from "shiki";
|
|
1
|
+
import { codeToHtml, type ShikiTransformer } from "shiki";
|
|
2
2
|
import type { Ref } from "vue";
|
|
3
3
|
import {
|
|
4
4
|
CODE_COLUMN_SECTIONS,
|
|
@@ -33,8 +33,22 @@ export const detectLanguage = (code: string): "graphql" | "json" => {
|
|
|
33
33
|
}
|
|
34
34
|
};
|
|
35
35
|
|
|
36
|
+
/**
|
|
37
|
+
* Drops the inline `style` Shiki puts on `<pre>` (theme background and text
|
|
38
|
+
* colour); the card supplies both, so no `!important` override is needed.
|
|
39
|
+
*/
|
|
40
|
+
const stripPreStyle: ShikiTransformer = {
|
|
41
|
+
pre(node) {
|
|
42
|
+
delete node.properties.style;
|
|
43
|
+
},
|
|
44
|
+
};
|
|
45
|
+
|
|
36
46
|
const highlight = async (code: string, shikiTheme: string): Promise<string> => {
|
|
37
|
-
return codeToHtml(code, {
|
|
47
|
+
return codeToHtml(code, {
|
|
48
|
+
lang: detectLanguage(code),
|
|
49
|
+
theme: shikiTheme,
|
|
50
|
+
transformers: [stripPreStyle],
|
|
51
|
+
});
|
|
38
52
|
};
|
|
39
53
|
|
|
40
54
|
/**
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@graphql-markdown/nuxt-theme",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.2",
|
|
4
4
|
"description": "A Nuxt layer for building GraphQL API reference sites",
|
|
5
5
|
"homepage": "https://graphql-markdown.dev",
|
|
6
6
|
"bugs": {
|
|
@@ -36,8 +36,8 @@
|
|
|
36
36
|
"build": "echo \"no build step — Nuxt layer ships source\"",
|
|
37
37
|
"lint": "eslint --config ../../packages/tooling-config/eslint/config.ts \"app/**/*.{ts,vue}\" \"modules/**/*.ts\" \"*.ts\" \"*.mjs\" \"bin/**/*.mjs\" \"tests/**/*.ts\" --ignore-pattern \"tests/fixture*/**\"",
|
|
38
38
|
"lint:fix": "eslint --config ../../packages/tooling-config/eslint/config.ts \"app/**/*.{ts,vue}\" \"modules/**/*.ts\" \"*.ts\" \"*.mjs\" \"bin/**/*.mjs\" \"tests/**/*.ts\" --ignore-pattern \"tests/fixture*/**\" --fix",
|
|
39
|
-
"prettier": "prettier \"app/**/*.{ts,vue,css}\" \"modules/**/*.ts\" \"*.ts\" \"*.mjs\" \"bin/**/*.mjs\" \"tests/**/*.ts\" \"!tests/fixture*/**\" --check",
|
|
40
|
-
"prettier:fix": "prettier \"app/**/*.{ts,vue,css}\" \"modules/**/*.ts\" \"*.ts\" \"*.mjs\" \"bin/**/*.mjs\" \"tests/**/*.ts\" \"!tests/fixture*/**\" --write",
|
|
39
|
+
"prettier": "prettier \"app/**/*.{ts,vue,css}\" \"modules/**/*.ts\" \"*.ts\" \"*.mjs\" \"bin/**/*.mjs\" \"tests/**/*.ts\" \"!tests/fixture*/**\" README.md --check",
|
|
40
|
+
"prettier:fix": "prettier \"app/**/*.{ts,vue,css}\" \"modules/**/*.ts\" \"*.ts\" \"*.mjs\" \"bin/**/*.mjs\" \"tests/**/*.ts\" \"!tests/fixture*/**\" README.md --write",
|
|
41
41
|
"ts:check": "nuxi typecheck",
|
|
42
42
|
"test": "vitest run --passWithNoTests",
|
|
43
43
|
"test:unit": "vitest run --passWithNoTests tests/unit",
|
|
@@ -46,23 +46,23 @@
|
|
|
46
46
|
},
|
|
47
47
|
"dependencies": {
|
|
48
48
|
"@clack/prompts": "^1.0.0",
|
|
49
|
-
"@graphql-markdown/cli": "^1.2.
|
|
50
|
-
"@nuxt/content": "^3.16.
|
|
51
|
-
"@nuxt/kit": "^4.6.
|
|
49
|
+
"@graphql-markdown/cli": "^1.2.2",
|
|
50
|
+
"@nuxt/content": "^3.16.2",
|
|
51
|
+
"@nuxt/kit": "^4.6.4",
|
|
52
52
|
"@nuxt/ui": "^4.11.0",
|
|
53
53
|
"consola": "^3.4.2",
|
|
54
|
-
"shiki": "^4.
|
|
55
|
-
"tailwindcss": "^4.3.
|
|
54
|
+
"shiki": "^4.6.0",
|
|
55
|
+
"tailwindcss": "^4.3.5"
|
|
56
56
|
},
|
|
57
57
|
"devDependencies": {
|
|
58
58
|
"@graphql-markdown/tooling-config": "^1.0.0",
|
|
59
|
-
"nuxt": "^4.6.
|
|
59
|
+
"nuxt": "^4.6.4",
|
|
60
60
|
"typescript": "6.0.3",
|
|
61
61
|
"vue-router": "^5.4.0",
|
|
62
|
-
"vue-tsc": "^3.3.
|
|
62
|
+
"vue-tsc": "^3.3.14"
|
|
63
63
|
},
|
|
64
64
|
"engines": {
|
|
65
|
-
"node": ">=22.
|
|
65
|
+
"node": ">=22.18.0"
|
|
66
66
|
},
|
|
67
67
|
"publishConfig": {
|
|
68
68
|
"access": "public"
|