@opentf/afw-docs 0.31.0 → 0.32.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 +24 -1
- package/build/blog-posts-plugin.js +16 -12
- package/build/docs-nav-plugin.js +21 -12
- package/build/finish.js +164 -0
- package/build/host.js +39 -21
- package/build/hosts/esdev.js +35 -0
- package/build/hosts/node.js +50 -0
- package/build/index.js +11 -1
- package/build/last-updated-plugin.js +20 -14
- package/build/last-updated.js +1 -3
- package/build/llms.js +3 -3
- package/build/search.js +4 -12
- package/build/vite.js +137 -0
- package/package.json +11 -5
- package/types/vite.d.ts +19 -0
package/README.md
CHANGED
|
@@ -89,6 +89,28 @@ to an existing project, import its stylesheet and register the build plugins:
|
|
|
89
89
|
|
|
90
90
|
`appDir` is resolved from the directory esdev runs in.
|
|
91
91
|
|
|
92
|
+
### With Vite
|
|
93
|
+
|
|
94
|
+
In the Vite + Node workflow, add `@opentf/afw-docs/vite` next to the AFW Vite plugin.
|
|
95
|
+
It reads the same `afw.config.js`, serves the generated navigation, post list and
|
|
96
|
+
last-updated map, and after the prerender writes the search index, the blog's RSS and
|
|
97
|
+
Atom feeds, and `llms.txt`:
|
|
98
|
+
|
|
99
|
+
```sh
|
|
100
|
+
pnpm add @opentf/afw-docs @opentf/afw
|
|
101
|
+
pnpm add -D vite @opentf/vite-plugin-afw
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
```js
|
|
105
|
+
// vite.config.js
|
|
106
|
+
import afw from "@opentf/vite-plugin-afw";
|
|
107
|
+
import afwDocs from "@opentf/afw-docs/vite";
|
|
108
|
+
|
|
109
|
+
export default { plugins: [afw({ mode: "ssg" }), afwDocs()] };
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
`vite build` writes the static site to `dist/`; `vite preview` serves it.
|
|
113
|
+
|
|
92
114
|
## Configure
|
|
93
115
|
|
|
94
116
|
```js
|
|
@@ -126,7 +148,8 @@ export default defineDocsConfig({
|
|
|
126
148
|
| `@opentf/afw-docs` | Every component above, plus `createSearch` |
|
|
127
149
|
| `@opentf/afw-docs/theme` | The default light/dark stylesheet |
|
|
128
150
|
| `@opentf/afw-docs/config` | `defineDocsConfig` and the config types |
|
|
129
|
-
| `@opentf/afw-docs/build` | `docsNavPlugin`, `blogPostsPlugin`, `lastUpdatedPlugin`, feed and `llms.txt` renderers |
|
|
151
|
+
| `@opentf/afw-docs/build` | `docsNavPlugin`, `blogPostsPlugin`, `lastUpdatedPlugin`, feed and `llms.txt` renderers (esdev) |
|
|
152
|
+
| `@opentf/afw-docs/vite` | `afwDocs()`: the same generators as one Vite plugin |
|
|
130
153
|
| `@opentf/afw-docs/nav`, `/posts`, `/updated` | Generated navigation, post list and last-updated map |
|
|
131
154
|
| `@opentf/afw-docs/search` | Browser search: `createSearch`, `tokenize`, `excerptParts` |
|
|
132
155
|
|
|
@@ -9,9 +9,7 @@
|
|
|
9
9
|
// overrides. Drafts and future-dated posts are left out except under `esdev start`
|
|
10
10
|
// (see publish.js).
|
|
11
11
|
|
|
12
|
-
import { join } from "
|
|
13
|
-
|
|
14
|
-
import { exists, readEntries, readNames, readText } from "./host.js";
|
|
12
|
+
import { exists, join, readEntries, readNames, readText } from "./host.js";
|
|
15
13
|
|
|
16
14
|
import { readFrontmatter } from "./frontmatter.js";
|
|
17
15
|
import { readingTime } from "./reading-time.js";
|
|
@@ -32,8 +30,6 @@ const PAGE_RE = /^page\.(mdx|md)$/;
|
|
|
32
30
|
* `esdev start`).
|
|
33
31
|
*/
|
|
34
32
|
export function blogPostsPlugin({ appDir, contentDir = "blog", exclude = new Set(), drafts } = {}) {
|
|
35
|
-
const root = join(appDir, contentDir);
|
|
36
|
-
const base = "/" + contentDir;
|
|
37
33
|
return {
|
|
38
34
|
name: "afw-blog-posts",
|
|
39
35
|
resolve: {
|
|
@@ -44,20 +40,28 @@ export function blogPostsPlugin({ appDir, contentDir = "blog", exclude = new Set
|
|
|
44
40
|
filter: { id: RESOLVED_ID },
|
|
45
41
|
async handler(id, ctx) {
|
|
46
42
|
if (id !== RESOLVED_ID) return null;
|
|
47
|
-
const
|
|
48
|
-
const all = showsUnpublished(drafts, ctx);
|
|
49
|
-
const posts = (await exists(root)) ? await collectPosts(root, base, exclude, watch, all) : [];
|
|
43
|
+
const { code, files } = await blogPostsModule({ appDir, contentDir, exclude, drafts: showsUnpublished(drafts, ctx) });
|
|
50
44
|
// The post list is generated from these files, which nothing imports —
|
|
51
45
|
// declaring them is what rebuilds the chunk when a post's frontmatter changes.
|
|
52
|
-
return {
|
|
53
|
-
code: `export const posts = ${JSON.stringify(posts)};\nexport default posts;\n`,
|
|
54
|
-
dependsOn: watch,
|
|
55
|
-
};
|
|
46
|
+
return { code, dependsOn: files };
|
|
56
47
|
},
|
|
57
48
|
},
|
|
58
49
|
};
|
|
59
50
|
}
|
|
60
51
|
|
|
52
|
+
/**
|
|
53
|
+
* The `@opentf/afw-docs/posts` module source and the post files it lists — the
|
|
54
|
+
* toolchain-neutral half of `blogPostsPlugin`, shared with the Vite plugin.
|
|
55
|
+
*
|
|
56
|
+
* @returns {Promise<{ code: string, files: string[] }>}
|
|
57
|
+
*/
|
|
58
|
+
export async function blogPostsModule({ appDir, contentDir = "blog", exclude = new Set(), drafts = false } = {}) {
|
|
59
|
+
const root = join(appDir, contentDir);
|
|
60
|
+
const watch = [];
|
|
61
|
+
const posts = (await exists(root)) ? await collectPosts(root, "/" + contentDir, exclude, watch, drafts) : [];
|
|
62
|
+
return { code: `export const posts = ${JSON.stringify(posts)};\nexport default posts;\n`, files: watch };
|
|
63
|
+
}
|
|
64
|
+
|
|
61
65
|
/**
|
|
62
66
|
* Scan the blog content folder and return the ordered post list — the same array the
|
|
63
67
|
* `blogPostsPlugin` virtual module exposes, but callable directly (used by the feed
|
package/build/docs-nav-plugin.js
CHANGED
|
@@ -10,9 +10,7 @@
|
|
|
10
10
|
// Tree node shape: `{ title, path?, order?, items?: Node[] }`. A node with `path`
|
|
11
11
|
// is a link; a node with `items` is a (possibly also linked) group.
|
|
12
12
|
|
|
13
|
-
import { join,
|
|
14
|
-
|
|
15
|
-
import { exists, readEntries, readNames, readText } from "./host.js";
|
|
13
|
+
import { exists, join, readEntries, readNames, readText, toFileUrl } from "./host.js";
|
|
16
14
|
import { readFrontmatter } from "./frontmatter.js";
|
|
17
15
|
import { isUnpublished, showsUnpublished } from "./publish.js";
|
|
18
16
|
|
|
@@ -56,22 +54,33 @@ export function docsNavPlugin({ appDir, exclude = new Set(), importModule, draft
|
|
|
56
54
|
filter: { id: RESOLVED_ID },
|
|
57
55
|
async handler(id, hookCtx) {
|
|
58
56
|
if (id !== RESOLVED_ID) return null;
|
|
59
|
-
const
|
|
60
|
-
const out = {};
|
|
61
|
-
for (const entry of await readEntries(appDir)) {
|
|
62
|
-
if (!navDirectory(entry, exclude)) continue;
|
|
63
|
-
const base = "/" + entry.name;
|
|
64
|
-
out[base] = await buildSection(join(appDir, entry.name), base, ctx, true, exclude);
|
|
65
|
-
}
|
|
57
|
+
const { code, files } = await docsNavModule({ appDir, exclude, importModule, drafts: showsUnpublished(drafts, hookCtx) });
|
|
66
58
|
// The files this tree was generated from. They are not imports, so nothing else
|
|
67
59
|
// ties them to this module — declaring them is what makes the dev server rebuild the
|
|
68
60
|
// chunk holding the sidebar when a page's frontmatter or a `_meta.*` changes.
|
|
69
|
-
return { code
|
|
61
|
+
return { code, dependsOn: files };
|
|
70
62
|
},
|
|
71
63
|
},
|
|
72
64
|
};
|
|
73
65
|
}
|
|
74
66
|
|
|
67
|
+
/**
|
|
68
|
+
* The `@opentf/afw-docs/nav` module source and the files it was generated from — the
|
|
69
|
+
* toolchain-neutral half of `docsNavPlugin`, shared with the Vite plugin.
|
|
70
|
+
*
|
|
71
|
+
* @returns {Promise<{ code: string, files: string[] }>}
|
|
72
|
+
*/
|
|
73
|
+
export async function docsNavModule({ appDir, exclude = new Set(), importModule, drafts = false } = {}) {
|
|
74
|
+
const ctx = { watch: [], importModule, drafts };
|
|
75
|
+
const out = {};
|
|
76
|
+
for (const entry of await readEntries(appDir)) {
|
|
77
|
+
if (!navDirectory(entry, exclude)) continue;
|
|
78
|
+
const base = "/" + entry.name;
|
|
79
|
+
out[base] = await buildSection(join(appDir, entry.name), base, ctx, true, exclude);
|
|
80
|
+
}
|
|
81
|
+
return { code: `export default ${JSON.stringify(out)};\n`, files: ctx.watch };
|
|
82
|
+
}
|
|
83
|
+
|
|
75
84
|
/** Load a folder's `_meta` (ordering + labels). Supports `.js`/`.mjs`/`.json`. */
|
|
76
85
|
async function loadMeta(dir, ctx) {
|
|
77
86
|
for (const name of ["_meta.js", "_meta.mjs", "_meta.json"]) {
|
|
@@ -83,7 +92,7 @@ async function loadMeta(dir, ctx) {
|
|
|
83
92
|
// A query string does not bust the ESM cache (it is keyed by path and ignores
|
|
84
93
|
// `?t=`), so a host that needs live `_meta` edits supplies a loader that can
|
|
85
94
|
// re-read the file; without one this is a plain, once-per-process import.
|
|
86
|
-
const mod = await (ctx.importModule?.(p) ?? import(
|
|
95
|
+
const mod = await (ctx.importModule?.(p) ?? import(toFileUrl(p)));
|
|
87
96
|
return mod.default ?? mod;
|
|
88
97
|
} catch (e) {
|
|
89
98
|
console.warn(`⚠ [@opentf/afw-docs] could not load ${p}: ${e?.message ?? e}`);
|
package/build/finish.js
ADDED
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
// The steps a docs or blog site runs after its pages are prerendered: the AFW Search
|
|
2
|
+
// index, RSS and Atom feeds (advertised from every page), and `llms.txt`. Shared by
|
|
3
|
+
// both workflows through the installed host (host.js). Each step reads the project's
|
|
4
|
+
// afw.config (`docs`, `blog`, `site.url`) and honours a hand-written file in
|
|
5
|
+
// `public/`.
|
|
6
|
+
|
|
7
|
+
import { exists, join, readEntries, readText, writeText } from "./host.js";
|
|
8
|
+
import { loadPosts } from "./blog-posts-plugin.js";
|
|
9
|
+
import { postContentHtml, renderAtomFeed, renderBlogFeed } from "./feed.js";
|
|
10
|
+
import { readFrontmatter } from "./frontmatter.js";
|
|
11
|
+
import { renderLlmsFullTxt, renderLlmsTxt } from "./llms.js";
|
|
12
|
+
import { isUnpublished } from "./publish.js";
|
|
13
|
+
import { indexWithAfwSearch } from "./search.js";
|
|
14
|
+
|
|
15
|
+
/** Whether "last updated" tracking is enabled anywhere (`docs`/`blog` `lastUpdated`). */
|
|
16
|
+
export function wantsLastUpdated(config) {
|
|
17
|
+
return Boolean(config?.docs?.lastUpdated || config?.blog?.lastUpdated);
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** The blog's content folder under `app/`, or undefined without a blog. */
|
|
21
|
+
export function blogDir(config) {
|
|
22
|
+
return config?.blog ? config.blog.dir ?? "blog" : undefined;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* The warning for a `docs.search.provider` other than `"afw"`, or null. A retired value
|
|
27
|
+
* would otherwise turn search off without a word.
|
|
28
|
+
*/
|
|
29
|
+
export function searchProviderWarning(config) {
|
|
30
|
+
const provider = config?.docs?.search?.provider;
|
|
31
|
+
if (provider == null || provider === "afw") return null;
|
|
32
|
+
return `⚠ docs.search.provider ${JSON.stringify(provider)} is not supported; use "afw" or remove it. Search is disabled for this build.`;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Index the prerendered site when static search is on. Errors fail the build. */
|
|
36
|
+
export async function runDocsSearchIndex(config, siteDir, afwc) {
|
|
37
|
+
if (config?.docs?.search?.provider !== "afw") return null;
|
|
38
|
+
return indexWithAfwSearch({ siteDir, afwc });
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Write `<blog>/rss.xml` and `<blog>/atom.xml` with each post's full content, read back
|
|
43
|
+
* from its prerendered page, and link them from every page's `<head>`. Needs the site
|
|
44
|
+
* URL. Returns `{ paths, urls, count }`, or null when skipped.
|
|
45
|
+
*/
|
|
46
|
+
export async function runBlogFeed({ root, appDir, config, siteDir, baseUrl, exclude = new Set() }) {
|
|
47
|
+
const blog = config?.blog;
|
|
48
|
+
if (!blog) return null;
|
|
49
|
+
if (!baseUrl) {
|
|
50
|
+
console.warn("⚠ blog feeds skipped: no site URL (set site.url in afw.config)");
|
|
51
|
+
return null;
|
|
52
|
+
}
|
|
53
|
+
const contentDir = blog.dir ?? "blog";
|
|
54
|
+
const posts = await loadPosts({ appDir, contentDir, exclude });
|
|
55
|
+
for (const post of posts) {
|
|
56
|
+
const page = join(siteDir, post.path.replace(/^\/+/, ""), "index.html");
|
|
57
|
+
if (await exists(page)) post.content = postContentHtml(await readText(page), baseUrl, post.cover);
|
|
58
|
+
}
|
|
59
|
+
const title = blog.title || (config?.docs?.title ? `${config.docs.title} Blog` : "Blog");
|
|
60
|
+
const channel = {
|
|
61
|
+
title,
|
|
62
|
+
description: blog.description || title,
|
|
63
|
+
link: `/${contentDir}`,
|
|
64
|
+
language: blog.language || config?.i18n?.defaultLocale || "en",
|
|
65
|
+
};
|
|
66
|
+
const feeds = [
|
|
67
|
+
{ file: "rss.xml", path: `/${contentDir}/rss.xml`, render: renderBlogFeed },
|
|
68
|
+
{ file: "atom.xml", path: `/${contentDir}/atom.xml`, render: renderAtomFeed },
|
|
69
|
+
];
|
|
70
|
+
const written = [];
|
|
71
|
+
for (const feed of feeds) {
|
|
72
|
+
if (await exists(join(root, "public", contentDir, feed.file))) continue; // honour an override
|
|
73
|
+
await writeText(join(siteDir, contentDir, feed.file), feed.render({ posts, baseUrl, feedPath: feed.path, channel }));
|
|
74
|
+
written.push(feed.path);
|
|
75
|
+
}
|
|
76
|
+
if (!written.length) return null;
|
|
77
|
+
await injectFeedLinks(siteDir, title, contentDir);
|
|
78
|
+
const origin = baseUrl.replace(/\/+$/, "");
|
|
79
|
+
return { paths: written, urls: written.map((path) => origin + path), count: posts.length };
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* Advertise the feeds from every prerendered page: RSS and Atom `<link rel="alternate">`
|
|
84
|
+
* in each `<head>`. A page that already declares a feed is left alone.
|
|
85
|
+
*/
|
|
86
|
+
async function injectFeedLinks(siteDir, title, contentDir) {
|
|
87
|
+
const t = String(title).replace(/&/g, "&").replace(/"/g, """).replace(/</g, "<");
|
|
88
|
+
const links =
|
|
89
|
+
`<link rel="alternate" type="application/rss+xml" title="${t}" href="/${contentDir}/rss.xml">\n` +
|
|
90
|
+
`<link rel="alternate" type="application/atom+xml" title="${t}" href="/${contentDir}/atom.xml">\n`;
|
|
91
|
+
const walk = async (dir) => {
|
|
92
|
+
for (const entry of await readEntries(dir)) {
|
|
93
|
+
const full = join(dir, entry.name);
|
|
94
|
+
if (entry.isDir) await walk(full);
|
|
95
|
+
else if (entry.name.endsWith(".html")) {
|
|
96
|
+
const html = await readText(full);
|
|
97
|
+
if (/type="application\/(rss|atom)\+xml"/.test(html) || !/<\/head>/i.test(html)) continue;
|
|
98
|
+
await writeText(full, html.replace(/<\/head>/i, () => `${links}</head>`));
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
};
|
|
102
|
+
await walk(siteDir);
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/** The app's published page, layout and 404 files (what `llms.txt` summarizes). */
|
|
106
|
+
export async function publishedPages(appDir, exclude = new Set()) {
|
|
107
|
+
const out = [];
|
|
108
|
+
const walk = async (dir) => {
|
|
109
|
+
for (const entry of await readEntries(dir)) {
|
|
110
|
+
if (entry.isDir) {
|
|
111
|
+
if (!exclude.has(entry.name) && !entry.name.startsWith(".") && entry.name !== "node_modules") await walk(join(dir, entry.name));
|
|
112
|
+
continue;
|
|
113
|
+
}
|
|
114
|
+
if (!/^(page|layout|404)\.(mdx|md|[jt]sx)$/.test(entry.name)) continue;
|
|
115
|
+
const file = join(dir, entry.name);
|
|
116
|
+
if (/\.(mdx|md)$/.test(entry.name) && isUnpublished(await readFrontmatter(file))) continue;
|
|
117
|
+
out.push(file);
|
|
118
|
+
}
|
|
119
|
+
};
|
|
120
|
+
await walk(appDir);
|
|
121
|
+
return out.sort();
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Write `/llms.txt` and `/llms-full.txt` for a docs or blog site. A file in `public/`
|
|
126
|
+
* overrides each one. `siteDescription` summarizes the site (from its own metadata).
|
|
127
|
+
*/
|
|
128
|
+
export async function runLlmsFiles({ root, appDir, pages, config, siteDir, baseUrl, siteDescription = "" }) {
|
|
129
|
+
if (!config?.docs && !config?.blog) return null;
|
|
130
|
+
const outputs = [
|
|
131
|
+
{ file: "llms.txt", render: renderLlmsTxt },
|
|
132
|
+
{ file: "llms-full.txt", render: renderLlmsFullTxt },
|
|
133
|
+
];
|
|
134
|
+
const written = [];
|
|
135
|
+
for (const out of outputs) {
|
|
136
|
+
if (await exists(join(root, "public", out.file))) continue;
|
|
137
|
+
await writeText(join(siteDir, out.file), await out.render({ appDir, pages, baseUrl, config, siteDescription }));
|
|
138
|
+
written.push(`/${out.file}`);
|
|
139
|
+
}
|
|
140
|
+
return written.length ? { paths: written } : null;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/**
|
|
144
|
+
* Every finishing step, in order, for a prerendered site in `siteDir`. Returns what
|
|
145
|
+
* each step produced (null for a skipped step).
|
|
146
|
+
*/
|
|
147
|
+
export async function finishSite({ root, appDir, config, siteDir, baseUrl = "", exclude = new Set(), siteDescription = "", afwc }) {
|
|
148
|
+
const warning = searchProviderWarning(config);
|
|
149
|
+
if (warning) console.warn(warning);
|
|
150
|
+
// A failed search index fails the build; feeds and llms.txt warn and carry on.
|
|
151
|
+
const search = await runDocsSearchIndex(config, siteDir, afwc);
|
|
152
|
+
const optional = async (label, step) => {
|
|
153
|
+
try {
|
|
154
|
+
return await step();
|
|
155
|
+
} catch (e) {
|
|
156
|
+
console.warn(`⚠ ${label} skipped: ${e?.message ?? e}`);
|
|
157
|
+
return null;
|
|
158
|
+
}
|
|
159
|
+
};
|
|
160
|
+
const feeds = await optional("blog feeds", () => runBlogFeed({ root, appDir, config, siteDir, baseUrl, exclude }));
|
|
161
|
+
const llms = await optional("llms.txt", async () =>
|
|
162
|
+
runLlmsFiles({ root, appDir, pages: await publishedPages(appDir, exclude), config, siteDir, baseUrl, siteDescription }));
|
|
163
|
+
return { search, feeds, llms };
|
|
164
|
+
}
|
package/build/host.js
CHANGED
|
@@ -1,28 +1,41 @@
|
|
|
1
|
-
// Host primitives for the docs build hooks.
|
|
1
|
+
// Host primitives for the docs build hooks, shared by both AFW workflows.
|
|
2
2
|
//
|
|
3
|
-
//
|
|
4
|
-
//
|
|
5
|
-
// the
|
|
6
|
-
//
|
|
3
|
+
// The build modules here use no platform modules (`runtime:*`, `node:*`). Each entry point
|
|
4
|
+
// installs the host for its platform before anything runs: `@opentf/afw-docs/build`
|
|
5
|
+
// the ES-Runtime host (esdev), `@opentf/afw-docs/vite` the Node host (Vite). A
|
|
6
|
+
// process builds with one toolchain, so one installed host serves every module.
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
8
|
+
let current = null;
|
|
9
|
+
|
|
10
|
+
/** Install the platform host (hosts/esdev.js or hosts/node.js). */
|
|
11
|
+
export function useHost(host) {
|
|
12
|
+
current = host;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
function host() {
|
|
16
|
+
if (!current) {
|
|
17
|
+
throw new Error("@opentf/afw-docs: no build host. Import @opentf/afw-docs/build (esdev) or @opentf/afw-docs/vite (Vite).");
|
|
18
|
+
}
|
|
19
|
+
return current;
|
|
20
|
+
}
|
|
10
21
|
|
|
11
22
|
/** Whether `path` exists — false rather than throwing when it is out of reach. */
|
|
12
23
|
export async function exists(path) {
|
|
13
24
|
try {
|
|
14
|
-
return await
|
|
25
|
+
return Boolean(await host().kind(path));
|
|
15
26
|
} catch {
|
|
16
27
|
return false;
|
|
17
28
|
}
|
|
18
29
|
}
|
|
19
30
|
|
|
20
|
-
export const readText = (path) =>
|
|
31
|
+
export const readText = (path) => host().readText(path);
|
|
32
|
+
|
|
33
|
+
export const writeText = (path, text) => host().writeText(path, text);
|
|
21
34
|
|
|
22
|
-
/** Directory entries, or `[]` when the directory is missing. */
|
|
35
|
+
/** Directory entries (`{ name, isFile, isDir }`), or `[]` when the directory is missing. */
|
|
23
36
|
export async function readEntries(dir) {
|
|
24
37
|
try {
|
|
25
|
-
return await readDir(dir);
|
|
38
|
+
return await host().readDir(dir);
|
|
26
39
|
} catch {
|
|
27
40
|
return [];
|
|
28
41
|
}
|
|
@@ -34,21 +47,26 @@ export async function readNames(dir) {
|
|
|
34
47
|
}
|
|
35
48
|
|
|
36
49
|
/**
|
|
37
|
-
* Run a command and return its trimmed stdout, or null if it failed. Git is the
|
|
50
|
+
* Run a command and return its trimmed stdout, or null if it failed. Git is the main
|
|
38
51
|
* caller, and a repo-less checkout must degrade to "no last-updated", never throw.
|
|
39
52
|
*/
|
|
40
53
|
export async function runOut(program, args, cwd) {
|
|
41
54
|
try {
|
|
42
|
-
|
|
43
|
-
args,
|
|
44
|
-
cwd,
|
|
45
|
-
stdout: "piped",
|
|
46
|
-
stderr: "null",
|
|
47
|
-
inheritEnv: true,
|
|
48
|
-
}).output();
|
|
49
|
-
if (!out.success) return null;
|
|
50
|
-
return new TextDecoder().decode(out.stdout).trim();
|
|
55
|
+
return await host().output(program, args, { cwd });
|
|
51
56
|
} catch {
|
|
52
57
|
return null;
|
|
53
58
|
}
|
|
54
59
|
}
|
|
60
|
+
|
|
61
|
+
/** Run a command; resolves `{ ok, stdout, stderr }` (stdout and stderr as text). */
|
|
62
|
+
export const run = (program, args, options) => host().exec(program, args, options);
|
|
63
|
+
|
|
64
|
+
export const join = (...parts) => host().path.join(...parts);
|
|
65
|
+
export const dirname = (path) => host().path.dirname(path);
|
|
66
|
+
export const relative = (from, to) => host().path.relative(from, to);
|
|
67
|
+
export const resolve = (...parts) => host().path.resolve(...parts);
|
|
68
|
+
/** A `file:` URL for importing a module by path. */
|
|
69
|
+
export const toFileUrl = (path) => host().path.toFileUrl(path);
|
|
70
|
+
export const cwd = () => host().cwd();
|
|
71
|
+
/** The `afwc` compiler binary (for the search indexer). */
|
|
72
|
+
export const afwcPath = () => host().afwcPath();
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
// The ES-Runtime host for the docs build (installed by `@opentf/afw-docs/build`).
|
|
2
|
+
import { exists as fsExists, file, mkdir, readDir, stat, write } from "runtime:fs";
|
|
3
|
+
import { dirname, join, relative, resolve, toFileURL } from "runtime:path";
|
|
4
|
+
import { cwd } from "runtime:process";
|
|
5
|
+
import { Command } from "runtime:system";
|
|
6
|
+
|
|
7
|
+
import { afwcPath } from "@opentf/afw-compiler";
|
|
8
|
+
|
|
9
|
+
async function exec(program, args, { cwd: dir } = {}) {
|
|
10
|
+
const out = await new Command(program, { args, cwd: dir, stdout: "piped", stderr: "piped", inheritEnv: true }).output();
|
|
11
|
+
const text = (bytes) => new TextDecoder().decode(bytes);
|
|
12
|
+
return { ok: out.success, stdout: text(out.stdout), stderr: text(out.stderr) };
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
export const esdevHost = {
|
|
16
|
+
readText: (path) => file(path).text(),
|
|
17
|
+
readDir: (path) => readDir(path),
|
|
18
|
+
async writeText(path, text) {
|
|
19
|
+
await mkdir(dirname(path), { recursive: true });
|
|
20
|
+
await write(path, text);
|
|
21
|
+
},
|
|
22
|
+
async kind(path) {
|
|
23
|
+
if (!(await fsExists(path))) return null;
|
|
24
|
+
const s = await stat(path);
|
|
25
|
+
return s.isDir ? "dir" : s.isFile ? "file" : null;
|
|
26
|
+
},
|
|
27
|
+
exec,
|
|
28
|
+
async output(program, args, options) {
|
|
29
|
+
const out = await exec(program, args, options);
|
|
30
|
+
return out.ok ? out.stdout.trim() : null;
|
|
31
|
+
},
|
|
32
|
+
cwd: () => cwd(),
|
|
33
|
+
afwcPath: () => afwcPath(),
|
|
34
|
+
path: { join, dirname, relative, resolve, toFileUrl: (path) => toFileURL(path).href },
|
|
35
|
+
};
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
// The Node host for the docs build (installed by `@opentf/afw-docs/vite`).
|
|
2
|
+
import { execFile } from "node:child_process";
|
|
3
|
+
import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
|
|
4
|
+
import path from "node:path";
|
|
5
|
+
import { pathToFileURL } from "node:url";
|
|
6
|
+
|
|
7
|
+
import { afwcPath } from "@opentf/afw-compiler/node";
|
|
8
|
+
|
|
9
|
+
const slash = (p) => p.replaceAll("\\", "/");
|
|
10
|
+
|
|
11
|
+
function exec(program, args, { cwd } = {}) {
|
|
12
|
+
return new Promise((resolve) => {
|
|
13
|
+
execFile(program, args, { cwd, maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => {
|
|
14
|
+
resolve({ ok: !error, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") });
|
|
15
|
+
});
|
|
16
|
+
});
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export const nodeHost = {
|
|
20
|
+
readText: (file) => readFile(file, "utf8"),
|
|
21
|
+
async readDir(dir) {
|
|
22
|
+
return (await readdir(dir, { withFileTypes: true })).map((e) => ({ name: e.name, isFile: e.isFile(), isDir: e.isDirectory() }));
|
|
23
|
+
},
|
|
24
|
+
async writeText(file, text) {
|
|
25
|
+
await mkdir(path.dirname(file), { recursive: true });
|
|
26
|
+
await writeFile(file, text);
|
|
27
|
+
},
|
|
28
|
+
async kind(file) {
|
|
29
|
+
try {
|
|
30
|
+
const s = await stat(file);
|
|
31
|
+
return s.isDirectory() ? "dir" : s.isFile() ? "file" : null;
|
|
32
|
+
} catch {
|
|
33
|
+
return null;
|
|
34
|
+
}
|
|
35
|
+
},
|
|
36
|
+
exec,
|
|
37
|
+
async output(program, args, options) {
|
|
38
|
+
const out = await exec(program, args, options);
|
|
39
|
+
return out.ok ? out.stdout.trim() : null;
|
|
40
|
+
},
|
|
41
|
+
cwd: () => slash(process.cwd()),
|
|
42
|
+
afwcPath: () => afwcPath(),
|
|
43
|
+
path: {
|
|
44
|
+
join: (...parts) => slash(path.join(...parts)),
|
|
45
|
+
dirname: (p) => slash(path.dirname(p)),
|
|
46
|
+
relative: (from, to) => slash(path.relative(from, to)),
|
|
47
|
+
resolve: (...parts) => slash(path.resolve(...parts)),
|
|
48
|
+
toFileUrl: (p) => pathToFileURL(p).href,
|
|
49
|
+
},
|
|
50
|
+
};
|
package/build/index.js
CHANGED
|
@@ -1,9 +1,15 @@
|
|
|
1
|
-
// Build-time entry for the docs toolchain integration.
|
|
1
|
+
// Build-time entry for the docs toolchain integration on esdev (ES-Runtime). The
|
|
2
|
+
// Vite workflow uses `@opentf/afw-docs/vite`, which installs the Node host instead.
|
|
2
3
|
//
|
|
3
4
|
// Re-exports the nav plugin (registered by @opentf/afw-cli when a project
|
|
4
5
|
// has a `docs` config) and the AFW Search indexing function. Importing this
|
|
5
6
|
// from afw-cli keeps all docs-specific build logic owned by this package.
|
|
6
7
|
|
|
8
|
+
import { useHost } from "./host.js";
|
|
9
|
+
import { esdevHost } from "./hosts/esdev.js";
|
|
10
|
+
|
|
11
|
+
useHost(esdevHost);
|
|
12
|
+
|
|
7
13
|
export { docsNavPlugin } from "./docs-nav-plugin.js";
|
|
8
14
|
export { blogPostsPlugin, loadPosts } from "./blog-posts-plugin.js";
|
|
9
15
|
export { lastUpdatedPlugin, loadLastUpdated } from "./last-updated-plugin.js";
|
|
@@ -11,3 +17,7 @@ export { isUnpublished } from "./publish.js";
|
|
|
11
17
|
export { postContentHtml, renderAtomFeed, renderBlogFeed } from "./feed.js";
|
|
12
18
|
export { renderLlmsFullTxt, renderLlmsTxt } from "./llms.js";
|
|
13
19
|
export { indexWithAfwSearch } from "./search.js";
|
|
20
|
+
export { blogPostsModule } from "./blog-posts-plugin.js";
|
|
21
|
+
export { docsNavModule } from "./docs-nav-plugin.js";
|
|
22
|
+
export { lastUpdatedModule } from "./last-updated-plugin.js";
|
|
23
|
+
export { finishSite, publishedPages, runBlogFeed, runDocsSearchIndex, runLlmsFiles, searchProviderWarning, wantsLastUpdated } from "./finish.js";
|
|
@@ -8,10 +8,7 @@
|
|
|
8
8
|
// The same map is needed by the SSG step for the `article:modified_time` SEO tag, so
|
|
9
9
|
// the scan is exposed as a callable (`loadLastUpdated`) too.
|
|
10
10
|
|
|
11
|
-
import { join, relative, resolve } from "
|
|
12
|
-
import { cwd } from "runtime:process";
|
|
13
|
-
|
|
14
|
-
import { readEntries, runOut } from "./host.js";
|
|
11
|
+
import { cwd, join, readEntries, relative, resolve, runOut } from "./host.js";
|
|
15
12
|
import { readFrontmatter } from "./frontmatter.js";
|
|
16
13
|
import { resolveLastUpdated } from "./last-updated.js";
|
|
17
14
|
import { frontmatterUpdated } from "./publish.js";
|
|
@@ -41,21 +38,30 @@ export function lastUpdatedPlugin({ appDir, exclude = new Set(), blogDir } = {})
|
|
|
41
38
|
filter: { id: RESOLVED_ID },
|
|
42
39
|
async handler(id) {
|
|
43
40
|
if (id !== RESOLVED_ID) return null;
|
|
44
|
-
const
|
|
45
|
-
|
|
46
|
-
// Default export: the `{ route: ISO }` last-updated map. Named `editPaths`:
|
|
47
|
-
// `{ route: repo-relative-file }`, for building "Edit this page" links.
|
|
48
|
-
return {
|
|
49
|
-
code:
|
|
50
|
-
`export default ${JSON.stringify(updated)};\n` +
|
|
51
|
-
`export const editPaths = ${JSON.stringify(editPaths)};\n`,
|
|
52
|
-
dependsOn: watch,
|
|
53
|
-
};
|
|
41
|
+
const { code, files } = await lastUpdatedModule({ appDir, exclude, blogDir });
|
|
42
|
+
return { code, dependsOn: files };
|
|
54
43
|
},
|
|
55
44
|
},
|
|
56
45
|
};
|
|
57
46
|
}
|
|
58
47
|
|
|
48
|
+
/**
|
|
49
|
+
* The `@opentf/afw-docs/updated` module source and the page files it covers — the
|
|
50
|
+
* toolchain-neutral half of `lastUpdatedPlugin`, shared with the Vite plugin. Default
|
|
51
|
+
* export: the `{ route: ISO }` last-updated map. Named `editPaths`:
|
|
52
|
+
* `{ route: repo-relative-file }`, for building "Edit this page" links.
|
|
53
|
+
*
|
|
54
|
+
* @returns {Promise<{ code: string, files: string[] }>}
|
|
55
|
+
*/
|
|
56
|
+
export async function lastUpdatedModule({ appDir, exclude = new Set(), blogDir } = {}) {
|
|
57
|
+
const watch = [];
|
|
58
|
+
const { updated, editPaths } = await collect(appDir, exclude, watch, blogDir);
|
|
59
|
+
return {
|
|
60
|
+
code: `export default ${JSON.stringify(updated)};\nexport const editPaths = ${JSON.stringify(editPaths)};\n`,
|
|
61
|
+
files: watch,
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
|
|
59
65
|
/**
|
|
60
66
|
* The `{ [routePath]: ISO }` last-updated map, callable directly (used by the SSG SEO
|
|
61
67
|
* step). Mirrors what the virtual module exposes.
|
package/build/last-updated.js
CHANGED
|
@@ -8,9 +8,7 @@
|
|
|
8
8
|
// isn't in git history the value is simply null and the UI omits it. This runs in dev
|
|
9
9
|
// and build alike — the displayed time is always the real last content change.
|
|
10
10
|
|
|
11
|
-
import { dirname } from "
|
|
12
|
-
|
|
13
|
-
import { runOut } from "./host.js";
|
|
11
|
+
import { dirname, runOut } from "./host.js";
|
|
14
12
|
|
|
15
13
|
/** Last git commit (committer ISO-8601) that touched `file`, or null. */
|
|
16
14
|
export async function gitLastUpdated(file) {
|
package/build/llms.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { dirname, relative
|
|
1
|
+
import { dirname, relative } from "./host.js";
|
|
2
2
|
|
|
3
3
|
import { exists, readText } from "./host.js";
|
|
4
4
|
|
|
@@ -12,9 +12,9 @@ function abs(baseUrl, path) {
|
|
|
12
12
|
}
|
|
13
13
|
|
|
14
14
|
function routePath(appDir, file) {
|
|
15
|
-
const rel = relative(appDir, file).split(
|
|
15
|
+
const rel = relative(appDir, file).split(/[\\/]/).join("/");
|
|
16
16
|
if (!PAGE_RE.test(rel)) return null;
|
|
17
|
-
const dir = dirname(rel).split(
|
|
17
|
+
const dir = dirname(rel).split(/[\\/]/).join("/");
|
|
18
18
|
if (dir === ".") return "/";
|
|
19
19
|
const segments = dir.split("/");
|
|
20
20
|
if (segments.some((seg) => seg.startsWith("_") || seg.startsWith(".") || seg.includes("["))) {
|
package/build/search.js
CHANGED
|
@@ -1,8 +1,6 @@
|
|
|
1
1
|
// Build-time AFW Search indexing; called after prerendering by the finish plugin.
|
|
2
2
|
|
|
3
|
-
import { join } from "
|
|
4
|
-
import { Command } from "runtime:system";
|
|
5
|
-
import { afwcPath } from "@opentf/afw-compiler";
|
|
3
|
+
import { afwcPath, join, run } from "./host.js";
|
|
6
4
|
|
|
7
5
|
/**
|
|
8
6
|
* Build the index from prerendered HTML using the unified native toolchain.
|
|
@@ -11,15 +9,9 @@ import { afwcPath } from "@opentf/afw-compiler";
|
|
|
11
9
|
*/
|
|
12
10
|
export async function indexWithAfwSearch({ siteDir, afwc }) {
|
|
13
11
|
const binary = afwc || await afwcPath();
|
|
14
|
-
const
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
stderr: "piped",
|
|
18
|
-
inheritEnv: true,
|
|
19
|
-
});
|
|
20
|
-
const result = await out.output();
|
|
21
|
-
if (!result.success) throw new Error(new TextDecoder().decode(result.stderr).trim() || "afwc docs index failed");
|
|
22
|
-
const message = new TextDecoder().decode(result.stderr);
|
|
12
|
+
const result = await run(binary, ["docs", "index", siteDir, "--out", join(siteDir, "_search"), "--root", "main"]);
|
|
13
|
+
if (!result.ok) throw new Error(result.stderr.trim() || "afwc docs index failed");
|
|
14
|
+
const message = result.stderr;
|
|
23
15
|
const indexed = /indexed\s+(\d+)\s+page/.exec(message);
|
|
24
16
|
if (!indexed) throw new Error("afwc docs index did not report an index. Install the updated @opentf/afw-compiler containing the docs indexing command.");
|
|
25
17
|
const pages = Number(indexed[1]);
|
package/build/vite.js
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
// `@opentf/afw-docs/vite` — the docs and blog generators for the Vite + Node workflow.
|
|
2
|
+
// Pair it with `@opentf/vite-plugin-afw`:
|
|
3
|
+
//
|
|
4
|
+
// import afw from "@opentf/vite-plugin-afw";
|
|
5
|
+
// import afwDocs from "@opentf/afw-docs/vite";
|
|
6
|
+
// export default { plugins: [afw({ mode: "ssg" }), afwDocs()] };
|
|
7
|
+
//
|
|
8
|
+
// It reads the same afw.config as the esdev workflow and serves the same virtual
|
|
9
|
+
// modules: `@opentf/afw-docs/nav` (with a `docs` block), `/posts` (with `blog`) and
|
|
10
|
+
// `/updated` (with `lastUpdated`). After an SSG prerender it indexes search, writes the
|
|
11
|
+
// blog feeds and `llms.txt`.
|
|
12
|
+
|
|
13
|
+
import { stat } from "node:fs/promises";
|
|
14
|
+
import path from "node:path";
|
|
15
|
+
import { pathToFileURL } from "node:url";
|
|
16
|
+
|
|
17
|
+
import { useHost } from "./host.js";
|
|
18
|
+
import { nodeHost } from "./hosts/node.js";
|
|
19
|
+
import { blogPostsModule } from "./blog-posts-plugin.js";
|
|
20
|
+
import { docsNavModule } from "./docs-nav-plugin.js";
|
|
21
|
+
import { blogDir, finishSite, wantsLastUpdated } from "./finish.js";
|
|
22
|
+
import { lastUpdatedModule, loadLastUpdated } from "./last-updated-plugin.js";
|
|
23
|
+
|
|
24
|
+
useHost(nodeHost);
|
|
25
|
+
|
|
26
|
+
export { finishSite } from "./finish.js";
|
|
27
|
+
|
|
28
|
+
const MODULES = ["nav", "posts", "updated"];
|
|
29
|
+
const VIRTUAL = (name) => `\0@opentf/afw-docs/${name}`;
|
|
30
|
+
// Files whose edits change the generated modules: pages (frontmatter) and `_meta.*`.
|
|
31
|
+
const SOURCE_FILE = /(?:^|\/)(?:page\.(?:mdx|md|[jt]sx)|_meta\.(?:js|mjs|json))$/;
|
|
32
|
+
const slash = (p) => p.replaceAll("\\", "/");
|
|
33
|
+
|
|
34
|
+
/** The project's afw.config (`.json`, `.js` or `.mjs`), or `{}`. */
|
|
35
|
+
export async function loadConfig(root) {
|
|
36
|
+
for (const name of ["afw.config.json", "afw.config.js", "afw.config.mjs"]) {
|
|
37
|
+
const file = path.join(root, name);
|
|
38
|
+
let info;
|
|
39
|
+
try {
|
|
40
|
+
info = await stat(file);
|
|
41
|
+
} catch {
|
|
42
|
+
continue;
|
|
43
|
+
}
|
|
44
|
+
if (name.endsWith(".json")) return JSON.parse(await nodeHost.readText(file)) ?? {};
|
|
45
|
+
const mod = await import(`${pathToFileURL(file).href}?t=${info.mtimeMs}`);
|
|
46
|
+
return mod.default ?? {};
|
|
47
|
+
}
|
|
48
|
+
return {};
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
// `_meta.js` read fresh after an edit: Node caches modules by URL, so the URL carries
|
|
52
|
+
// the file's modification time.
|
|
53
|
+
async function importFresh(file) {
|
|
54
|
+
const { mtimeMs } = await stat(file);
|
|
55
|
+
return import(`${pathToFileURL(file).href}?t=${mtimeMs}`);
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* @param {{ config?: object, appDir?: string, exclude?: string[] }} [options]
|
|
60
|
+
* `config` — the docs config (default: afw.config from the project root).
|
|
61
|
+
* `appDir` — the routes folder. `exclude` — folders under it that hold no pages.
|
|
62
|
+
*/
|
|
63
|
+
export default function afwDocs({ config: given, appDir: appDirOption = "app", exclude = [] } = {}) {
|
|
64
|
+
let config = given ?? {};
|
|
65
|
+
let root = slash(process.cwd());
|
|
66
|
+
let appDir = "";
|
|
67
|
+
let command = "serve";
|
|
68
|
+
const excluded = new Set(exclude);
|
|
69
|
+
|
|
70
|
+
const enabled = (name) =>
|
|
71
|
+
name === "nav" ? Boolean(config.docs) : name === "posts" ? Boolean(config.blog) : wantsLastUpdated(config);
|
|
72
|
+
|
|
73
|
+
async function generate(name) {
|
|
74
|
+
const drafts = command === "serve";
|
|
75
|
+
if (name === "nav") return docsNavModule({ appDir, exclude: excluded, importModule: importFresh, drafts });
|
|
76
|
+
if (name === "posts") return blogPostsModule({ appDir, contentDir: blogDir(config), exclude: excluded, drafts });
|
|
77
|
+
return lastUpdatedModule({ appDir, exclude: excluded, blogDir: blogDir(config) });
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
return {
|
|
81
|
+
name: "afw-docs",
|
|
82
|
+
enforce: "pre",
|
|
83
|
+
|
|
84
|
+
async configResolved(resolved) {
|
|
85
|
+
root = slash(resolved.root);
|
|
86
|
+
command = resolved.command;
|
|
87
|
+
appDir = slash(path.resolve(root, appDirOption));
|
|
88
|
+
if (!given) config = await loadConfig(root);
|
|
89
|
+
},
|
|
90
|
+
|
|
91
|
+
configureServer(server) {
|
|
92
|
+
// A page added, removed or renamed changes the navigation and post list.
|
|
93
|
+
const refresh = (file) => {
|
|
94
|
+
const p = slash(file);
|
|
95
|
+
if (!p.startsWith(`${appDir}/`) || !SOURCE_FILE.test(p)) return;
|
|
96
|
+
for (const env of Object.values(server.environments ?? { client: server })) {
|
|
97
|
+
for (const name of MODULES) {
|
|
98
|
+
const mod = env.moduleGraph?.getModuleById?.(VIRTUAL(name));
|
|
99
|
+
if (mod) env.moduleGraph.invalidateModule(mod);
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
server.ws.send({ type: "full-reload" });
|
|
103
|
+
};
|
|
104
|
+
server.watcher.on("add", refresh);
|
|
105
|
+
server.watcher.on("unlink", refresh);
|
|
106
|
+
},
|
|
107
|
+
|
|
108
|
+
resolveId(source) {
|
|
109
|
+
const name = source.startsWith("@opentf/afw-docs/") ? source.slice("@opentf/afw-docs/".length) : null;
|
|
110
|
+
return name && MODULES.includes(name) && enabled(name) ? VIRTUAL(name) : null;
|
|
111
|
+
},
|
|
112
|
+
|
|
113
|
+
async load(id) {
|
|
114
|
+
const name = MODULES.find((n) => id === VIRTUAL(n));
|
|
115
|
+
if (!name) return null;
|
|
116
|
+
const { code, files } = await generate(name);
|
|
117
|
+
for (const file of files) this.addWatchFile(file);
|
|
118
|
+
return { code, map: null };
|
|
119
|
+
},
|
|
120
|
+
|
|
121
|
+
// Read by @opentf/vite-plugin-afw around its SSG prerender.
|
|
122
|
+
api: {
|
|
123
|
+
/** Data the prerender needs: the site URL and per-page last-updated times. */
|
|
124
|
+
async afwPrerenderData() {
|
|
125
|
+
const lastUpdated = wantsLastUpdated(config)
|
|
126
|
+
? await loadLastUpdated({ appDir, exclude: excluded, blogDir: blogDir(config) })
|
|
127
|
+
: {};
|
|
128
|
+
return { baseUrl: String(config?.site?.url ?? "").replace(/\/+$/, ""), lastUpdated };
|
|
129
|
+
},
|
|
130
|
+
/** Search index, feeds and llms.txt over the prerendered site. */
|
|
131
|
+
async afwFinish({ outDir, siteDescription = "", baseUrl = "", afwc }) {
|
|
132
|
+
if (!config.docs && !config.blog) return null;
|
|
133
|
+
return finishSite({ root, appDir, config, siteDir: slash(outDir), baseUrl, exclude: excluded, siteDescription, afwc });
|
|
134
|
+
},
|
|
135
|
+
},
|
|
136
|
+
};
|
|
137
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@opentf/afw-docs",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.32.0",
|
|
4
4
|
"description": "Documentation and blog sites built as ordinary AFW apps.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"scripts": {
|
|
@@ -29,6 +29,10 @@
|
|
|
29
29
|
"default": "./updated-virtual.js"
|
|
30
30
|
},
|
|
31
31
|
"./build": "./build/index.js",
|
|
32
|
+
"./vite": {
|
|
33
|
+
"types": "./types/vite.d.ts",
|
|
34
|
+
"default": "./build/vite.js"
|
|
35
|
+
},
|
|
32
36
|
"./search": {
|
|
33
37
|
"types": "./types/search.d.ts",
|
|
34
38
|
"default": "./search.js"
|
|
@@ -65,17 +69,19 @@
|
|
|
65
69
|
"bugs": "https://github.com/Open-Tech-Foundation/afw/issues",
|
|
66
70
|
"license": "MIT",
|
|
67
71
|
"peerDependencies": {
|
|
68
|
-
"@opentf/afw": "0.
|
|
72
|
+
"@opentf/afw": "0.34.0"
|
|
69
73
|
},
|
|
70
74
|
"publishConfig": {
|
|
71
75
|
"access": "public"
|
|
72
76
|
},
|
|
73
77
|
"dependencies": {
|
|
74
|
-
"@opentf/afw-compiler": "0.
|
|
78
|
+
"@opentf/afw-compiler": "0.22.0"
|
|
75
79
|
},
|
|
76
80
|
"devDependencies": {
|
|
77
|
-
"@opentf/afw": "0.
|
|
78
|
-
"@opentf/afw-test": "1.
|
|
81
|
+
"@opentf/afw": "0.34.0",
|
|
82
|
+
"@opentf/afw-test": "1.29.0",
|
|
83
|
+
"@opentf/vite-plugin-afw": "0.1.0",
|
|
84
|
+
"vite": "8.3.5"
|
|
79
85
|
},
|
|
80
86
|
"types": "./types/index.d.ts"
|
|
81
87
|
}
|
package/types/vite.d.ts
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import type { Plugin } from "vite";
|
|
2
|
+
|
|
3
|
+
export interface AfwDocsViteOptions {
|
|
4
|
+
/** The docs config. Default: afw.config.{json,js,mjs} from the project root. */
|
|
5
|
+
config?: Record<string, unknown>;
|
|
6
|
+
/** The routes folder. Default `"app"`. */
|
|
7
|
+
appDir?: string;
|
|
8
|
+
/** Folders under `appDir` that hold no pages. */
|
|
9
|
+
exclude?: string[];
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
/** The docs and blog generators for Vite: navigation, posts, last-updated, search, feeds, llms.txt. */
|
|
13
|
+
export default function afwDocs(options?: AfwDocsViteOptions): Plugin;
|
|
14
|
+
|
|
15
|
+
/** Run the post-prerender steps (search index, feeds, llms.txt) yourself. */
|
|
16
|
+
export function finishSite(options: Record<string, unknown>): Promise<unknown>;
|
|
17
|
+
|
|
18
|
+
/** The project's afw.config, or `{}`. */
|
|
19
|
+
export function loadConfig(root: string): Promise<Record<string, unknown>>;
|