@graphql-markdown/nuxt-theme 0.2.3 → 0.3.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 +1 -1
- package/app/components/ApiSinglePageEntry.vue +9 -2
- package/app/components/SchemaCodeCard.vue +7 -5
- package/app/composables/useApiNavigation.ts +5 -0
- package/app/composables/useApiReferencePage.ts +6 -3
- package/app/composables/useApiSinglePage.ts +21 -5
- package/app/layouts/reference.vue +19 -3
- package/app/pages/api-reference/[...slug].vue +9 -2
- package/app/utils/api-document.ts +63 -15
- package/app/utils/page-title.ts +24 -0
- package/app/utils/search-sections.ts +106 -0
- package/formatter.mjs +3 -1
- package/generate.ts +32 -10
- package/modules/mdc-components.ts +35 -0
- package/nuxt.config.ts +1 -0
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -92,7 +92,7 @@ These style the classes the default formatter emits (`gqlmd-mdx-badge-*`, `api-d
|
|
|
92
92
|
|
|
93
93
|
### `printTypeOptions`
|
|
94
94
|
|
|
95
|
-
`createGenerateDocs`'s `printTypeOptions` is a generic passthrough to [`@graphql-markdown/core`](https://graphql-markdown.dev/docs/settings#printtypeoptions) — every documented option (`deprecated`, `exampleSection`, `hierarchy`, `parentTypePrefix`, `typeBadges`) works here exactly as described there. This layer only sets its own defaults for two of them (`parentTypePrefix: false`, `typeBadges: true`), which your own `printTypeOptions` can override like any other key.
|
|
95
|
+
`createGenerateDocs`'s `printTypeOptions` is a generic passthrough to [`@graphql-markdown/core`](https://graphql-markdown.dev/docs/reference/settings#printtypeoptions) — every documented option (`deprecated`, `exampleSection`, `hierarchy`, `parentTypePrefix`, `typeBadges`) works here exactly as described there. This layer only sets its own defaults for two of them (`parentTypePrefix: false`, `typeBadges: true`), which your own `printTypeOptions` can override like any other key.
|
|
96
96
|
|
|
97
97
|
`hierarchy` (`"api"` default, `"entity"`, `"flat"`) controls the generated folder structure — and this layer's navigation and landing-page grid adapt to it automatically. Under `"flat"`, where there's no folder to group by at all, every generated page's frontmatter carries a `kind` field (the GraphQL entity kind — `objects`, `scalars`, `queries`, `directives`, …), and the sidebar/landing grid group by that instead, so the site stays organized whichever `hierarchy` value you choose.
|
|
98
98
|
|
|
@@ -13,9 +13,16 @@
|
|
|
13
13
|
color="error"
|
|
14
14
|
variant="subtle"
|
|
15
15
|
icon="i-lucide-triangle-alert"
|
|
16
|
-
:description="entry.deprecationReason"
|
|
17
16
|
class="mb-8"
|
|
18
|
-
|
|
17
|
+
>
|
|
18
|
+
<template #description>
|
|
19
|
+
<ContentRenderer
|
|
20
|
+
v-if="entry.deprecationReason"
|
|
21
|
+
:value="entry.deprecationReason.document"
|
|
22
|
+
tag="span"
|
|
23
|
+
/>
|
|
24
|
+
</template>
|
|
25
|
+
</UAlert>
|
|
19
26
|
|
|
20
27
|
<ContentRenderer
|
|
21
28
|
v-if="entry.lead"
|
|
@@ -20,18 +20,20 @@
|
|
|
20
20
|
|
|
21
21
|
<div class="relative overflow-x-auto p-5 font-mono text-sm">
|
|
22
22
|
<!-- Inside a code group the tab bar carries the label, so the card drops
|
|
23
|
-
its header.
|
|
24
|
-
|
|
23
|
+
its header. Only the copy button floats over the snippet; the entry
|
|
24
|
+
heading already shows the kind badge. -->
|
|
25
25
|
<div
|
|
26
26
|
v-if="hideHeader"
|
|
27
27
|
class="absolute top-3 right-3 z-10 flex items-center gap-2"
|
|
28
28
|
>
|
|
29
|
-
<UBadge color="primary" variant="subtle" size="sm">{{ kind }}</UBadge>
|
|
30
|
-
|
|
31
29
|
<UButton v-bind="copyButtonProps" @click="copy(code)" />
|
|
32
30
|
</div>
|
|
33
31
|
|
|
34
|
-
<div
|
|
32
|
+
<div
|
|
33
|
+
class="blueprint-code"
|
|
34
|
+
:class="{ 'pr-12': hideHeader }"
|
|
35
|
+
v-html="html"
|
|
36
|
+
/>
|
|
35
37
|
</div>
|
|
36
38
|
|
|
37
39
|
<!-- Example variables stack under the query, with their own copy button. -->
|
|
@@ -8,6 +8,8 @@ export interface ApiNavigationLeaf {
|
|
|
8
8
|
active?: boolean;
|
|
9
9
|
ui?: Record<string, unknown>;
|
|
10
10
|
badge?: { label: string; color: "error"; variant: "subtle" };
|
|
11
|
+
/** Set on deprecated leaves so the link's accessible name is not "Titledeprecated". */
|
|
12
|
+
"aria-label"?: string;
|
|
11
13
|
}
|
|
12
14
|
|
|
13
15
|
export interface ApiNavigationBranch {
|
|
@@ -76,6 +78,9 @@ const buildTree = (
|
|
|
76
78
|
variant: "subtle" as const,
|
|
77
79
|
}
|
|
78
80
|
: undefined,
|
|
81
|
+
"aria-label": item.isDeprecated
|
|
82
|
+
? `${item.title} (deprecated)`
|
|
83
|
+
: undefined,
|
|
79
84
|
});
|
|
80
85
|
}
|
|
81
86
|
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { ComputedRef, Ref } from "vue";
|
|
2
2
|
import { anchorIdFor } from "~/composables/useApiSinglePage";
|
|
3
|
+
import { referencePageTitle } from "~/utils/page-title";
|
|
3
4
|
import { LANDING_DOC_NAME, isLandingDocPath } from "../../constants";
|
|
4
5
|
|
|
5
6
|
type Page = Record<string, any> | null | undefined;
|
|
@@ -160,9 +161,11 @@ export const useApiReferencePage = async (): Promise<ApiReferencePage> => {
|
|
|
160
161
|
const current = page.value;
|
|
161
162
|
await nuxtApp.runWithContext(() => {
|
|
162
163
|
useSeoMeta({
|
|
163
|
-
title:
|
|
164
|
-
|
|
165
|
-
:
|
|
164
|
+
title: referencePageTitle({
|
|
165
|
+
title: current.title,
|
|
166
|
+
siteTitle: config.gqlmd.siteTitle as string | undefined,
|
|
167
|
+
isLanding: isLandingPage.value,
|
|
168
|
+
}),
|
|
166
169
|
description: current.description,
|
|
167
170
|
});
|
|
168
171
|
});
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { isLandingDocPath } from "../../constants";
|
|
2
2
|
import {
|
|
3
3
|
codeColumnNodeIndexes,
|
|
4
|
+
type DeprecationNotice,
|
|
4
5
|
findDeprecationNotice,
|
|
5
6
|
isOperationCategory,
|
|
6
7
|
schemaKindLabel,
|
|
@@ -16,10 +17,10 @@ import type {
|
|
|
16
17
|
ApiNavigationNode,
|
|
17
18
|
} from "./useApiNavigation";
|
|
18
19
|
|
|
19
|
-
/** Anvil's own order: queries, then mutations, then subscriptions, then types. */
|
|
20
|
+
/** Anvil's own order: queries, then mutations, then subscriptions, then types, then directives. */
|
|
20
21
|
const OPERATION_KINDS = ["queries", "mutations", "subscriptions"] as const;
|
|
21
22
|
type OperationKind = (typeof OPERATION_KINDS)[number];
|
|
22
|
-
type BucketId = OperationKind | "types";
|
|
23
|
+
type BucketId = OperationKind | "directives" | "types";
|
|
23
24
|
|
|
24
25
|
/**
|
|
25
26
|
* One entry of the single-page view. Typed by the swizzlable
|
|
@@ -32,7 +33,7 @@ export interface ApiSinglePageEntry {
|
|
|
32
33
|
title: string;
|
|
33
34
|
kindLabel: string;
|
|
34
35
|
isDeprecated: boolean;
|
|
35
|
-
deprecationReason?:
|
|
36
|
+
deprecationReason?: DeprecationNotice;
|
|
36
37
|
lead?: Record<string, any>;
|
|
37
38
|
sections: { id: string; title: string; document: Record<string, any> }[];
|
|
38
39
|
definitionCard?: CodeCard;
|
|
@@ -71,6 +72,9 @@ export const anchorIdFor = (page: { path: string; kind?: string }): string => {
|
|
|
71
72
|
};
|
|
72
73
|
|
|
73
74
|
const bucketIdFor = (kind: string | undefined): BucketId => {
|
|
75
|
+
if (kind === "directives") {
|
|
76
|
+
return "directives";
|
|
77
|
+
}
|
|
74
78
|
return kind && (OPERATION_KINDS as readonly string[]).includes(kind)
|
|
75
79
|
? (kind as OperationKind)
|
|
76
80
|
: "types";
|
|
@@ -81,6 +85,7 @@ const BUCKET_TITLES: Record<BucketId, string> = {
|
|
|
81
85
|
mutations: "Mutations",
|
|
82
86
|
subscriptions: "Subscriptions",
|
|
83
87
|
types: "Types",
|
|
88
|
+
directives: "Directives",
|
|
84
89
|
};
|
|
85
90
|
|
|
86
91
|
const buildEntry = async (
|
|
@@ -129,7 +134,7 @@ const buildEntry = async (
|
|
|
129
134
|
* Everything the single-page reference view needs: every generated page's
|
|
130
135
|
* full body, fixed up and split into lead/sections the same way
|
|
131
136
|
* `useApiDocument` does for one page at a time, grouped into
|
|
132
|
-
* Queries/Mutations/Subscriptions/Types buckets in Anvil's order, with every
|
|
137
|
+
* Queries/Mutations/Subscriptions/Types/Directives buckets in Anvil's order, with every
|
|
133
138
|
* definition and example already Shiki-highlighted. Rendered at the base
|
|
134
139
|
* route (`[...slug].vue`'s landing branch) whenever `useHierarchyMode()`
|
|
135
140
|
* detects flat hierarchy, in place of the per-type catalog.
|
|
@@ -206,7 +211,15 @@ export const useApiSinglePage = async (
|
|
|
206
211
|
}),
|
|
207
212
|
);
|
|
208
213
|
|
|
209
|
-
return (
|
|
214
|
+
return (
|
|
215
|
+
[
|
|
216
|
+
"queries",
|
|
217
|
+
"mutations",
|
|
218
|
+
"subscriptions",
|
|
219
|
+
"types",
|
|
220
|
+
"directives",
|
|
221
|
+
] as const
|
|
222
|
+
)
|
|
210
223
|
.map((id) => {
|
|
211
224
|
return {
|
|
212
225
|
id,
|
|
@@ -266,6 +279,9 @@ export const useApiSinglePageNavigation = (
|
|
|
266
279
|
variant: "subtle" as const,
|
|
267
280
|
}
|
|
268
281
|
: undefined,
|
|
282
|
+
"aria-label": entry.isDeprecated
|
|
283
|
+
? `${entry.title} (deprecated)`
|
|
284
|
+
: undefined,
|
|
269
285
|
};
|
|
270
286
|
}),
|
|
271
287
|
};
|
|
@@ -76,9 +76,11 @@
|
|
|
76
76
|
<!-- Nuxt UI reads the dialog's accessible name from `contentSearch.title`
|
|
77
77
|
and `contentSearch.description`, which its bundled locales do not
|
|
78
78
|
define — without these props the modal announces the raw keys. -->
|
|
79
|
+
<!-- Search groups are keyed by `path`; branches have none, so give them one
|
|
80
|
+
here (the sidebar keeps the raw tree). -->
|
|
79
81
|
<UContentSearch
|
|
80
|
-
:navigation="
|
|
81
|
-
:files="
|
|
82
|
+
:navigation="searchNavigation as unknown as ContentNavigationItem[]"
|
|
83
|
+
:files="singlePageSearchFiles"
|
|
82
84
|
title="Search the API reference"
|
|
83
85
|
description="Find an operation, type, field, or example by name."
|
|
84
86
|
/>
|
|
@@ -89,6 +91,10 @@
|
|
|
89
91
|
<script setup lang="ts">
|
|
90
92
|
import type { ContentNavigationItem } from "@nuxt/content";
|
|
91
93
|
import { useApiSinglePageNavigation } from "~/composables/useApiSinglePage";
|
|
94
|
+
import {
|
|
95
|
+
toSinglePageSearchSections,
|
|
96
|
+
withSearchGroupIds,
|
|
97
|
+
} from "~/utils/search-sections";
|
|
92
98
|
import { scrollToIntro } from "~/utils/scroll-to-intro";
|
|
93
99
|
|
|
94
100
|
const config = useAppConfig();
|
|
@@ -121,6 +127,10 @@ const navigationSections = computed(() =>
|
|
|
121
127
|
: sections.value,
|
|
122
128
|
);
|
|
123
129
|
|
|
130
|
+
const searchNavigation = computed(() =>
|
|
131
|
+
withSearchGroupIds(navigationSections.value),
|
|
132
|
+
);
|
|
133
|
+
|
|
124
134
|
// Keep the highlighted sidebar link visible as the page scrolls.
|
|
125
135
|
watch(
|
|
126
136
|
activeAnchor,
|
|
@@ -140,7 +150,13 @@ watch(
|
|
|
140
150
|
);
|
|
141
151
|
|
|
142
152
|
const { data: searchFiles } = await useAsyncData("api-reference-search", () =>
|
|
143
|
-
queryCollectionSearchSections("content"),
|
|
153
|
+
queryCollectionSearchSections("content", { ignoredTags: ["style"] }),
|
|
154
|
+
);
|
|
155
|
+
|
|
156
|
+
// Flat hierarchy's sidebar leaves are `#anchor` links, so search results must
|
|
157
|
+
// carry the same `#anchor` ids for Nuxt UI to match them.
|
|
158
|
+
const singlePageSearchFiles = computed(() =>
|
|
159
|
+
toSinglePageSearchSections(searchFiles.value ?? [], isFlat.value),
|
|
144
160
|
);
|
|
145
161
|
</script>
|
|
146
162
|
|
|
@@ -31,9 +31,16 @@
|
|
|
31
31
|
color="error"
|
|
32
32
|
variant="subtle"
|
|
33
33
|
icon="i-lucide-triangle-alert"
|
|
34
|
-
:description="deprecationReason"
|
|
35
34
|
class="mb-8"
|
|
36
|
-
|
|
35
|
+
>
|
|
36
|
+
<template #description>
|
|
37
|
+
<ContentRenderer
|
|
38
|
+
v-if="deprecationReason"
|
|
39
|
+
:value="deprecationReason.document"
|
|
40
|
+
tag="span"
|
|
41
|
+
/>
|
|
42
|
+
</template>
|
|
43
|
+
</UAlert>
|
|
37
44
|
|
|
38
45
|
<template v-if="isLandingPage">
|
|
39
46
|
<template v-if="isFlat">
|
|
@@ -122,12 +122,49 @@ export const sectionCode = (
|
|
|
122
122
|
};
|
|
123
123
|
|
|
124
124
|
/**
|
|
125
|
-
*
|
|
126
|
-
* the
|
|
125
|
+
* The message of a deprecation notice, as renderable nodes: the children of
|
|
126
|
+
* the `::api-deprecation` block (a lone paragraph is unwrapped so the alert
|
|
127
|
+
* text stays inline), or, for the legacy `<aside>` shape, the children of the
|
|
128
|
+
* message span. The badge is never part of it.
|
|
129
|
+
*/
|
|
130
|
+
const deprecationMessageNodes = (node: MdcElement): MdcNode[] | undefined => {
|
|
131
|
+
if (node[0] === "api-deprecation") {
|
|
132
|
+
const children = childrenOf(node);
|
|
133
|
+
const [only] = children;
|
|
134
|
+
|
|
135
|
+
return children.length === 1 && isElement(only, "p")
|
|
136
|
+
? childrenOf(only)
|
|
137
|
+
: children;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
if (hasClass(node, "api-deprecation-callout")) {
|
|
141
|
+
const message = findByClass(node, "api-deprecation-message");
|
|
142
|
+
|
|
143
|
+
return message ? childrenOf(message) : [];
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
return undefined;
|
|
147
|
+
};
|
|
148
|
+
|
|
149
|
+
export interface DeprecationNotice {
|
|
150
|
+
/** The notice node as it sits in the page body. */
|
|
151
|
+
node: MdcElement;
|
|
152
|
+
/** The message as renderable nodes, links and inline code included. */
|
|
153
|
+
nodes: MdcNode[];
|
|
154
|
+
/** Plain text of the message, without the badge. */
|
|
155
|
+
text: string;
|
|
156
|
+
/** A minimal document, so the message can go through `ContentRenderer`. */
|
|
157
|
+
document: { body: { type: "minimark"; value: MdcNode[] } };
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* A type-level `@deprecated` is emitted as an `::api-deprecation` block (or a
|
|
162
|
+
* legacy `<aside>`) in the description, before the definition. Detected by
|
|
163
|
+
* structure, so any reason text is recognised.
|
|
127
164
|
*/
|
|
128
165
|
export const findDeprecationNotice = (
|
|
129
166
|
body: { value?: MdcNode[] } | null | undefined,
|
|
130
|
-
):
|
|
167
|
+
): DeprecationNotice | undefined => {
|
|
131
168
|
const nodes: MdcNode[] = body?.value ?? [];
|
|
132
169
|
const definitionIndex = nodes.findIndex((node) => {
|
|
133
170
|
return isElement(node, "pre");
|
|
@@ -135,9 +172,19 @@ export const findDeprecationNotice = (
|
|
|
135
172
|
const metadataNodes =
|
|
136
173
|
definitionIndex >= 0 ? nodes.slice(0, definitionIndex) : [];
|
|
137
174
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
175
|
+
for (const node of metadataNodes) {
|
|
176
|
+
const message = isElement(node) ? deprecationMessageNodes(node) : undefined;
|
|
177
|
+
if (isElement(node) && message) {
|
|
178
|
+
return {
|
|
179
|
+
node,
|
|
180
|
+
nodes: message,
|
|
181
|
+
text: message.map(nodeText).join("").trim(),
|
|
182
|
+
document: { body: { type: "minimark", value: message } },
|
|
183
|
+
};
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
return undefined;
|
|
141
188
|
};
|
|
142
189
|
|
|
143
190
|
// --- Transforms ----------------------------------------------------------
|
|
@@ -192,9 +239,9 @@ export const codeColumnNodeIndexes = (nodes: MdcNode[]): Set<number> => {
|
|
|
192
239
|
*/
|
|
193
240
|
export const withoutDeprecationNotice = (
|
|
194
241
|
nodes: MdcNode[],
|
|
195
|
-
|
|
242
|
+
notice?: DeprecationNotice,
|
|
196
243
|
): MdcNode[] => {
|
|
197
|
-
if (!
|
|
244
|
+
if (!notice) return nodes;
|
|
198
245
|
|
|
199
246
|
let isInDirectivesSection = false;
|
|
200
247
|
|
|
@@ -205,19 +252,20 @@ export const withoutDeprecationNotice = (
|
|
|
205
252
|
|
|
206
253
|
if (isInDirectivesSection) return false;
|
|
207
254
|
|
|
208
|
-
return
|
|
255
|
+
return node !== notice.node;
|
|
209
256
|
});
|
|
210
257
|
};
|
|
211
258
|
|
|
212
259
|
/**
|
|
213
|
-
*
|
|
214
|
-
* same UAlert the type-level
|
|
260
|
+
* Deprecation notices are emitted as an `::api-deprecation` block (or, in older
|
|
261
|
+
* output, a raw `<aside>`). Swap them for the same UAlert the type-level
|
|
262
|
+
* notice uses, keeping the message's links and inline code as slot content.
|
|
215
263
|
*/
|
|
216
264
|
const promoteDeprecationCallout = (node: MdcNode): MdcNode => {
|
|
217
|
-
if (!isElement(node)
|
|
218
|
-
return node;
|
|
265
|
+
if (!isElement(node)) return node;
|
|
219
266
|
|
|
220
|
-
const message =
|
|
267
|
+
const message = deprecationMessageNodes(node);
|
|
268
|
+
if (!message) return node;
|
|
221
269
|
|
|
222
270
|
return [
|
|
223
271
|
"UAlert",
|
|
@@ -225,9 +273,9 @@ const promoteDeprecationCallout = (node: MdcNode): MdcNode => {
|
|
|
225
273
|
color: "error",
|
|
226
274
|
variant: "subtle",
|
|
227
275
|
icon: "i-lucide-triangle-alert",
|
|
228
|
-
description: nodeText(message ?? node),
|
|
229
276
|
class: "my-4",
|
|
230
277
|
},
|
|
278
|
+
["template", { "v-slot:description": "" }, ...message],
|
|
231
279
|
];
|
|
232
280
|
};
|
|
233
281
|
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
export interface ReferencePageTitleInput {
|
|
2
|
+
title: string;
|
|
3
|
+
siteTitle?: string;
|
|
4
|
+
isLanding: boolean;
|
|
5
|
+
}
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Builds the browser-tab title of a reference page: the page title, then
|
|
9
|
+
* "API Reference" for non-landing pages, then the site title. The site title
|
|
10
|
+
* is dropped when empty or equal to the page title (case-insensitive).
|
|
11
|
+
*/
|
|
12
|
+
export const referencePageTitle = ({
|
|
13
|
+
title,
|
|
14
|
+
siteTitle,
|
|
15
|
+
isLanding,
|
|
16
|
+
}: ReferencePageTitleInput): string => {
|
|
17
|
+
const parts = [title];
|
|
18
|
+
if (!isLanding) parts.push("API Reference");
|
|
19
|
+
const site = (siteTitle ?? "").trim();
|
|
20
|
+
if (site && site.toLowerCase() !== title.trim().toLowerCase()) {
|
|
21
|
+
parts.push(site);
|
|
22
|
+
}
|
|
23
|
+
return parts.join(" | ");
|
|
24
|
+
};
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
import { extractAnchor } from "./api-document";
|
|
2
|
+
|
|
3
|
+
/** The subset of a `queryCollectionSearchSections` item this helper touches. */
|
|
4
|
+
export interface SearchSection {
|
|
5
|
+
[key: string]: unknown;
|
|
6
|
+
id: string;
|
|
7
|
+
title: string;
|
|
8
|
+
titles: string[];
|
|
9
|
+
level: number;
|
|
10
|
+
content: string;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
const stripAnchorMarker = (value: string): string => {
|
|
14
|
+
const anchor = extractAnchor(value);
|
|
15
|
+
return anchor ? anchor.text.trim() : value;
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* Removes Shiki theme CSS (`html .shiki span {...}`) that leaks into indexed
|
|
20
|
+
* content. Plain index scanning rather than a regex, so there is no
|
|
21
|
+
* backtracking risk.
|
|
22
|
+
*/
|
|
23
|
+
export const stripShikiCss = (content: string): string => {
|
|
24
|
+
let result = content;
|
|
25
|
+
let from = 0;
|
|
26
|
+
for (;;) {
|
|
27
|
+
const marker = result.indexOf(".shiki", from);
|
|
28
|
+
if (marker === -1) break;
|
|
29
|
+
const open = result.indexOf("{", marker);
|
|
30
|
+
const close = open === -1 ? -1 : result.indexOf("}", open);
|
|
31
|
+
if (close === -1) break;
|
|
32
|
+
let start = result.lastIndexOf("html", marker);
|
|
33
|
+
if (start === -1 || result.slice(start, marker).includes("}")) {
|
|
34
|
+
start = marker;
|
|
35
|
+
}
|
|
36
|
+
result = `${result.slice(0, start)} ${result.slice(close + 1)}`;
|
|
37
|
+
from = start;
|
|
38
|
+
}
|
|
39
|
+
return result.split(/\s+/).filter(Boolean).join(" ");
|
|
40
|
+
};
|
|
41
|
+
|
|
42
|
+
const anchorFromId = (id: string): string => {
|
|
43
|
+
const base = id.split("#")[0] ?? id;
|
|
44
|
+
return base.split("/").findLast(Boolean) ?? base;
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Replaces characters Nuxt UI's `highlight` HTML-escapes into multi-character
|
|
49
|
+
* entities (quotes, apostrophes, ampersands, angle brackets). Its
|
|
50
|
+
* `truncateHTMLFromStart` (Nuxt UI runtime/utils/search.js) trims escaped
|
|
51
|
+
* text by character count and can cut through an entity, leaving a stray
|
|
52
|
+
* `quot;` in the snippet. Indexed text without such characters avoids it.
|
|
53
|
+
*/
|
|
54
|
+
export const normalizeSearchText = (value: string): string => {
|
|
55
|
+
return value
|
|
56
|
+
.replaceAll('"', "")
|
|
57
|
+
.replaceAll("'", "\u2019")
|
|
58
|
+
.replaceAll("&", "+")
|
|
59
|
+
.replaceAll("<", "\u2039")
|
|
60
|
+
.replaceAll(">", "\u203A");
|
|
61
|
+
};
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Cleans search sections and, in flat (single-page) mode, points every
|
|
65
|
+
* section at its entry's `#<anchorId>` so it matches the single-page
|
|
66
|
+
* sidebar's leaf paths (Nuxt UI buckets files by `id.split("#")[0]`, which
|
|
67
|
+
* is empty for a bare hash id and falls back to the whole id).
|
|
68
|
+
*/
|
|
69
|
+
export const toSinglePageSearchSections = <T extends SearchSection>(
|
|
70
|
+
files: readonly T[],
|
|
71
|
+
isFlat: boolean,
|
|
72
|
+
): T[] => {
|
|
73
|
+
return files.map((file) => {
|
|
74
|
+
const cleaned = {
|
|
75
|
+
...file,
|
|
76
|
+
title: normalizeSearchText(stripAnchorMarker(file.title)),
|
|
77
|
+
titles: file.titles.map((t) => {
|
|
78
|
+
return normalizeSearchText(stripAnchorMarker(t));
|
|
79
|
+
}),
|
|
80
|
+
content: normalizeSearchText(stripShikiCss(file.content)),
|
|
81
|
+
};
|
|
82
|
+
return isFlat ? { ...cleaned, id: `#${anchorFromId(file.id)}` } : cleaned;
|
|
83
|
+
});
|
|
84
|
+
};
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Gives every top-level navigation branch without a `path` a synthetic one so
|
|
88
|
+
* Nuxt UI's UContentSearch (which keys each CommandPalette group by
|
|
89
|
+
* `group.path` and silently drops groups without an `id`) keeps its results.
|
|
90
|
+
* Returns a shallow copy; the input is not mutated.
|
|
91
|
+
*/
|
|
92
|
+
export const withSearchGroupIds = <
|
|
93
|
+
T extends { title?: string; path?: string; children?: unknown[] },
|
|
94
|
+
>(
|
|
95
|
+
navigation: readonly T[],
|
|
96
|
+
): T[] => {
|
|
97
|
+
return navigation.map((node, index) => {
|
|
98
|
+
if (!node.children || node.path) {
|
|
99
|
+
return { ...node };
|
|
100
|
+
}
|
|
101
|
+
const slug =
|
|
102
|
+
(node.title ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-") ||
|
|
103
|
+
String(index);
|
|
104
|
+
return { ...node, path: `search-group-${slug}` };
|
|
105
|
+
});
|
|
106
|
+
};
|
package/formatter.mjs
CHANGED
|
@@ -54,7 +54,9 @@ export const formatMDXAdmonition = ({ text, title, type }) => {
|
|
|
54
54
|
type.toLowerCase() === "warning" &&
|
|
55
55
|
title?.toLowerCase() === "deprecated"
|
|
56
56
|
) {
|
|
57
|
-
|
|
57
|
+
// An MDC block component, not raw HTML: MDC does not parse Markdown inside
|
|
58
|
+
// raw HTML, so links and code spans in the reason would stay literal.
|
|
59
|
+
return `::api-deprecation\n${text.trim()}\n::`;
|
|
58
60
|
}
|
|
59
61
|
|
|
60
62
|
return `<fieldset class="gqlmd-mdx-admonition-fieldset"><legend class="gqlmd-mdx-admonition-legend"><span class="gqlmd-mdx-admonition-legend-type gqlmd-mdx-admonition-legend-type-${type.toLowerCase()}">${title}</span></legend><span>${text}</span></fieldset>`;
|
package/generate.ts
CHANGED
|
@@ -13,6 +13,9 @@ import { DEFAULT_BASE_URL, LANDING_DOC_NAME } from "./constants.ts";
|
|
|
13
13
|
*/
|
|
14
14
|
type GraphQLMarkdownOptions = Parameters<typeof runGraphQLMarkdown>[0];
|
|
15
15
|
|
|
16
|
+
/** Options the theme sets itself; users cannot override them via `createGenerateDocs`. */
|
|
17
|
+
type ThemeControlledKeys = "linkRoot";
|
|
18
|
+
|
|
16
19
|
/** Default loaders: GraphQL file loader. */
|
|
17
20
|
const DEFAULT_LOADERS = {
|
|
18
21
|
GraphQLFileLoader: "@graphql-tools/graphql-file-loader",
|
|
@@ -36,18 +39,32 @@ const DEFAULT_LOADERS = {
|
|
|
36
39
|
* - homepage: Path to a markdown template rendered as the intro of the API
|
|
37
40
|
* reference, or `false` to disable it (default: GraphQL-Markdown's built-in
|
|
38
41
|
* homepage). Whatever its file name, it is stored as `generated.md`.
|
|
42
|
+
* - any other GraphQL-Markdown option (for example `telemetry`, `pretty`, `force`) is forwarded as-is; `linkRoot` is set by the theme
|
|
39
43
|
* @returns A function that generates the documentation when called
|
|
40
44
|
*/
|
|
41
|
-
export const createGenerateDocs = (
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
45
|
+
export const createGenerateDocs = (
|
|
46
|
+
userOptions: Omit<
|
|
47
|
+
Partial<GraphQLMarkdownOptions>,
|
|
48
|
+
| ThemeControlledKeys
|
|
49
|
+
| "baseURL"
|
|
50
|
+
| "decorators"
|
|
51
|
+
| "formatter"
|
|
52
|
+
| "homepage"
|
|
53
|
+
| "loaders"
|
|
54
|
+
| "printTypeOptions"
|
|
55
|
+
| "rootPath"
|
|
56
|
+
| "schema"
|
|
57
|
+
> & {
|
|
58
|
+
schema: string;
|
|
59
|
+
rootPath?: string;
|
|
60
|
+
baseURL?: string;
|
|
61
|
+
printTypeOptions?: Partial<GraphQLMarkdownOptions["printTypeOptions"]>;
|
|
62
|
+
decorators?: NonNullable<GraphQLMarkdownOptions["decorators"]>;
|
|
63
|
+
formatter?: string;
|
|
64
|
+
loaders?: NonNullable<GraphQLMarkdownOptions["loaders"]>;
|
|
65
|
+
homepage?: string | false;
|
|
66
|
+
},
|
|
67
|
+
): (() => Promise<void>) => {
|
|
51
68
|
const {
|
|
52
69
|
schema,
|
|
53
70
|
rootPath = "./content",
|
|
@@ -57,6 +74,7 @@ export const createGenerateDocs = (userOptions: {
|
|
|
57
74
|
formatter = new URL("./formatter.mjs", import.meta.url).href,
|
|
58
75
|
loaders = DEFAULT_LOADERS,
|
|
59
76
|
homepage,
|
|
77
|
+
...rest
|
|
60
78
|
} = userOptions;
|
|
61
79
|
|
|
62
80
|
const logger = useLogger("gqlmd-generate");
|
|
@@ -69,6 +87,10 @@ export const createGenerateDocs = (userOptions: {
|
|
|
69
87
|
};
|
|
70
88
|
|
|
71
89
|
const options: GraphQLMarkdownOptions = {
|
|
90
|
+
// Forward every other GraphQL-Markdown option untouched; the theme's own
|
|
91
|
+
// values below win over anything passed through here
|
|
92
|
+
...rest,
|
|
93
|
+
|
|
72
94
|
// Core paths
|
|
73
95
|
schema,
|
|
74
96
|
rootPath,
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import { defineNuxtModule, useNuxt } from "@nuxt/kit";
|
|
2
|
+
import type { Component } from "nuxt/schema";
|
|
3
|
+
|
|
4
|
+
const MDC_INJECTED_COMPONENTS = new Set(["UBadge", "UAlert"]);
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Marks the MDC components that api-document.ts injects into rendered markdown
|
|
8
|
+
* at runtime as global.
|
|
9
|
+
*
|
|
10
|
+
* api-document.ts injects these into rendered markdown at runtime, so Nuxt
|
|
11
|
+
* Content never sees them in the content manifest; production builds only
|
|
12
|
+
* bundle manifest or global components, leaving raw <UBadge>/<UAlert>.
|
|
13
|
+
*/
|
|
14
|
+
export const markInjectedComponentsGlobal = (components: Component[]): void => {
|
|
15
|
+
for (const component of components) {
|
|
16
|
+
if (MDC_INJECTED_COMPONENTS.has(component.pascalName)) {
|
|
17
|
+
component.global = true;
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
export { MDC_INJECTED_COMPONENTS };
|
|
23
|
+
|
|
24
|
+
export default defineNuxtModule({
|
|
25
|
+
meta: {
|
|
26
|
+
name: "gqlmd-mdc-components",
|
|
27
|
+
},
|
|
28
|
+
setup() {
|
|
29
|
+
const nuxt = useNuxt();
|
|
30
|
+
|
|
31
|
+
nuxt.hook("components:extend", (components: Component[]) => {
|
|
32
|
+
markInjectedComponentsGlobal(components);
|
|
33
|
+
});
|
|
34
|
+
},
|
|
35
|
+
});
|
package/nuxt.config.ts
CHANGED
|
@@ -7,6 +7,7 @@ const layerDir = fileURLToPath(new URL(".", import.meta.url));
|
|
|
7
7
|
export default defineNuxtConfig({
|
|
8
8
|
modules: [
|
|
9
9
|
join(layerDir, "modules/generate"),
|
|
10
|
+
join(layerDir, "modules/mdc-components"),
|
|
10
11
|
"@nuxt/content",
|
|
11
12
|
"@nuxt/ui",
|
|
12
13
|
join(layerDir, "modules/prerender"),
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@graphql-markdown/nuxt-theme",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "A Nuxt layer for building GraphQL API reference sites",
|
|
5
5
|
"homepage": "https://graphql-markdown.dev",
|
|
6
6
|
"bugs": {
|
|
@@ -29,6 +29,7 @@
|
|
|
29
29
|
"main": "./nuxt.config.ts",
|
|
30
30
|
"exports": {
|
|
31
31
|
".": "./nuxt.config.ts",
|
|
32
|
+
"./formatter": "./formatter.mjs",
|
|
32
33
|
"./generate": "./generate.ts",
|
|
33
34
|
"./package.json": "./package.json"
|
|
34
35
|
},
|
|
@@ -46,7 +47,7 @@
|
|
|
46
47
|
},
|
|
47
48
|
"dependencies": {
|
|
48
49
|
"@clack/prompts": "^1.0.0",
|
|
49
|
-
"@graphql-markdown/cli": "^1.
|
|
50
|
+
"@graphql-markdown/cli": "^1.3.0",
|
|
50
51
|
"@nuxt/content": "^3.16.2",
|
|
51
52
|
"@nuxt/kit": "^4.6.4",
|
|
52
53
|
"@nuxt/ui": "^4.11.0",
|