@graphql-markdown/nuxt-theme 0.1.3 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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
- * Highlights the code column's cards, dropping any the page carries no snippet
28
- * for: the landing page has no definition, and most types define no example.
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 toCards = async (
31
- cards: { label: string; kind: string; code?: string }[],
46
+ export const buildCodeCards = async (
47
+ documentBody: MdcNode[],
48
+ kindLabel: string,
49
+ isOperation: boolean,
32
50
  shikiTheme: string,
33
- ): Promise<{ label: string; kind: string; code: string; html: string }[]> => {
34
- return Promise.all(
35
- cards
36
- .filter((card): card is typeof card & { code: string } => {
37
- return Boolean(card.code);
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 (card) => {
40
- return {
41
- ...card,
42
- html: await codeToHtml(card.code, {
43
- lang: detectLanguage(card.code),
44
- theme: shikiTheme,
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
- | { label: string; kind: string; code: string; html: string }
66
- | undefined;
67
- exampleCards: { label: string; kind: string; code: string; html: string }[];
147
+ definitionCard: CodeCard | undefined;
148
+ exampleCards: CodeCard[];
68
149
  }> => {
69
- const [definitionCard] = await toCards(
70
- [
71
- {
72
- label: "SDL",
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 !isLandingDoc(item.path);
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(/\/$/, "")}/generated`)
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?.endsWith("/generated") ?? false;
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 { codeToHtml } from "shiki";
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 { detectLanguage } from "./useApiCodeCards";
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 filteredSections = CODE_COLUMN_SECTIONS.filter((section) => {
147
- return !section.operationOnly || isOperation;
148
- });
149
-
150
- const [definitionCard, exampleCards] = await Promise.all([
151
- highlightCards(
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: definitionCard[0],
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 !isLandingDoc(item.path);
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.endsWith("/generated");
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 ? useApiSinglePageNavigation(buckets.value) : sections.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 overflow-y-auto p-8 lg:px-16 lg:py-20"
10
- :class="{ 'border-r border-default': !isLandingPage }"
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 workspace API by operation or schema type. Every page includes its definition, related fields, and examples when available."
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
- const code =
108
+ // Example Variables arrive as a ```json block, so JSON blocks count too.
109
+ const block =
109
110
  index >= 0
110
- ? findGraphqlCode(nodes, index + 1)?.[1]?.code?.trim()
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
+ };