@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.
@@ -0,0 +1,18 @@
1
+ /**
2
+ * When the current route is already the API base route, the router sees no
3
+ * route change on a link back to it, so scroll the page to the top instead.
4
+ * Returns whether a scroll happened.
5
+ */
6
+ export const scrollToIntro = (
7
+ currentPath: string,
8
+ baseURLPath: string,
9
+ scroll: (options: ScrollToOptions) => void = (options) => {
10
+ window.scrollTo(options);
11
+ },
12
+ ): boolean => {
13
+ if (currentPath.replace(/\/$/, "") !== baseURLPath) {
14
+ return false;
15
+ }
16
+ scroll({ top: 0, behavior: "smooth" });
17
+ return true;
18
+ };
package/constants.ts CHANGED
@@ -1,2 +1,10 @@
1
1
  /** Default value for `gqlmd.baseURL` / `createGenerateDocs`'s `baseURL` option — the shared route prefix every page and content-generation call resolves against unless overridden. */
2
2
  export const DEFAULT_BASE_URL = "api-reference";
3
+
4
+ /** Name (without extension) every landing doc is stored under — the theme finds the schema homepage by this name, whatever the template was called. */
5
+ export const LANDING_DOC_NAME = "generated";
6
+
7
+ /** True when the last path segment is the landing doc name (`/api-reference/generated`), never for lookalikes such as `generated-things`. */
8
+ export const isLandingDocPath = (path: string): boolean => {
9
+ return path.split("/").findLast(Boolean) === LANDING_DOC_NAME;
10
+ };
package/generate.ts CHANGED
@@ -1,8 +1,11 @@
1
1
  // generate.ts
2
+ import { rename } from "node:fs/promises";
3
+ import { basename, join } from "node:path";
4
+
2
5
  import { useLogger } from "@nuxt/kit";
3
6
 
4
7
  import { runGraphQLMarkdown } from "@graphql-markdown/cli";
5
- import { DEFAULT_BASE_URL } from "./constants";
8
+ import { DEFAULT_BASE_URL, LANDING_DOC_NAME } from "./constants.ts";
6
9
 
7
10
  /**
8
11
  * `@graphql-markdown/types` is a transitive dependency, so the option shape is
@@ -30,6 +33,9 @@ const DEFAULT_LOADERS = {
30
33
  * - decorators: Custom decorators for the schema output
31
34
  * - formatter: Path/URL to custom formatter module (default: this package's formatter.mjs)
32
35
  * - loaders: Custom schema loaders (default: GraphQLFileLoader)
36
+ * - homepage: Path to a markdown template rendered as the intro of the API
37
+ * reference, or `false` to disable it (default: GraphQL-Markdown's built-in
38
+ * homepage). Whatever its file name, it is stored as `generated.md`.
33
39
  * @returns A function that generates the documentation when called
34
40
  */
35
41
  export const createGenerateDocs = (userOptions: {
@@ -40,6 +46,7 @@ export const createGenerateDocs = (userOptions: {
40
46
  decorators?: NonNullable<GraphQLMarkdownOptions["decorators"]>;
41
47
  formatter?: string;
42
48
  loaders?: NonNullable<GraphQLMarkdownOptions["loaders"]>;
49
+ homepage?: string | false;
43
50
  }): (() => Promise<void>) => {
44
51
  const {
45
52
  schema,
@@ -49,6 +56,7 @@ export const createGenerateDocs = (userOptions: {
49
56
  decorators,
50
57
  formatter = new URL("./formatter.mjs", import.meta.url).href,
51
58
  loaders = DEFAULT_LOADERS,
59
+ homepage,
52
60
  } = userOptions;
53
61
 
54
62
  const logger = useLogger("gqlmd-generate");
@@ -76,11 +84,34 @@ export const createGenerateDocs = (userOptions: {
76
84
 
77
85
  // Custom decorators, if provided
78
86
  ...(decorators && { decorators }),
87
+
88
+ // Homepage template (or `false` to disable), only when set
89
+ ...(homepage !== undefined && { homepage }),
79
90
  };
80
91
 
81
92
  return async () => {
82
93
  try {
83
- await runGraphQLMarkdown(options, {}, import.meta.resolve("consola"));
94
+ await runGraphQLMarkdown(options, {}, import.meta.resolve("consola"), {
95
+ trigger: "nuxt",
96
+ });
97
+
98
+ // The theme finds the landing doc by name, so a custom template keeps
99
+ // working whatever it's called: GraphQL-Markdown copies it under its own
100
+ // file name, which is renamed (overwriting) to the expected one.
101
+ if (
102
+ typeof homepage === "string" &&
103
+ basename(homepage) !== `${LANDING_DOC_NAME}.md`
104
+ ) {
105
+ try {
106
+ await rename(
107
+ join(rootPath, baseURL, basename(homepage)),
108
+ join(rootPath, baseURL, `${LANDING_DOC_NAME}.md`),
109
+ );
110
+ } catch (error) {
111
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
112
+ logger.warn(`Homepage ${homepage} was not rendered; skipping rename`);
113
+ }
114
+ }
84
115
 
85
116
  logger.info(`GraphQL Markdown generated in ${rootPath}/${baseURL}/`);
86
117
  } catch (error) {
@@ -2,7 +2,7 @@ import { readdir } from "node:fs/promises";
2
2
  import { join, relative, sep } from "node:path";
3
3
 
4
4
  import { defineNuxtModule, useNuxt } from "@nuxt/kit";
5
- import { DEFAULT_BASE_URL } from "../constants";
5
+ import { DEFAULT_BASE_URL, LANDING_DOC_NAME } from "../constants.ts";
6
6
 
7
7
  /**
8
8
  * Enumerates every generated content route for the prerenderer.
@@ -62,7 +62,7 @@ export const routeFor = (
62
62
  const relativePath = relative(contentDir, file);
63
63
  const segments = relativePath.replace(/\.md$/, "").split(sep);
64
64
 
65
- if (segments.at(-1) === "generated") {
65
+ if (segments.at(-1) === LANDING_DOC_NAME) {
66
66
  return `/${segments.slice(0, -1).join("/")}`;
67
67
  }
68
68
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@graphql-markdown/nuxt-theme",
3
- "version": "0.1.3",
3
+ "version": "0.2.0",
4
4
  "description": "A Nuxt layer for building GraphQL API reference sites",
5
5
  "homepage": "https://graphql-markdown.dev",
6
6
  "bugs": {
@@ -46,9 +46,9 @@
46
46
  },
47
47
  "dependencies": {
48
48
  "@clack/prompts": "^1.0.0",
49
- "@graphql-markdown/cli": "^1.1.2",
49
+ "@graphql-markdown/cli": "^1.2.0",
50
50
  "@nuxt/content": "^3.16.0",
51
- "@nuxt/kit": "^4.5.2",
51
+ "@nuxt/kit": "^4.6.0",
52
52
  "@nuxt/ui": "^4.11.0",
53
53
  "consola": "^3.4.2",
54
54
  "shiki": "^4.4.3",
@@ -56,9 +56,9 @@
56
56
  },
57
57
  "devDependencies": {
58
58
  "@graphql-markdown/tooling-config": "^1.0.0",
59
- "nuxt": "^4.5.2",
59
+ "nuxt": "^4.6.0",
60
60
  "typescript": "6.0.3",
61
- "vue-router": "^5.3.1",
61
+ "vue-router": "^5.4.0",
62
62
  "vue-tsc": "^3.3.11"
63
63
  },
64
64
  "engines": {