@graphql-markdown/nuxt-theme 0.0.0-stage → 0.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 +196 -2
- package/app/app-config.d.ts +15 -0
- package/app/app.config.ts +22 -0
- package/app/assets/css/main.css +85 -0
- package/app/components/ApiCodeColumn.vue +53 -0
- package/app/components/ApiDocumentContent.vue +45 -0
- package/app/components/ApiNamespaceLanding.vue +29 -0
- package/app/components/ApiOverviewGrid.vue +38 -0
- package/app/components/ApiSinglePageEntry.vue +75 -0
- package/app/components/ApiSinglePageSection.vue +32 -0
- package/app/components/SchemaCodeCard.vue +68 -0
- package/app/components/SiteFooter.vue +13 -0
- package/app/components/SiteHeader.vue +31 -0
- package/app/composables/useApiCodeCards.ts +96 -0
- package/app/composables/useApiDocument.ts +69 -0
- package/app/composables/useApiNavigation.ts +212 -0
- package/app/composables/useApiReferencePage.ts +164 -0
- package/app/composables/useApiSinglePage.ts +320 -0
- package/app/composables/useClipboardCopy.ts +56 -0
- package/app/composables/useHierarchyMode.ts +48 -0
- package/app/layouts/reference.vue +128 -0
- package/app/pages/api-reference/[...slug].vue +233 -0
- package/app/utils/api-document.ts +329 -0
- package/app/utils/mdc.ts +60 -0
- package/app/utils/navigation-tree.ts +28 -0
- package/bin/swizzle.mjs +256 -0
- package/content.config.ts +13 -0
- package/formatter.ts +77 -0
- package/generate.ts +91 -0
- package/modules/generate.ts +72 -0
- package/modules/prerender.ts +104 -0
- package/nuxt.config.ts +16 -0
- package/package.json +81 -4
- package/swizzle.manifest.mjs +84 -0
- package/swizzle.manifest.ts +11 -0
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
<!-- fallow-ignore-file complexity -->
|
|
2
|
+
<template>
|
|
3
|
+
<main
|
|
4
|
+
v-if="page"
|
|
5
|
+
class="grid flex-1 grid-cols-1"
|
|
6
|
+
:class="{ 'lg:grid-cols-2': !isLandingPage }"
|
|
7
|
+
>
|
|
8
|
+
<section
|
|
9
|
+
class="api-document max-w-none overflow-y-auto p-8 lg:px-16 lg:py-20"
|
|
10
|
+
:class="{ 'border-r border-default': !isLandingPage }"
|
|
11
|
+
>
|
|
12
|
+
<UBreadcrumb
|
|
13
|
+
:items="breadcrumbs"
|
|
14
|
+
class="mb-8 -mt-12 font-mono"
|
|
15
|
+
:ui="{ list: 'flex-wrap', linkLabel: 'truncate-none' }"
|
|
16
|
+
/>
|
|
17
|
+
|
|
18
|
+
<UAlert
|
|
19
|
+
v-if="deprecationReason"
|
|
20
|
+
color="error"
|
|
21
|
+
variant="subtle"
|
|
22
|
+
icon="i-lucide-triangle-alert"
|
|
23
|
+
:description="deprecationReason"
|
|
24
|
+
class="mb-8"
|
|
25
|
+
/>
|
|
26
|
+
|
|
27
|
+
<template v-if="isLandingPage">
|
|
28
|
+
<template v-if="isFlat">
|
|
29
|
+
<ApiSinglePageSection
|
|
30
|
+
v-for="bucket in buckets"
|
|
31
|
+
:key="bucket.id"
|
|
32
|
+
:bucket="bucket"
|
|
33
|
+
/>
|
|
34
|
+
</template>
|
|
35
|
+
<ApiNamespaceLanding
|
|
36
|
+
v-else
|
|
37
|
+
title="Schema Documentation"
|
|
38
|
+
description="Browse the workspace API by operation or schema type. Every page includes its definition, related fields, and examples when available."
|
|
39
|
+
:items="overviewGroups"
|
|
40
|
+
/>
|
|
41
|
+
</template>
|
|
42
|
+
<ApiDocumentContent v-else :document="document" />
|
|
43
|
+
</section>
|
|
44
|
+
|
|
45
|
+
<ApiCodeColumn
|
|
46
|
+
v-if="!isLandingPage"
|
|
47
|
+
:definition-card="definitionCard"
|
|
48
|
+
:example-cards="exampleCards"
|
|
49
|
+
/>
|
|
50
|
+
</main>
|
|
51
|
+
<main v-else-if="isNamespaceChooser" class="grid flex-1 grid-cols-1">
|
|
52
|
+
<section
|
|
53
|
+
class="api-document max-w-none overflow-y-auto p-8 lg:px-16 lg:py-20"
|
|
54
|
+
>
|
|
55
|
+
<UBreadcrumb
|
|
56
|
+
:items="[{ label: 'API Reference' }]"
|
|
57
|
+
class="mb-8 -mt-12 font-mono"
|
|
58
|
+
:ui="{ list: 'flex-wrap', linkLabel: 'truncate-none' }"
|
|
59
|
+
/>
|
|
60
|
+
|
|
61
|
+
<ApiNamespaceLanding
|
|
62
|
+
title="Choose a Namespace"
|
|
63
|
+
description="Select a schema namespace to browse the API documentation."
|
|
64
|
+
:items="sections"
|
|
65
|
+
/>
|
|
66
|
+
</section>
|
|
67
|
+
</main>
|
|
68
|
+
<div v-else class="flex-1 p-12 text-center text-muted">
|
|
69
|
+
Loading documentation endpoint…
|
|
70
|
+
</div>
|
|
71
|
+
</template>
|
|
72
|
+
|
|
73
|
+
<script setup lang="ts">
|
|
74
|
+
definePageMeta({ layout: "reference" });
|
|
75
|
+
|
|
76
|
+
const {
|
|
77
|
+
route,
|
|
78
|
+
baseURLPath,
|
|
79
|
+
page,
|
|
80
|
+
isLandingPage,
|
|
81
|
+
isNamespaceChooser,
|
|
82
|
+
isFlat,
|
|
83
|
+
buckets,
|
|
84
|
+
sections,
|
|
85
|
+
overviewGroups,
|
|
86
|
+
breadcrumbs,
|
|
87
|
+
deprecationReason,
|
|
88
|
+
document,
|
|
89
|
+
definitionCard,
|
|
90
|
+
exampleCards,
|
|
91
|
+
} = await useApiReferencePage();
|
|
92
|
+
</script>
|
|
93
|
+
|
|
94
|
+
<style>
|
|
95
|
+
/* Everything below styles rendered content only. Scoping to
|
|
96
|
+
`.markdown-text-body` — the ContentRenderer wrapper — keeps it away from the
|
|
97
|
+
hand-written landing markup that shares the `.api-document` column. */
|
|
98
|
+
/* fallow-ignore-next-line css-selector-complexity -- targets generated markdown content */
|
|
99
|
+
.markdown-text-body :is(h1, h2, h3) {
|
|
100
|
+
color: var(--ui-text-highlighted);
|
|
101
|
+
font-family: var(--font-serif);
|
|
102
|
+
font-weight: 600;
|
|
103
|
+
letter-spacing: 0;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
.markdown-text-body h2 {
|
|
107
|
+
font-size: 2rem;
|
|
108
|
+
margin-top: 0;
|
|
109
|
+
margin-bottom: 2.5rem;
|
|
110
|
+
padding-bottom: 1.25rem;
|
|
111
|
+
border-bottom: 1px solid var(--ui-border-accented);
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
.markdown-text-body h3 {
|
|
115
|
+
font-size: 1.5rem;
|
|
116
|
+
margin-top: 2.75rem;
|
|
117
|
+
padding-bottom: 0.75rem;
|
|
118
|
+
border-bottom: 1px solid var(--ui-border-muted);
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/* The section heading carries the separator, so the first entry beneath it
|
|
122
|
+
must not draw a second one. */
|
|
123
|
+
/* fallow-ignore-next-line css-selector-complexity -- targets generated markdown content */
|
|
124
|
+
.markdown-text-body h3 + h4 {
|
|
125
|
+
border-top: 0;
|
|
126
|
+
padding-top: 0.5rem;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
.markdown-text-body h4 {
|
|
130
|
+
color: var(--ui-primary);
|
|
131
|
+
font-family: var(--font-mono);
|
|
132
|
+
font-size: 1rem;
|
|
133
|
+
margin-top: 0;
|
|
134
|
+
padding-top: 1.5rem;
|
|
135
|
+
border-top: 1px solid var(--ui-border-muted);
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
.markdown-text-body p {
|
|
139
|
+
color: var(--ui-text);
|
|
140
|
+
font-size: 1rem;
|
|
141
|
+
line-height: 1.5rem;
|
|
142
|
+
margin-top: 0.75rem;
|
|
143
|
+
margin-bottom: 0.75rem;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/* The type/operation description renders in its own block above the collapsible
|
|
147
|
+
sections and reads as a lead paragraph; everything inside a section is body
|
|
148
|
+
copy, which `.markdown-text-body p` already sizes. */
|
|
149
|
+
.markdown-lead > p {
|
|
150
|
+
font-size: 1.2rem;
|
|
151
|
+
line-height: 1.75rem;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/* The section heading is now a collapsible trigger, so it carries the rule and
|
|
155
|
+
spacing the `h3` used to draw. */
|
|
156
|
+
.section-trigger {
|
|
157
|
+
justify-content: space-between;
|
|
158
|
+
margin-top: 2.75rem;
|
|
159
|
+
padding: 0 0 0.75rem;
|
|
160
|
+
border-bottom: 1px solid var(--ui-border-muted);
|
|
161
|
+
border-radius: 0;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
.section-trigger:hover {
|
|
165
|
+
background: transparent;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/* The trigger carries the separator, so the first entry beneath it must not
|
|
169
|
+
draw a second one. */
|
|
170
|
+
.markdown-text-body > h4:first-child {
|
|
171
|
+
border-top: 0;
|
|
172
|
+
padding-top: 1rem;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
.markdown-text-body a {
|
|
176
|
+
color: var(--ui-primary);
|
|
177
|
+
text-decoration: none;
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/* fallow-ignore-next-line css-selector-complexity -- targets generated markdown content */
|
|
181
|
+
.markdown-text-body a[href^="/"]:not([href^="#"]) {
|
|
182
|
+
font-weight: 600;
|
|
183
|
+
text-decoration: underline;
|
|
184
|
+
text-decoration-color: var(--ui-primary);
|
|
185
|
+
text-decoration-style: dotted;
|
|
186
|
+
text-decoration-thickness: 1px;
|
|
187
|
+
text-underline-offset: 3px;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/* fallow-ignore-next-line css-selector-complexity -- targets generated markdown content */
|
|
191
|
+
.markdown-text-body a[href^="/"]:not([href^="#"]):hover {
|
|
192
|
+
background: color-mix(in oklch, var(--ui-primary) 20%, transparent);
|
|
193
|
+
border-radius: 3px;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/* Nuxt UI hovers code-in-link via `&>code`, but generated entity links wrap the
|
|
197
|
+
chip in a `.gqlmd-mdx-entity` span — the chip is a grandchild, so that never
|
|
198
|
+
matches and the opaque chip also hides the anchor's own hover. Re-apply it
|
|
199
|
+
for that shape, on links that actually navigate somewhere. */
|
|
200
|
+
/* fallow-ignore-next-line css-selector-complexity -- targets generated markdown content */
|
|
201
|
+
.markdown-text-body a:not([href^="#"]) > .gqlmd-mdx-entity > code {
|
|
202
|
+
border-style: dashed;
|
|
203
|
+
transition:
|
|
204
|
+
color 0.15s,
|
|
205
|
+
border-color 0.15s;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/* fallow-ignore-next-line css-selector-complexity -- targets generated markdown content */
|
|
209
|
+
.markdown-text-body a:not([href^="#"]):hover > .gqlmd-mdx-entity > code {
|
|
210
|
+
border-color: var(--ui-primary);
|
|
211
|
+
color: var(--ui-primary);
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
/* Self-anchors (`Folder.id`) only mark the field they head — nothing to follow,
|
|
215
|
+
so they stay inert, including Nuxt UI's own underline-on-hover. */
|
|
216
|
+
/* fallow-ignore-next-line css-selector-complexity -- targets generated markdown content */
|
|
217
|
+
.markdown-text-body a[href^="#"]:hover {
|
|
218
|
+
background: none;
|
|
219
|
+
border-bottom-color: transparent;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/* The GraphQL definition is rendered separately in the code column. Hiding the
|
|
223
|
+
`<pre>` alone leaves the ProsePre wrapper behind, whose absolutely-positioned
|
|
224
|
+
copy button then floats over the prose — so the whole block goes. */
|
|
225
|
+
/* fallow-ignore-next-line css-selector-complexity -- targets generated markdown content */
|
|
226
|
+
.markdown-text-body div:has(> pre),
|
|
227
|
+
.markdown-text-body pre,
|
|
228
|
+
.markdown-text-body .code-block,
|
|
229
|
+
.markdown-text-body code::before,
|
|
230
|
+
.markdown-text-body code::after {
|
|
231
|
+
display: none !important;
|
|
232
|
+
}
|
|
233
|
+
</style>
|
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
import {
|
|
2
|
+
childrenOf,
|
|
3
|
+
findByClass,
|
|
4
|
+
hasClass,
|
|
5
|
+
isElement,
|
|
6
|
+
nodeClasses,
|
|
7
|
+
nodeText,
|
|
8
|
+
type MdcElement,
|
|
9
|
+
type MdcNode,
|
|
10
|
+
} from "~/utils/mdc";
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Reading the generated GraphQL reference: the queries and transforms that turn
|
|
14
|
+
* one `graphql-markdown` page into the parts the reference layout renders.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
const SCHEMA_KIND_LABELS: Record<string, string> = {
|
|
18
|
+
directives: "DIRECTIVE",
|
|
19
|
+
mutations: "MUTATION",
|
|
20
|
+
subscriptions: "SUBSCRIPTION",
|
|
21
|
+
queries: "QUERY",
|
|
22
|
+
objects: "OBJECT",
|
|
23
|
+
scalars: "SCALAR",
|
|
24
|
+
enums: "ENUM",
|
|
25
|
+
unions: "UNION",
|
|
26
|
+
inputs: "INPUT",
|
|
27
|
+
interfaces: "INTERFACE",
|
|
28
|
+
};
|
|
29
|
+
|
|
30
|
+
/** Categories whose pages document an operation rather than a schema type. */
|
|
31
|
+
const OPERATION_CATEGORIES = new Set(["queries", "mutations", "subscriptions"]);
|
|
32
|
+
|
|
33
|
+
export const isOperationCategory = (category?: string): boolean => {
|
|
34
|
+
return Boolean(category && OPERATION_CATEGORIES.has(category));
|
|
35
|
+
};
|
|
36
|
+
|
|
37
|
+
/** Badge for a page's schema kind, taken from its category path segment. */
|
|
38
|
+
export const schemaKindLabel = (category?: string): string => {
|
|
39
|
+
return category
|
|
40
|
+
? (SCHEMA_KIND_LABELS[category] ?? category.toUpperCase())
|
|
41
|
+
: "GRAPHQL";
|
|
42
|
+
};
|
|
43
|
+
|
|
44
|
+
/** `create-project` → `Create Project`, for path segments used as labels. */
|
|
45
|
+
export const titleCase = (value: string): string => {
|
|
46
|
+
return value.replaceAll("-", " ").replace(/\b\w/g, (letter) => {
|
|
47
|
+
return letter.toUpperCase();
|
|
48
|
+
});
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
export interface Breadcrumb {
|
|
52
|
+
label: string;
|
|
53
|
+
to?: string;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Breadcrumb trail for a page path. Only the root crumb navigates (to
|
|
58
|
+
* `rootPath`, and only when there are deeper segments); the category segments
|
|
59
|
+
* have no page. The leaf shows the page title when there is one.
|
|
60
|
+
*/
|
|
61
|
+
export const buildBreadcrumbs = (
|
|
62
|
+
segments: string[],
|
|
63
|
+
pageTitle: string | undefined,
|
|
64
|
+
rootPath: string,
|
|
65
|
+
): Breadcrumb[] => {
|
|
66
|
+
const lastIndex = segments.length - 1;
|
|
67
|
+
return segments.map((segment, index) => {
|
|
68
|
+
if (index === 0) {
|
|
69
|
+
return {
|
|
70
|
+
label: "API Reference",
|
|
71
|
+
to: segments.length > 1 ? rootPath : undefined,
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
const label =
|
|
75
|
+
index === lastIndex && pageTitle ? pageTitle : titleCase(segment);
|
|
76
|
+
return { label, to: undefined };
|
|
77
|
+
});
|
|
78
|
+
};
|
|
79
|
+
|
|
80
|
+
// --- Queries -------------------------------------------------------------
|
|
81
|
+
|
|
82
|
+
const findSectionIndex = (nodes: MdcNode[], title: string): number => {
|
|
83
|
+
return nodes.findIndex((node) => {
|
|
84
|
+
return isElement(node, "h3") && nodeText(node).trim() === title;
|
|
85
|
+
});
|
|
86
|
+
};
|
|
87
|
+
|
|
88
|
+
const findGraphqlCode = (
|
|
89
|
+
nodes: MdcNode[],
|
|
90
|
+
from = 0,
|
|
91
|
+
): MdcElement | undefined => {
|
|
92
|
+
return nodes.slice(from).find((node): node is MdcElement => {
|
|
93
|
+
return isElement(node, "pre") && node[1].language === "graphql";
|
|
94
|
+
});
|
|
95
|
+
};
|
|
96
|
+
|
|
97
|
+
/** The type or operation definition, always the page's first code block. */
|
|
98
|
+
export const definitionCode = (nodes: MdcNode[]): string | undefined => {
|
|
99
|
+
return findGraphqlCode(nodes)?.[1]?.code;
|
|
100
|
+
};
|
|
101
|
+
|
|
102
|
+
/** The code block below an `### <title>` heading, if the schema defines one. */
|
|
103
|
+
export const sectionCode = (
|
|
104
|
+
nodes: MdcNode[],
|
|
105
|
+
title: string,
|
|
106
|
+
): string | undefined => {
|
|
107
|
+
const index = findSectionIndex(nodes, title);
|
|
108
|
+
const code =
|
|
109
|
+
index >= 0
|
|
110
|
+
? findGraphqlCode(nodes, index + 1)?.[1]?.code?.trim()
|
|
111
|
+
: undefined;
|
|
112
|
+
|
|
113
|
+
// Types without a schema-defined example still emit an empty `{}` block.
|
|
114
|
+
return code && code !== "{}" ? code : undefined;
|
|
115
|
+
};
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* A type retired with `@deprecatedType` states its replacement as prose above
|
|
119
|
+
* the definition rather than through the standard `@deprecated` directive.
|
|
120
|
+
*/
|
|
121
|
+
export const findDeprecationNotice = (
|
|
122
|
+
body: { value?: MdcNode[] } | null | undefined,
|
|
123
|
+
): string | undefined => {
|
|
124
|
+
const nodes: MdcNode[] = body?.value ?? [];
|
|
125
|
+
const definitionIndex = nodes.findIndex((node) => {
|
|
126
|
+
return isElement(node, "pre");
|
|
127
|
+
});
|
|
128
|
+
const metadataNodes =
|
|
129
|
+
definitionIndex >= 0 ? nodes.slice(0, definitionIndex) : [];
|
|
130
|
+
|
|
131
|
+
return metadataNodes.map(nodeText).find((text) => {
|
|
132
|
+
return text.includes("Replaced by");
|
|
133
|
+
});
|
|
134
|
+
};
|
|
135
|
+
|
|
136
|
+
// --- Transforms ----------------------------------------------------------
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* Sections lifted out of the prose column and rendered as cards in the code
|
|
140
|
+
* column instead, with the badge each card carries — `kind` defaults to the
|
|
141
|
+
* page's own schema kind. Single source of truth for both sides of the move.
|
|
142
|
+
*/
|
|
143
|
+
export const CODE_COLUMN_SECTIONS: {
|
|
144
|
+
title: string;
|
|
145
|
+
label?: string;
|
|
146
|
+
kind?: string;
|
|
147
|
+
operationOnly?: boolean;
|
|
148
|
+
}[] = [
|
|
149
|
+
{ title: "Example" },
|
|
150
|
+
{
|
|
151
|
+
title: "Example Response",
|
|
152
|
+
label: "Response",
|
|
153
|
+
kind: "JSON",
|
|
154
|
+
operationOnly: true,
|
|
155
|
+
},
|
|
156
|
+
];
|
|
157
|
+
|
|
158
|
+
/** Indexes of the moved headings and the code block following each of them. */
|
|
159
|
+
export const codeColumnNodeIndexes = (nodes: MdcNode[]): Set<number> => {
|
|
160
|
+
const indexes = new Set<number>();
|
|
161
|
+
|
|
162
|
+
for (const { title } of CODE_COLUMN_SECTIONS) {
|
|
163
|
+
const index = findSectionIndex(nodes, title);
|
|
164
|
+
if (index >= 0) indexes.add(index).add(index + 1);
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
return indexes;
|
|
168
|
+
};
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* On a deprecated type, both the notice itself and the "Directives" section
|
|
172
|
+
* restating it are promoted into the alert above the document.
|
|
173
|
+
*/
|
|
174
|
+
export const withoutDeprecationNotice = (
|
|
175
|
+
nodes: MdcNode[],
|
|
176
|
+
reason?: string,
|
|
177
|
+
): MdcNode[] => {
|
|
178
|
+
if (!reason) return nodes;
|
|
179
|
+
|
|
180
|
+
let isInDirectivesSection = false;
|
|
181
|
+
|
|
182
|
+
return nodes.filter((node) => {
|
|
183
|
+
if (isElement(node, "h3")) {
|
|
184
|
+
isInDirectivesSection = nodeText(node).trim() === "Directives";
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
if (isInDirectivesSection) return false;
|
|
188
|
+
|
|
189
|
+
return !nodeText(node).includes(reason);
|
|
190
|
+
});
|
|
191
|
+
};
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* Field-level deprecations are emitted as a raw `<aside>`. Swap them for the
|
|
195
|
+
* same UAlert the type-level notice uses so both render identically.
|
|
196
|
+
*/
|
|
197
|
+
const promoteDeprecationCallout = (node: MdcNode): MdcNode => {
|
|
198
|
+
if (!isElement(node) || !hasClass(node, "api-deprecation-callout"))
|
|
199
|
+
return node;
|
|
200
|
+
|
|
201
|
+
const message = findByClass(node, "api-deprecation-message");
|
|
202
|
+
|
|
203
|
+
return [
|
|
204
|
+
"UAlert",
|
|
205
|
+
{
|
|
206
|
+
color: "error",
|
|
207
|
+
variant: "subtle",
|
|
208
|
+
icon: "i-lucide-triangle-alert",
|
|
209
|
+
description: nodeText(message ?? node),
|
|
210
|
+
class: "my-4",
|
|
211
|
+
},
|
|
212
|
+
];
|
|
213
|
+
};
|
|
214
|
+
|
|
215
|
+
const BADGE_STYLES: Record<string, { color: string; variant: string }> = {
|
|
216
|
+
"gqlmd-mdx-badge-deprecated": { color: "error", variant: "subtle" },
|
|
217
|
+
"gqlmd-mdx-badge-non-null": { color: "neutral", variant: "solid" },
|
|
218
|
+
};
|
|
219
|
+
|
|
220
|
+
/**
|
|
221
|
+
* Type metadata is marked with `<mark class="gqlmd-mdx-badge-*">`. Render it as
|
|
222
|
+
* UBadge so it matches the badges used in the sidebar.
|
|
223
|
+
*/
|
|
224
|
+
const promoteBadges = (node: MdcNode): MdcNode => {
|
|
225
|
+
if (!isElement(node)) return node;
|
|
226
|
+
|
|
227
|
+
const classes = nodeClasses(node);
|
|
228
|
+
if (node[0] === "mark" && classes.includes("gqlmd-mdx-badge")) {
|
|
229
|
+
const style = classes
|
|
230
|
+
.map((name) => {
|
|
231
|
+
return BADGE_STYLES[name];
|
|
232
|
+
})
|
|
233
|
+
.find(Boolean) ?? {
|
|
234
|
+
color: "neutral",
|
|
235
|
+
variant: "subtle",
|
|
236
|
+
};
|
|
237
|
+
|
|
238
|
+
return [
|
|
239
|
+
"UBadge",
|
|
240
|
+
{ ...style, size: "sm", class: "font-mono align-middle" },
|
|
241
|
+
...childrenOf(node),
|
|
242
|
+
];
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
return [node[0], node[1], ...childrenOf(node).map(promoteBadges)];
|
|
246
|
+
};
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* Splits a trailing `{#id}` marker off a string in linear time (equivalent to
|
|
250
|
+
* matching `/\s*\{#([^}]+)\}\s*$/`, without its backtracking).
|
|
251
|
+
*/
|
|
252
|
+
export const extractAnchor = (
|
|
253
|
+
value: string,
|
|
254
|
+
): { id: string; text: string } | null => {
|
|
255
|
+
const trimmed = value.trimEnd();
|
|
256
|
+
if (!trimmed.endsWith("}")) return null;
|
|
257
|
+
const closeIdx = trimmed.length - 1;
|
|
258
|
+
const open = trimmed.indexOf(
|
|
259
|
+
"{#",
|
|
260
|
+
trimmed.lastIndexOf("}", closeIdx - 1) + 1,
|
|
261
|
+
);
|
|
262
|
+
if (open === -1 || open + 2 >= closeIdx) return null;
|
|
263
|
+
return {
|
|
264
|
+
id: trimmed.slice(open + 2, closeIdx),
|
|
265
|
+
text: trimmed.slice(0, open).trimEnd(),
|
|
266
|
+
};
|
|
267
|
+
};
|
|
268
|
+
|
|
269
|
+
/**
|
|
270
|
+
* Headings carry their anchor as a trailing `{#id}` marker; lift it into the
|
|
271
|
+
* element's own id so in-page links resolve.
|
|
272
|
+
*/
|
|
273
|
+
const normalizeAnchorId = (node: MdcNode): MdcNode => {
|
|
274
|
+
if (!isElement(node) || !/^h[1-6]$/.test(node[0])) return node;
|
|
275
|
+
|
|
276
|
+
const lastChild = node.at(-1);
|
|
277
|
+
const anchor =
|
|
278
|
+
typeof lastChild === "string" ? extractAnchor(lastChild) : null;
|
|
279
|
+
if (!anchor) return node;
|
|
280
|
+
|
|
281
|
+
const children = node.slice(2, -1) as MdcNode[];
|
|
282
|
+
if (anchor.text) children.push(anchor.text);
|
|
283
|
+
|
|
284
|
+
return [node[0], { ...node[1], id: anchor.id }, ...children];
|
|
285
|
+
};
|
|
286
|
+
|
|
287
|
+
/** Every generated-markup fixup the reference layout applies to a node. */
|
|
288
|
+
export const toRenderableNode = (node: MdcNode): MdcNode => {
|
|
289
|
+
return promoteBadges(promoteDeprecationCallout(normalizeAnchorId(node)));
|
|
290
|
+
};
|
|
291
|
+
|
|
292
|
+
interface DocumentSection {
|
|
293
|
+
id: string;
|
|
294
|
+
title: string;
|
|
295
|
+
nodes: MdcNode[];
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
export interface SplitDocument {
|
|
299
|
+
lead: MdcNode[];
|
|
300
|
+
sections: DocumentSection[];
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
/**
|
|
304
|
+
* Splits a document's fixed-up node list at its `h3` boundaries, so each
|
|
305
|
+
* schema section ("Arguments", "Fields", …) can be rendered on its own. The
|
|
306
|
+
* nodes before the first heading are the type/operation description and
|
|
307
|
+
* always stay together as `lead`. Shared by `useApiDocument` (one reactive
|
|
308
|
+
* page) and `useApiSinglePage` (many pages fetched at once), which is why
|
|
309
|
+
* this lives here as a plain function rather than inside either composable.
|
|
310
|
+
*/
|
|
311
|
+
export const splitDocumentSections = (nodes: MdcNode[]): SplitDocument => {
|
|
312
|
+
const lead: MdcNode[] = [];
|
|
313
|
+
const sections: DocumentSection[] = [];
|
|
314
|
+
|
|
315
|
+
for (const node of nodes) {
|
|
316
|
+
if (isElement(node, "h3")) {
|
|
317
|
+
sections.push({
|
|
318
|
+
id: node[1].id ?? `section-${sections.length}`,
|
|
319
|
+
title: nodeText(node).trim(),
|
|
320
|
+
nodes: [],
|
|
321
|
+
});
|
|
322
|
+
continue;
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
(sections.at(-1)?.nodes ?? lead).push(node);
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
return { lead, sections };
|
|
329
|
+
};
|
package/app/utils/mdc.ts
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Nuxt Content compiles Markdown into a compact AST: every element is
|
|
3
|
+
* `[tag, props, ...children]` and every text run is a plain string. These
|
|
4
|
+
* helpers are the only place that shape is unpacked, so the pages and
|
|
5
|
+
* composables above them never index into raw tuples.
|
|
6
|
+
*/
|
|
7
|
+
export type MdcNode = MdcElement | string;
|
|
8
|
+
|
|
9
|
+
export type MdcElement = [
|
|
10
|
+
tag: string,
|
|
11
|
+
props: Record<string, any>,
|
|
12
|
+
...children: MdcNode[],
|
|
13
|
+
];
|
|
14
|
+
|
|
15
|
+
export const isElement = (node: unknown, tag?: string): node is MdcElement => {
|
|
16
|
+
return Array.isArray(node) && (tag === undefined || node[0] === tag);
|
|
17
|
+
};
|
|
18
|
+
|
|
19
|
+
export const childrenOf = (node: MdcNode): MdcNode[] => {
|
|
20
|
+
return isElement(node) ? (node.slice(2) as MdcNode[]) : [];
|
|
21
|
+
};
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Flattened text of a node. Inline markup, such as a code span inside
|
|
25
|
+
* "Replaced by `Project`",
|
|
26
|
+
* splits a single sentence across several children, so prose has to be read
|
|
27
|
+
* from the flattened text rather than from any one child.
|
|
28
|
+
*/
|
|
29
|
+
export const nodeText = (node: MdcNode): string => {
|
|
30
|
+
return typeof node === "string"
|
|
31
|
+
? node
|
|
32
|
+
: childrenOf(node).map(nodeText).join("");
|
|
33
|
+
};
|
|
34
|
+
|
|
35
|
+
export const nodeClasses = (node: MdcNode): string[] => {
|
|
36
|
+
const className = isElement(node)
|
|
37
|
+
? (node[1].className ?? node[1].class ?? "")
|
|
38
|
+
: "";
|
|
39
|
+
|
|
40
|
+
return Array.isArray(className) ? className : String(className).split(" ");
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
export const hasClass = (node: MdcNode, className: string): boolean => {
|
|
44
|
+
return nodeClasses(node).includes(className);
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
/** Depth-first search for the first descendant (or `node` itself) with a class. */
|
|
48
|
+
export const findByClass = (
|
|
49
|
+
node: MdcNode,
|
|
50
|
+
className: string,
|
|
51
|
+
): MdcElement | undefined => {
|
|
52
|
+
if (!isElement(node)) return undefined;
|
|
53
|
+
if (hasClass(node, className)) return node;
|
|
54
|
+
|
|
55
|
+
return childrenOf(node)
|
|
56
|
+
.map((child) => {
|
|
57
|
+
return findByClass(child, className);
|
|
58
|
+
})
|
|
59
|
+
.find(Boolean);
|
|
60
|
+
};
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import type { ApiNavigationNode } from "~/composables/useApiNavigation";
|
|
2
|
+
|
|
3
|
+
/** Stable `v-for` key; items merged from several sections carry their section title. */
|
|
4
|
+
export const itemKey = (
|
|
5
|
+
item: ApiNavigationNode | (ApiNavigationNode & { sectionTitle: string }),
|
|
6
|
+
): string => {
|
|
7
|
+
return "sectionTitle" in item
|
|
8
|
+
? `${item.sectionTitle}-${item.title}`
|
|
9
|
+
: item.title;
|
|
10
|
+
};
|
|
11
|
+
|
|
12
|
+
export const getFirstLeafPath = (
|
|
13
|
+
node: ApiNavigationNode,
|
|
14
|
+
): string | undefined => {
|
|
15
|
+
if ("path" in node) return node.path;
|
|
16
|
+
for (const child of node.children) {
|
|
17
|
+
const path = getFirstLeafPath(child);
|
|
18
|
+
if (path) return path;
|
|
19
|
+
}
|
|
20
|
+
return undefined;
|
|
21
|
+
};
|
|
22
|
+
|
|
23
|
+
export const countLeaves = (node: ApiNavigationNode): number => {
|
|
24
|
+
if ("path" in node) return 1;
|
|
25
|
+
return node.children.reduce((sum, child) => {
|
|
26
|
+
return sum + countLeaves(child);
|
|
27
|
+
}, 0);
|
|
28
|
+
};
|