@graphql-markdown/nuxt-theme 0.1.3 → 0.2.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 +48 -36
- package/app/assets/css/main.css +2 -0
- package/app/components/ApiCodeColumn.vue +17 -24
- package/app/components/ApiNamespaceLanding.vue +9 -1
- package/app/components/ApiSinglePageEntry.vue +3 -1
- package/app/components/SchemaCodeCard.vue +34 -6
- package/app/components/SiteFooter.vue +19 -3
- package/app/composables/useActiveEntry.ts +166 -0
- package/app/composables/useApiCodeCards.ts +105 -44
- package/app/composables/useApiNavigation.ts +3 -6
- package/app/composables/useApiReferencePage.ts +27 -2
- package/app/composables/useApiSinglePage.ts +17 -64
- package/app/composables/useHierarchyMode.ts +3 -1
- package/app/layouts/reference.vue +40 -4
- package/app/pages/api-reference/[...slug].vue +39 -4
- package/app/utils/api-document.ts +21 -2
- package/app/utils/footer-ui.ts +29 -0
- package/app/utils/scroll-to-intro.ts +18 -0
- package/constants.ts +8 -0
- package/generate.ts +33 -2
- package/modules/prerender.ts +2 -2
- package/package.json +5 -5
|
@@ -7,6 +7,16 @@ import {
|
|
|
7
7
|
} from "~/utils/api-document";
|
|
8
8
|
import type { MdcNode } from "~/utils/mdc";
|
|
9
9
|
|
|
10
|
+
/** One highlighted card of the code column. */
|
|
11
|
+
export interface CodeCard {
|
|
12
|
+
label: string;
|
|
13
|
+
kind: string;
|
|
14
|
+
code: string;
|
|
15
|
+
html: string;
|
|
16
|
+
/** Example variables stacked under the card's snippet. */
|
|
17
|
+
variables?: { code: string; html: string };
|
|
18
|
+
}
|
|
19
|
+
|
|
10
20
|
/**
|
|
11
21
|
* Object and input examples are JSON payloads, operation examples and every
|
|
12
22
|
* definition are GraphQL. Highlighting JSON with the GraphQL grammar drops
|
|
@@ -23,29 +33,102 @@ export const detectLanguage = (code: string): "graphql" | "json" => {
|
|
|
23
33
|
}
|
|
24
34
|
};
|
|
25
35
|
|
|
36
|
+
const highlight = async (code: string, shikiTheme: string): Promise<string> => {
|
|
37
|
+
return codeToHtml(code, { lang: detectLanguage(code), theme: shikiTheme });
|
|
38
|
+
};
|
|
39
|
+
|
|
26
40
|
/**
|
|
27
|
-
*
|
|
28
|
-
*
|
|
41
|
+
* Builds one page's highlighted cards: the SDL definition (if any) plus every
|
|
42
|
+
* `CODE_COLUMN_SECTIONS` card the page carries code for. Sections with
|
|
43
|
+
* `attachTo` become the `variables` of the card they attach to instead of
|
|
44
|
+
* cards of their own. Shared by `useApiCodeCards` and `useApiSinglePage`.
|
|
29
45
|
*/
|
|
30
|
-
const
|
|
31
|
-
|
|
46
|
+
export const buildCodeCards = async (
|
|
47
|
+
documentBody: MdcNode[],
|
|
48
|
+
kindLabel: string,
|
|
49
|
+
isOperation: boolean,
|
|
32
50
|
shikiTheme: string,
|
|
33
|
-
): Promise<{
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
51
|
+
): Promise<{ definitionCard?: CodeCard; exampleCards: CodeCard[] }> => {
|
|
52
|
+
const definition = definitionCode(documentBody);
|
|
53
|
+
const definitionCard: CodeCard | undefined = definition
|
|
54
|
+
? {
|
|
55
|
+
label: "SDL",
|
|
56
|
+
kind: kindLabel,
|
|
57
|
+
code: definition,
|
|
58
|
+
html: await highlight(definition, shikiTheme),
|
|
59
|
+
}
|
|
60
|
+
: undefined;
|
|
61
|
+
|
|
62
|
+
const sections = CODE_COLUMN_SECTIONS.filter((section) => {
|
|
63
|
+
return !section.operationOnly || isOperation;
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
const cardEntries = await Promise.all(
|
|
67
|
+
sections
|
|
68
|
+
.filter((section) => {
|
|
69
|
+
return !section.attachTo;
|
|
38
70
|
})
|
|
39
|
-
.map(async (
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
71
|
+
.map(async (section) => {
|
|
72
|
+
const code = sectionCode(documentBody, section.title);
|
|
73
|
+
if (!code) return undefined;
|
|
74
|
+
const card: CodeCard = {
|
|
75
|
+
label: section.label ?? section.title,
|
|
76
|
+
kind: section.kind ?? kindLabel,
|
|
77
|
+
code,
|
|
78
|
+
html: await highlight(code, shikiTheme),
|
|
46
79
|
};
|
|
80
|
+
return { title: section.title, card };
|
|
47
81
|
}),
|
|
48
82
|
);
|
|
83
|
+
const built = cardEntries.filter((entry) => {
|
|
84
|
+
return entry !== undefined;
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
await Promise.all(
|
|
88
|
+
sections
|
|
89
|
+
.filter((section) => {
|
|
90
|
+
return section.attachTo;
|
|
91
|
+
})
|
|
92
|
+
.map(async (section) => {
|
|
93
|
+
const code = sectionCode(documentBody, section.title);
|
|
94
|
+
if (!code) return;
|
|
95
|
+
const html = await highlight(code, shikiTheme);
|
|
96
|
+
const target = built.find((entry) => {
|
|
97
|
+
return entry.title === section.attachTo;
|
|
98
|
+
});
|
|
99
|
+
if (target) {
|
|
100
|
+
target.card.variables = { code, html };
|
|
101
|
+
return;
|
|
102
|
+
}
|
|
103
|
+
// Nothing to stack under (no Example, or an empty one): the section
|
|
104
|
+
// is already stripped from the prose column, so show it as a card of
|
|
105
|
+
// its own rather than losing it.
|
|
106
|
+
built.push({
|
|
107
|
+
title: section.title,
|
|
108
|
+
card: {
|
|
109
|
+
label: section.label ?? section.title,
|
|
110
|
+
kind: section.kind ?? kindLabel,
|
|
111
|
+
code,
|
|
112
|
+
html,
|
|
113
|
+
},
|
|
114
|
+
});
|
|
115
|
+
}),
|
|
116
|
+
);
|
|
117
|
+
|
|
118
|
+
// Fallback cards were appended last; restore CODE_COLUMN_SECTIONS order.
|
|
119
|
+
const order = sections.map((section) => {
|
|
120
|
+
return section.title;
|
|
121
|
+
});
|
|
122
|
+
built.sort((a, b) => {
|
|
123
|
+
return order.indexOf(a.title) - order.indexOf(b.title);
|
|
124
|
+
});
|
|
125
|
+
|
|
126
|
+
return {
|
|
127
|
+
definitionCard,
|
|
128
|
+
exampleCards: built.map((entry) => {
|
|
129
|
+
return entry.card;
|
|
130
|
+
}),
|
|
131
|
+
};
|
|
49
132
|
};
|
|
50
133
|
|
|
51
134
|
/**
|
|
@@ -61,36 +144,14 @@ export const useApiCodeCards = async (
|
|
|
61
144
|
isOperation: Ref<boolean>,
|
|
62
145
|
shikiTheme: string,
|
|
63
146
|
): Promise<{
|
|
64
|
-
definitionCard:
|
|
65
|
-
|
|
66
|
-
| undefined;
|
|
67
|
-
exampleCards: { label: string; kind: string; code: string; html: string }[];
|
|
147
|
+
definitionCard: CodeCard | undefined;
|
|
148
|
+
exampleCards: CodeCard[];
|
|
68
149
|
}> => {
|
|
69
|
-
const
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
kind: schemaKind.value,
|
|
74
|
-
code: definitionCode(documentBody.value),
|
|
75
|
-
},
|
|
76
|
-
],
|
|
77
|
-
shikiTheme,
|
|
78
|
-
);
|
|
79
|
-
|
|
80
|
-
const filteredSections = CODE_COLUMN_SECTIONS.filter((section) => {
|
|
81
|
-
return !section.operationOnly || isOperation.value;
|
|
82
|
-
});
|
|
83
|
-
|
|
84
|
-
const exampleCards = await toCards(
|
|
85
|
-
filteredSections.map(({ title, label, kind }) => {
|
|
86
|
-
return {
|
|
87
|
-
label: label ?? title,
|
|
88
|
-
kind: kind ?? schemaKind.value,
|
|
89
|
-
code: sectionCode(documentBody.value, title),
|
|
90
|
-
};
|
|
91
|
-
}),
|
|
150
|
+
const { definitionCard, exampleCards } = await buildCodeCards(
|
|
151
|
+
documentBody.value,
|
|
152
|
+
schemaKind.value,
|
|
153
|
+
isOperation.value,
|
|
92
154
|
shikiTheme,
|
|
93
155
|
);
|
|
94
|
-
|
|
95
156
|
return { definitionCard, exampleCards };
|
|
96
157
|
};
|
|
@@ -1,9 +1,11 @@
|
|
|
1
1
|
import { findDeprecationNotice, titleCase } from "~/utils/api-document";
|
|
2
|
+
import { isLandingDocPath } from "../../constants";
|
|
2
3
|
|
|
3
4
|
export interface ApiNavigationLeaf {
|
|
4
5
|
title: string;
|
|
5
6
|
path: string;
|
|
6
7
|
isDeprecated: boolean;
|
|
8
|
+
active?: boolean;
|
|
7
9
|
ui?: Record<string, unknown>;
|
|
8
10
|
badge?: { label: string; color: "error"; variant: "subtle" };
|
|
9
11
|
}
|
|
@@ -23,11 +25,6 @@ interface RawPage {
|
|
|
23
25
|
kind?: string;
|
|
24
26
|
}
|
|
25
27
|
|
|
26
|
-
/** True for a namespace/schema's own generated landing doc, never a real nav entry. */
|
|
27
|
-
const isLandingDoc = (path: string): boolean => {
|
|
28
|
-
return path.endsWith("/generated");
|
|
29
|
-
};
|
|
30
|
-
|
|
31
28
|
interface Branch {
|
|
32
29
|
children: Map<string, Branch>;
|
|
33
30
|
leaves: ApiNavigationLeaf[];
|
|
@@ -145,7 +142,7 @@ export const useApiNavigation = async (): Promise<{
|
|
|
145
142
|
.then((items) => {
|
|
146
143
|
return items
|
|
147
144
|
.filter((item) => {
|
|
148
|
-
return !
|
|
145
|
+
return !isLandingDocPath(item.path);
|
|
149
146
|
})
|
|
150
147
|
.map<RawPage>((item) => {
|
|
151
148
|
return {
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { ComputedRef, Ref } from "vue";
|
|
2
2
|
import { anchorIdFor } from "~/composables/useApiSinglePage";
|
|
3
|
+
import { LANDING_DOC_NAME, isLandingDocPath } from "../../constants";
|
|
3
4
|
|
|
4
5
|
type Page = Record<string, any> | null | undefined;
|
|
5
6
|
type Resolved<T extends (...args: any[]) => any> = Awaited<ReturnType<T>>;
|
|
@@ -11,6 +12,8 @@ export interface ApiReferencePage {
|
|
|
11
12
|
isLandingPage: ComputedRef<boolean>;
|
|
12
13
|
isNamespaceChooser: ComputedRef<boolean>;
|
|
13
14
|
isFlat: Ref<boolean>;
|
|
15
|
+
landingDocument: ComputedRef<Record<string, any> | undefined>;
|
|
16
|
+
landingTitle: ComputedRef<string | undefined>;
|
|
14
17
|
buckets: Resolved<typeof useApiSinglePage>["buckets"];
|
|
15
18
|
sections: Resolved<typeof useApiNavigation>["sections"];
|
|
16
19
|
overviewGroups: ComputedRef<
|
|
@@ -55,14 +58,34 @@ export const useApiReferencePage = async (): Promise<ApiReferencePage> => {
|
|
|
55
58
|
const exact = await queryCollection("content").path(route.path).first();
|
|
56
59
|
if (exact) return exact;
|
|
57
60
|
return queryCollection("content")
|
|
58
|
-
.path(`${route.path.replace(/\/$/, "")}
|
|
61
|
+
.path(`${route.path.replace(/\/$/, "")}/${LANDING_DOC_NAME}`)
|
|
59
62
|
.first();
|
|
60
63
|
});
|
|
61
64
|
|
|
62
65
|
const page = data as Ref<Page>;
|
|
63
66
|
|
|
64
67
|
const isLandingPage = computed(() => {
|
|
65
|
-
return page.value?.path
|
|
68
|
+
return isLandingDocPath(page.value?.path ?? "");
|
|
69
|
+
});
|
|
70
|
+
|
|
71
|
+
// The schema homepage: its body goes through the same generated-markup
|
|
72
|
+
// fixups as every other document before `ContentRenderer` sees it.
|
|
73
|
+
const landingDocument = computed<Record<string, any> | undefined>(() => {
|
|
74
|
+
if (!isLandingPage.value || !page.value) {
|
|
75
|
+
return undefined;
|
|
76
|
+
}
|
|
77
|
+
const nodes: MdcNode[] = page.value.body?.value ?? [];
|
|
78
|
+
|
|
79
|
+
return {
|
|
80
|
+
...page.value,
|
|
81
|
+
body: { ...page.value.body, value: nodes.map(toRenderableNode) },
|
|
82
|
+
};
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
const landingTitle = computed<string | undefined>(() => {
|
|
86
|
+
// Empty titles are treated as absent, hence `||`.
|
|
87
|
+
// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
|
|
88
|
+
return page.value?.title || undefined;
|
|
66
89
|
});
|
|
67
90
|
|
|
68
91
|
const { sections, overviewGroupsFor } = await nuxtApp.runWithContext(
|
|
@@ -152,6 +175,8 @@ export const useApiReferencePage = async (): Promise<ApiReferencePage> => {
|
|
|
152
175
|
isLandingPage,
|
|
153
176
|
isNamespaceChooser,
|
|
154
177
|
isFlat,
|
|
178
|
+
landingDocument,
|
|
179
|
+
landingTitle,
|
|
155
180
|
buckets,
|
|
156
181
|
sections,
|
|
157
182
|
overviewGroups,
|
|
@@ -1,41 +1,26 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { isLandingDocPath } from "../../constants";
|
|
2
2
|
import {
|
|
3
|
-
CODE_COLUMN_SECTIONS,
|
|
4
3
|
codeColumnNodeIndexes,
|
|
5
|
-
definitionCode,
|
|
6
4
|
findDeprecationNotice,
|
|
7
5
|
isOperationCategory,
|
|
8
6
|
schemaKindLabel,
|
|
9
|
-
sectionCode,
|
|
10
7
|
splitDocumentSections,
|
|
11
8
|
toRenderableNode,
|
|
12
9
|
withoutDeprecationNotice,
|
|
13
10
|
} from "~/utils/api-document";
|
|
14
11
|
import type { MdcNode } from "~/utils/mdc";
|
|
15
|
-
import {
|
|
12
|
+
import { buildCodeCards, type CodeCard } from "./useApiCodeCards";
|
|
16
13
|
import type {
|
|
17
14
|
ApiNavigationBranch,
|
|
18
15
|
ApiNavigationLeaf,
|
|
19
16
|
ApiNavigationNode,
|
|
20
17
|
} from "./useApiNavigation";
|
|
21
18
|
|
|
22
|
-
/** True for a namespace/schema's own generated landing doc, never a real entry. */
|
|
23
|
-
const isLandingDoc = (path: string): boolean => {
|
|
24
|
-
return path.endsWith("/generated");
|
|
25
|
-
};
|
|
26
|
-
|
|
27
19
|
/** Anvil's own order: queries, then mutations, then subscriptions, then types. */
|
|
28
20
|
const OPERATION_KINDS = ["queries", "mutations", "subscriptions"] as const;
|
|
29
21
|
type OperationKind = (typeof OPERATION_KINDS)[number];
|
|
30
22
|
type BucketId = OperationKind | "types";
|
|
31
23
|
|
|
32
|
-
interface CodeCard {
|
|
33
|
-
label: string;
|
|
34
|
-
kind: string;
|
|
35
|
-
code: string;
|
|
36
|
-
html: string;
|
|
37
|
-
}
|
|
38
|
-
|
|
39
24
|
/**
|
|
40
25
|
* One entry of the single-page view. Typed by the swizzlable
|
|
41
26
|
* `ApiSinglePageEntry.vue` component, whose import knip can't see.
|
|
@@ -98,30 +83,6 @@ const BUCKET_TITLES: Record<BucketId, string> = {
|
|
|
98
83
|
types: "Types",
|
|
99
84
|
};
|
|
100
85
|
|
|
101
|
-
/** Highlights every card a single page carries, dropping any it has no
|
|
102
|
-
* snippet for — mirrors `useApiCodeCards`'s own `toCards`, one page at a
|
|
103
|
-
* time, so per-page work can run in parallel across the whole schema. */
|
|
104
|
-
const highlightCards = async (
|
|
105
|
-
requests: { label: string; kind: string; code?: string }[],
|
|
106
|
-
shikiTheme: string,
|
|
107
|
-
): Promise<CodeCard[]> => {
|
|
108
|
-
return Promise.all(
|
|
109
|
-
requests
|
|
110
|
-
.filter((request): request is typeof request & { code: string } => {
|
|
111
|
-
return Boolean(request.code);
|
|
112
|
-
})
|
|
113
|
-
.map(async (request) => {
|
|
114
|
-
return {
|
|
115
|
-
...request,
|
|
116
|
-
html: await codeToHtml(request.code, {
|
|
117
|
-
lang: detectLanguage(request.code),
|
|
118
|
-
theme: shikiTheme,
|
|
119
|
-
}),
|
|
120
|
-
};
|
|
121
|
-
}),
|
|
122
|
-
);
|
|
123
|
-
};
|
|
124
|
-
|
|
125
86
|
const buildEntry = async (
|
|
126
87
|
page: RawPage,
|
|
127
88
|
shikiTheme: string,
|
|
@@ -141,28 +102,13 @@ const buildEntry = async (
|
|
|
141
102
|
return { ...page, body: { ...page.body, value: nodes } };
|
|
142
103
|
};
|
|
143
104
|
|
|
144
|
-
const isOperation = isOperationCategory(page.kind);
|
|
145
105
|
const kindLabel = schemaKindLabel(page.kind);
|
|
146
|
-
const
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
[{ label: "SDL", kind: kindLabel, code: definitionCode(documentBody) }],
|
|
153
|
-
shikiTheme,
|
|
154
|
-
),
|
|
155
|
-
highlightCards(
|
|
156
|
-
filteredSections.map(({ title, label, kind }) => {
|
|
157
|
-
return {
|
|
158
|
-
label: label ?? title,
|
|
159
|
-
kind: kind ?? kindLabel,
|
|
160
|
-
code: sectionCode(documentBody, title),
|
|
161
|
-
};
|
|
162
|
-
}),
|
|
163
|
-
shikiTheme,
|
|
164
|
-
),
|
|
165
|
-
]);
|
|
106
|
+
const { definitionCard, exampleCards } = await buildCodeCards(
|
|
107
|
+
documentBody,
|
|
108
|
+
kindLabel,
|
|
109
|
+
isOperationCategory(page.kind),
|
|
110
|
+
shikiTheme,
|
|
111
|
+
);
|
|
166
112
|
|
|
167
113
|
return {
|
|
168
114
|
anchorId: anchorIdFor(page),
|
|
@@ -174,7 +120,7 @@ const buildEntry = async (
|
|
|
174
120
|
sections: sections.map(({ nodes, ...section }) => {
|
|
175
121
|
return { ...section, document: asDocument(nodes) };
|
|
176
122
|
}),
|
|
177
|
-
definitionCard
|
|
123
|
+
definitionCard,
|
|
178
124
|
exampleCards,
|
|
179
125
|
};
|
|
180
126
|
};
|
|
@@ -232,7 +178,7 @@ export const useApiSinglePage = async (
|
|
|
232
178
|
|
|
233
179
|
const rawPages = items
|
|
234
180
|
.filter((item) => {
|
|
235
|
-
return !
|
|
181
|
+
return !isLandingDocPath(item.path);
|
|
236
182
|
})
|
|
237
183
|
.map<RawPage>((item) => {
|
|
238
184
|
return {
|
|
@@ -293,9 +239,15 @@ export const useApiSinglePage = async (
|
|
|
293
239
|
* in-page hash (`#<anchorId>`) instead of a route — `UContentNavigation`'s
|
|
294
240
|
* link already treats a hash-only `to` as an in-page scroll, so no custom
|
|
295
241
|
* click handling is needed.
|
|
242
|
+
*
|
|
243
|
+
* Every leaf carries an explicit `active` flag (`true` only for the entry
|
|
244
|
+
* matching `activeAnchor`, `false` for the rest): Nuxt UI's `ULink`
|
|
245
|
+
* `isLinkActive` returns `props.active` when it is defined, and otherwise
|
|
246
|
+
* every `#hash` leaf on the same path would count as active.
|
|
296
247
|
*/
|
|
297
248
|
export const useApiSinglePageNavigation = (
|
|
298
249
|
buckets: ApiSinglePageBucket[],
|
|
250
|
+
activeAnchor?: string,
|
|
299
251
|
): ApiNavigationNode[] => {
|
|
300
252
|
return buckets.map((bucket): ApiNavigationBranch => {
|
|
301
253
|
return {
|
|
@@ -305,6 +257,7 @@ export const useApiSinglePageNavigation = (
|
|
|
305
257
|
title: entry.title,
|
|
306
258
|
path: `#${entry.anchorId}`,
|
|
307
259
|
isDeprecated: entry.isDeprecated,
|
|
260
|
+
active: entry.anchorId === activeAnchor,
|
|
308
261
|
ui: { linkTitle: "font-mono text-[small]" },
|
|
309
262
|
badge: entry.isDeprecated
|
|
310
263
|
? {
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import { isLandingDocPath } from "../../constants";
|
|
2
|
+
|
|
1
3
|
/**
|
|
2
4
|
* Detects whether the generated API reference content is using
|
|
3
5
|
* `printTypeOptions.hierarchy: "flat"` (see `@graphql-markdown/core`'s
|
|
@@ -26,7 +28,7 @@ export const useHierarchyMode = async (): Promise<{
|
|
|
26
28
|
async () => {
|
|
27
29
|
const items = await queryCollection("content").select("path").all();
|
|
28
30
|
const nonLanding = items.filter((item) => {
|
|
29
|
-
return !item.path
|
|
31
|
+
return !isLandingDocPath(item.path);
|
|
30
32
|
});
|
|
31
33
|
|
|
32
34
|
return (
|
|
@@ -36,25 +36,33 @@
|
|
|
36
36
|
title="GraphQL API"
|
|
37
37
|
:ui="{
|
|
38
38
|
container:
|
|
39
|
-
'top-(--ui-header-height) h-[calc(100vh-var(--ui-header-height))] border-r border-default bg-muted',
|
|
39
|
+
'top-(--ui-header-height) h-[calc(100vh-var(--ui-header-height)-var(--gqlmd-footer-height))] border-r border-default bg-muted',
|
|
40
40
|
header: 'px-8',
|
|
41
41
|
body: 'p-8 pt-4',
|
|
42
42
|
}"
|
|
43
43
|
class="[--sidebar-width:var(--gqlmd-sidebar-width)]"
|
|
44
44
|
>
|
|
45
45
|
<template #header>
|
|
46
|
+
<!-- The base route is where the schema homepage renders as the intro.
|
|
47
|
+
Already on it (the single-page view, scrolled down an entry), the
|
|
48
|
+
router sees no route change and wouldn't move, so scroll back up. -->
|
|
46
49
|
<NuxtLink
|
|
47
50
|
:to="baseURLPath"
|
|
48
51
|
class="block text-sm font-semibold text-dimmed transition hover:text-primary"
|
|
52
|
+
@click="onHeaderClick"
|
|
49
53
|
>
|
|
50
54
|
GraphQL API
|
|
51
55
|
</NuxtLink>
|
|
52
56
|
</template>
|
|
53
57
|
|
|
58
|
+
<!-- `default-open` opens only branches holding a leaf whose `path`
|
|
59
|
+
equals the route path. Single-page leaves are `#anchor` links that
|
|
60
|
+
never match, so there it would collapse every bucket and hide the
|
|
61
|
+
active entry; leaving it unset opens every bucket instead. -->
|
|
54
62
|
<UContentNavigation
|
|
55
63
|
class="gqlmd-api-nav"
|
|
56
64
|
:navigation="navigationSections as unknown as ContentNavigationItem[]"
|
|
57
|
-
default-open
|
|
65
|
+
:default-open="isFlat ? undefined : true"
|
|
58
66
|
:ui="{ link: 'text-sm', trigger: 'font-normal' }"
|
|
59
67
|
/>
|
|
60
68
|
</USidebar>
|
|
@@ -62,7 +70,7 @@
|
|
|
62
70
|
<slot />
|
|
63
71
|
</div>
|
|
64
72
|
|
|
65
|
-
<SiteFooter />
|
|
73
|
+
<SiteFooter sticky container-class="max-w-none px-4 md:px-8" />
|
|
66
74
|
|
|
67
75
|
<ClientOnly>
|
|
68
76
|
<!-- Nuxt UI reads the dialog's accessible name from `contentSearch.title`
|
|
@@ -81,10 +89,16 @@
|
|
|
81
89
|
<script setup lang="ts">
|
|
82
90
|
import type { ContentNavigationItem } from "@nuxt/content";
|
|
83
91
|
import { useApiSinglePageNavigation } from "~/composables/useApiSinglePage";
|
|
92
|
+
import { scrollToIntro } from "~/utils/scroll-to-intro";
|
|
84
93
|
|
|
85
94
|
const config = useAppConfig();
|
|
86
95
|
const baseURLPath = useApiBaseURL();
|
|
87
96
|
const isSidebarOpen = ref(true);
|
|
97
|
+
const route = useRoute();
|
|
98
|
+
|
|
99
|
+
const onHeaderClick = (): void => {
|
|
100
|
+
scrollToIntro(route.path, baseURLPath.value);
|
|
101
|
+
};
|
|
88
102
|
|
|
89
103
|
// @nuxt/content's ContentNavigationItem requires a `path` on every node,
|
|
90
104
|
// including branches — real Nuxt Content trees always have one (folder index
|
|
@@ -99,8 +113,30 @@ const { isFlat } = await useHierarchyMode();
|
|
|
99
113
|
const { buckets } = await useApiSinglePage(isFlat.value);
|
|
100
114
|
const { sections } = await useApiNavigation();
|
|
101
115
|
|
|
116
|
+
const { activeAnchor } = useActiveEntry(isFlat);
|
|
117
|
+
|
|
102
118
|
const navigationSections = computed(() =>
|
|
103
|
-
isFlat.value
|
|
119
|
+
isFlat.value
|
|
120
|
+
? useApiSinglePageNavigation(buckets.value, activeAnchor.value)
|
|
121
|
+
: sections.value,
|
|
122
|
+
);
|
|
123
|
+
|
|
124
|
+
// Keep the highlighted sidebar link visible as the page scrolls.
|
|
125
|
+
watch(
|
|
126
|
+
activeAnchor,
|
|
127
|
+
(id) => {
|
|
128
|
+
if (!id) {
|
|
129
|
+
return;
|
|
130
|
+
}
|
|
131
|
+
const links = document.querySelectorAll<HTMLAnchorElement>(
|
|
132
|
+
".gqlmd-api-nav a[href]",
|
|
133
|
+
);
|
|
134
|
+
const link = Array.from(links).find((candidate) => {
|
|
135
|
+
return candidate.getAttribute("href")?.endsWith(`#${id}`);
|
|
136
|
+
});
|
|
137
|
+
link?.scrollIntoView({ block: "nearest" });
|
|
138
|
+
},
|
|
139
|
+
{ flush: "post" },
|
|
104
140
|
);
|
|
105
141
|
|
|
106
142
|
const { data: searchFiles } = await useAsyncData("api-reference-search", () =>
|
|
@@ -5,9 +5,20 @@
|
|
|
5
5
|
class="grid flex-1 grid-cols-1"
|
|
6
6
|
:class="{ 'lg:grid-cols-2': !isLandingPage }"
|
|
7
7
|
>
|
|
8
|
+
<!-- `overflow-y-auto` makes this a scroll container that never actually
|
|
9
|
+
scrolls (the page scrolls, not this column), which would break
|
|
10
|
+
`position: sticky` for the code column's descendants. So it is applied
|
|
11
|
+
only where this column is not the scroll owner; the flat single-page
|
|
12
|
+
view uses `overflow-x-clip` instead. -->
|
|
8
13
|
<section
|
|
9
|
-
class="api-document max-w-none
|
|
10
|
-
:class="
|
|
14
|
+
class="api-document max-w-none p-8 lg:px-16 lg:py-20"
|
|
15
|
+
:class="[
|
|
16
|
+
{
|
|
17
|
+
'border-r border-default': !isLandingPage,
|
|
18
|
+
'overflow-y-auto': !(isLandingPage && isFlat),
|
|
19
|
+
},
|
|
20
|
+
{ 'overflow-x-clip': isLandingPage && isFlat },
|
|
21
|
+
]"
|
|
11
22
|
>
|
|
12
23
|
<UBreadcrumb
|
|
13
24
|
:items="breadcrumbs"
|
|
@@ -26,6 +37,17 @@
|
|
|
26
37
|
|
|
27
38
|
<template v-if="isLandingPage">
|
|
28
39
|
<template v-if="isFlat">
|
|
40
|
+
<header
|
|
41
|
+
v-if="landingDocument || landingTitle"
|
|
42
|
+
class="api-landing-intro mb-16"
|
|
43
|
+
>
|
|
44
|
+
<h1 v-if="landingTitle">{{ landingTitle }}</h1>
|
|
45
|
+
<ContentRenderer
|
|
46
|
+
v-if="landingDocument"
|
|
47
|
+
:value="landingDocument"
|
|
48
|
+
class="markdown-text-body markdown-lead"
|
|
49
|
+
/>
|
|
50
|
+
</header>
|
|
29
51
|
<ApiSinglePageSection
|
|
30
52
|
v-for="bucket in buckets"
|
|
31
53
|
:key="bucket.id"
|
|
@@ -34,8 +56,9 @@
|
|
|
34
56
|
</template>
|
|
35
57
|
<ApiNamespaceLanding
|
|
36
58
|
v-else
|
|
37
|
-
title="Schema Documentation"
|
|
38
|
-
description="Browse the
|
|
59
|
+
:title="landingTitle || 'Schema Documentation'"
|
|
60
|
+
description="Browse the API by operation or schema type."
|
|
61
|
+
:document="landingDocument"
|
|
39
62
|
:items="overviewGroups"
|
|
40
63
|
/>
|
|
41
64
|
</template>
|
|
@@ -80,6 +103,8 @@ const {
|
|
|
80
103
|
isLandingPage,
|
|
81
104
|
isNamespaceChooser,
|
|
82
105
|
isFlat,
|
|
106
|
+
landingDocument,
|
|
107
|
+
landingTitle,
|
|
83
108
|
buckets,
|
|
84
109
|
sections,
|
|
85
110
|
overviewGroups,
|
|
@@ -92,6 +117,16 @@ const {
|
|
|
92
117
|
</script>
|
|
93
118
|
|
|
94
119
|
<style>
|
|
120
|
+
/* The schema homepage title in the single-page view, styled like the entry
|
|
121
|
+
headings of `ApiSinglePageSection`. */
|
|
122
|
+
.api-landing-intro h1 {
|
|
123
|
+
color: var(--ui-text-highlighted);
|
|
124
|
+
font-family: var(--font-serif);
|
|
125
|
+
font-size: 2.25rem;
|
|
126
|
+
font-weight: 700;
|
|
127
|
+
margin-bottom: 1rem;
|
|
128
|
+
}
|
|
129
|
+
|
|
95
130
|
/* Everything below styles rendered content only. Scoping to
|
|
96
131
|
`.markdown-text-body` — the ContentRenderer wrapper — keeps it away from the
|
|
97
132
|
hand-written landing markup that shares the `.api-document` column. */
|
|
@@ -105,10 +105,17 @@ export const sectionCode = (
|
|
|
105
105
|
title: string,
|
|
106
106
|
): string | undefined => {
|
|
107
107
|
const index = findSectionIndex(nodes, title);
|
|
108
|
-
|
|
108
|
+
// Example Variables arrive as a ```json block, so JSON blocks count too.
|
|
109
|
+
const block =
|
|
109
110
|
index >= 0
|
|
110
|
-
?
|
|
111
|
+
? nodes.slice(index + 1).find((node): node is MdcElement => {
|
|
112
|
+
return (
|
|
113
|
+
isElement(node, "pre") &&
|
|
114
|
+
(node[1].language === "graphql" || node[1].language === "json")
|
|
115
|
+
);
|
|
116
|
+
})
|
|
111
117
|
: undefined;
|
|
118
|
+
const code = block?.[1]?.code?.trim();
|
|
112
119
|
|
|
113
120
|
// Types without a schema-defined example still emit an empty `{}` block.
|
|
114
121
|
return code && code !== "{}" ? code : undefined;
|
|
@@ -145,8 +152,20 @@ export const CODE_COLUMN_SECTIONS: {
|
|
|
145
152
|
label?: string;
|
|
146
153
|
kind?: string;
|
|
147
154
|
operationOnly?: boolean;
|
|
155
|
+
/**
|
|
156
|
+
* A section with `attachTo` is not its own card: it is stacked under the
|
|
157
|
+
* card whose section title matches this value.
|
|
158
|
+
*/
|
|
159
|
+
attachTo?: string;
|
|
148
160
|
}[] = [
|
|
149
161
|
{ title: "Example" },
|
|
162
|
+
{
|
|
163
|
+
title: "Example Variables",
|
|
164
|
+
label: "Variables",
|
|
165
|
+
kind: "JSON",
|
|
166
|
+
attachTo: "Example",
|
|
167
|
+
operationOnly: true,
|
|
168
|
+
},
|
|
150
169
|
{
|
|
151
170
|
title: "Example Response",
|
|
152
171
|
label: "Response",
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
export interface FooterUiOptions {
|
|
2
|
+
containerClass?: string;
|
|
3
|
+
sticky?: boolean;
|
|
4
|
+
}
|
|
5
|
+
|
|
6
|
+
const joinClasses = (classes: (string | false | undefined)[]): string => {
|
|
7
|
+
return classes.filter(Boolean).join(" ");
|
|
8
|
+
};
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Nuxt UI `ui` slots for the site footer. The reference layout pins the footer
|
|
12
|
+
* to the bottom of the viewport at a fixed height; the landing page keeps the
|
|
13
|
+
* default in-flow footer.
|
|
14
|
+
*/
|
|
15
|
+
export const buildFooterUi = ({
|
|
16
|
+
containerClass,
|
|
17
|
+
sticky = false,
|
|
18
|
+
}: FooterUiOptions = {}): { root: string; container: string } => {
|
|
19
|
+
return {
|
|
20
|
+
root: joinClasses([
|
|
21
|
+
"border-t border-default bg-muted",
|
|
22
|
+
sticky && "sticky bottom-0 z-40",
|
|
23
|
+
]),
|
|
24
|
+
container: joinClasses([
|
|
25
|
+
sticky ? "h-(--gqlmd-footer-height) py-0" : "py-6",
|
|
26
|
+
containerClass,
|
|
27
|
+
]),
|
|
28
|
+
};
|
|
29
|
+
};
|