@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.
- package/README.md +69 -67
- 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 +10 -10
|
@@ -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) {
|
package/modules/prerender.ts
CHANGED
|
@@ -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) ===
|
|
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
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "A Nuxt layer for building GraphQL API reference sites",
|
|
5
5
|
"homepage": "https://graphql-markdown.dev",
|
|
6
6
|
"bugs": {
|
|
@@ -36,8 +36,8 @@
|
|
|
36
36
|
"build": "echo \"no build step — Nuxt layer ships source\"",
|
|
37
37
|
"lint": "eslint --config ../../packages/tooling-config/eslint/config.ts \"app/**/*.{ts,vue}\" \"modules/**/*.ts\" \"*.ts\" \"*.mjs\" \"bin/**/*.mjs\" \"tests/**/*.ts\" --ignore-pattern \"tests/fixture*/**\"",
|
|
38
38
|
"lint:fix": "eslint --config ../../packages/tooling-config/eslint/config.ts \"app/**/*.{ts,vue}\" \"modules/**/*.ts\" \"*.ts\" \"*.mjs\" \"bin/**/*.mjs\" \"tests/**/*.ts\" --ignore-pattern \"tests/fixture*/**\" --fix",
|
|
39
|
-
"prettier": "prettier \"app/**/*.{ts,vue,css}\" \"modules/**/*.ts\" \"*.ts\" \"*.mjs\" \"bin/**/*.mjs\" \"tests/**/*.ts\" \"!tests/fixture*/**\" --check",
|
|
40
|
-
"prettier:fix": "prettier \"app/**/*.{ts,vue,css}\" \"modules/**/*.ts\" \"*.ts\" \"*.mjs\" \"bin/**/*.mjs\" \"tests/**/*.ts\" \"!tests/fixture*/**\" --write",
|
|
39
|
+
"prettier": "prettier \"app/**/*.{ts,vue,css}\" \"modules/**/*.ts\" \"*.ts\" \"*.mjs\" \"bin/**/*.mjs\" \"tests/**/*.ts\" \"!tests/fixture*/**\" README.md --check",
|
|
40
|
+
"prettier:fix": "prettier \"app/**/*.{ts,vue,css}\" \"modules/**/*.ts\" \"*.ts\" \"*.mjs\" \"bin/**/*.mjs\" \"tests/**/*.ts\" \"!tests/fixture*/**\" README.md --write",
|
|
41
41
|
"ts:check": "nuxi typecheck",
|
|
42
42
|
"test": "vitest run --passWithNoTests",
|
|
43
43
|
"test:unit": "vitest run --passWithNoTests tests/unit",
|
|
@@ -46,9 +46,9 @@
|
|
|
46
46
|
},
|
|
47
47
|
"dependencies": {
|
|
48
48
|
"@clack/prompts": "^1.0.0",
|
|
49
|
-
"@graphql-markdown/cli": "^1.1
|
|
50
|
-
"@nuxt/content": "^3.16.
|
|
51
|
-
"@nuxt/kit": "^4.
|
|
49
|
+
"@graphql-markdown/cli": "^1.2.1",
|
|
50
|
+
"@nuxt/content": "^3.16.2",
|
|
51
|
+
"@nuxt/kit": "^4.6.1",
|
|
52
52
|
"@nuxt/ui": "^4.11.0",
|
|
53
53
|
"consola": "^3.4.2",
|
|
54
54
|
"shiki": "^4.4.3",
|
|
@@ -56,13 +56,13 @@
|
|
|
56
56
|
},
|
|
57
57
|
"devDependencies": {
|
|
58
58
|
"@graphql-markdown/tooling-config": "^1.0.0",
|
|
59
|
-
"nuxt": "^4.
|
|
59
|
+
"nuxt": "^4.6.0",
|
|
60
60
|
"typescript": "6.0.3",
|
|
61
|
-
"vue-router": "^5.
|
|
62
|
-
"vue-tsc": "^3.3.
|
|
61
|
+
"vue-router": "^5.4.0",
|
|
62
|
+
"vue-tsc": "^3.3.13"
|
|
63
63
|
},
|
|
64
64
|
"engines": {
|
|
65
|
-
"node": ">=22.
|
|
65
|
+
"node": ">=22.18.0"
|
|
66
66
|
},
|
|
67
67
|
"publishConfig": {
|
|
68
68
|
"access": "public"
|