@graphql-markdown/nuxt-theme 0.2.4 → 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 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"
@@ -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: isLandingPage.value
164
- ? current.title
165
- : `API Reference | ${current.title}`,
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,
@@ -32,7 +33,7 @@ export interface ApiSinglePageEntry {
32
33
  title: string;
33
34
  kindLabel: string;
34
35
  isDeprecated: boolean;
35
- deprecationReason?: string;
36
+ deprecationReason?: DeprecationNotice;
36
37
  lead?: Record<string, any>;
37
38
  sections: { id: string; title: string; document: Record<string, any> }[];
38
39
  definitionCard?: CodeCard;
@@ -278,6 +279,9 @@ export const useApiSinglePageNavigation = (
278
279
  variant: "subtle" as const,
279
280
  }
280
281
  : undefined,
282
+ "aria-label": entry.isDeprecated
283
+ ? `${entry.title} (deprecated)`
284
+ : undefined,
281
285
  };
282
286
  }),
283
287
  };
@@ -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
- * A type retired with `@deprecatedType` states its replacement as prose above
126
- * the definition rather than through the standard `@deprecated` directive.
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
- ): string | undefined => {
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
- return metadataNodes.map(nodeText).find((text) => {
139
- return text.includes("Replaced by");
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
- reason?: string,
242
+ notice?: DeprecationNotice,
196
243
  ): MdcNode[] => {
197
- if (!reason) return nodes;
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 !nodeText(node).includes(reason);
255
+ return node !== notice.node;
209
256
  });
210
257
  };
211
258
 
212
259
  /**
213
- * Field-level deprecations are emitted as a raw `<aside>`. Swap them for the
214
- * same UAlert the type-level notice uses so both render identically.
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) || !hasClass(node, "api-deprecation-callout"))
218
- return node;
265
+ if (!isElement(node)) return node;
219
266
 
220
- const message = findByClass(node, "api-deprecation-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
+ };
@@ -44,6 +44,22 @@ const anchorFromId = (id: string): string => {
44
44
  return base.split("/").findLast(Boolean) ?? base;
45
45
  };
46
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
+
47
63
  /**
48
64
  * Cleans search sections and, in flat (single-page) mode, points every
49
65
  * section at its entry's `#<anchorId>` so it matches the single-page
@@ -57,9 +73,11 @@ export const toSinglePageSearchSections = <T extends SearchSection>(
57
73
  return files.map((file) => {
58
74
  const cleaned = {
59
75
  ...file,
60
- title: stripAnchorMarker(file.title),
61
- titles: file.titles.map(stripAnchorMarker),
62
- content: stripShikiCss(file.content),
76
+ title: normalizeSearchText(stripAnchorMarker(file.title)),
77
+ titles: file.titles.map((t) => {
78
+ return normalizeSearchText(stripAnchorMarker(t));
79
+ }),
80
+ content: normalizeSearchText(stripShikiCss(file.content)),
63
81
  };
64
82
  return isFlat ? { ...cleaned, id: `#${anchorFromId(file.id)}` } : cleaned;
65
83
  });
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
- return `<aside class="api-deprecation-callout not-prose mb-8"><span class="api-deprecated-badge">deprecated</span><span class="api-deprecation-message">${text.trim()}</span></aside>`;
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 = (userOptions: {
42
- schema: string;
43
- rootPath?: string;
44
- baseURL?: string;
45
- printTypeOptions?: Partial<GraphQLMarkdownOptions["printTypeOptions"]>;
46
- decorators?: NonNullable<GraphQLMarkdownOptions["decorators"]>;
47
- formatter?: string;
48
- loaders?: NonNullable<GraphQLMarkdownOptions["loaders"]>;
49
- homepage?: string | false;
50
- }): (() => Promise<void>) => {
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,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@graphql-markdown/nuxt-theme",
3
- "version": "0.2.4",
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.2.3",
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",