@opentf/afw-docs 0.30.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/LICENSE +21 -0
- package/README.md +165 -0
- package/build/blog-posts-plugin.js +35 -18
- package/build/docs-nav-plugin.js +29 -16
- package/build/feed.js +31 -2
- 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 +13 -2
- package/build/last-updated-plugin.js +33 -19
- package/build/last-updated.js +1 -3
- package/build/llms.js +3 -3
- package/build/publish.js +29 -0
- package/build/search.js +4 -12
- package/build/vite.js +137 -0
- package/components/BlogLayout.jsx +24 -10
- package/components/FeedLinks.jsx +47 -0
- package/components/LastUpdated.jsx +4 -6
- package/components/Navbar.jsx +1 -1
- package/components/PostBanner.jsx +2 -2
- package/components/PostCard.jsx +10 -5
- package/components/PostList.jsx +11 -3
- package/components/PostMeta.jsx +11 -2
- package/components/Toc.jsx +44 -17
- package/index.js +2 -0
- package/package.json +19 -9
- package/theme/index.css +97 -3
- package/types/config.d.ts +2 -0
- package/types/index.d.ts +4 -0
- package/types/vite.d.ts +19 -0
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,12 +1,23 @@
|
|
|
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";
|
|
10
|
-
export {
|
|
16
|
+
export { isUnpublished } from "./publish.js";
|
|
17
|
+
export { postContentHtml, renderAtomFeed, renderBlogFeed } from "./feed.js";
|
|
11
18
|
export { renderLlmsFullTxt, renderLlmsTxt } from "./llms.js";
|
|
12
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,12 +8,10 @@
|
|
|
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";
|
|
14
|
+
import { frontmatterUpdated } from "./publish.js";
|
|
17
15
|
|
|
18
16
|
const VIRTUAL_ID = "@opentf/afw-docs/updated";
|
|
19
17
|
// No NUL sentinel: the bundler marks a module virtual explicitly, and a `\0` in
|
|
@@ -26,8 +24,10 @@ const MD_RE = /\.(mdx|md)$/;
|
|
|
26
24
|
* @param {Object} opts
|
|
27
25
|
* @param {string} opts.appDir
|
|
28
26
|
* @param {Set<string>} [opts.exclude] Folder names to skip (mirrors route exclusions).
|
|
27
|
+
* @param {string} [opts.blogDir] The blog folder under `app/`. Its posts take their date
|
|
28
|
+
* from frontmatter `updated` only, never git (see `collect`).
|
|
29
29
|
*/
|
|
30
|
-
export function lastUpdatedPlugin({ appDir, exclude = new Set() } = {}) {
|
|
30
|
+
export function lastUpdatedPlugin({ appDir, exclude = new Set(), blogDir } = {}) {
|
|
31
31
|
return {
|
|
32
32
|
name: "afw-last-updated",
|
|
33
33
|
resolve: {
|
|
@@ -38,33 +38,42 @@ export function lastUpdatedPlugin({ appDir, exclude = new Set() } = {}) {
|
|
|
38
38
|
filter: { id: RESOLVED_ID },
|
|
39
39
|
async handler(id) {
|
|
40
40
|
if (id !== RESOLVED_ID) return null;
|
|
41
|
-
const
|
|
42
|
-
|
|
43
|
-
// Default export: the `{ route: ISO }` last-updated map. Named `editPaths`:
|
|
44
|
-
// `{ route: repo-relative-file }`, for building "Edit this page" links.
|
|
45
|
-
return {
|
|
46
|
-
code:
|
|
47
|
-
`export default ${JSON.stringify(updated)};\n` +
|
|
48
|
-
`export const editPaths = ${JSON.stringify(editPaths)};\n`,
|
|
49
|
-
dependsOn: watch,
|
|
50
|
-
};
|
|
41
|
+
const { code, files } = await lastUpdatedModule({ appDir, exclude, blogDir });
|
|
42
|
+
return { code, dependsOn: files };
|
|
51
43
|
},
|
|
52
44
|
},
|
|
53
45
|
};
|
|
54
46
|
}
|
|
55
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
|
+
|
|
56
65
|
/**
|
|
57
66
|
* The `{ [routePath]: ISO }` last-updated map, callable directly (used by the SSG SEO
|
|
58
67
|
* step). Mirrors what the virtual module exposes.
|
|
59
68
|
*/
|
|
60
|
-
export async function loadLastUpdated({ appDir, exclude = new Set() } = {}) {
|
|
61
|
-
return (await collect(appDir, exclude, [])).updated;
|
|
69
|
+
export async function loadLastUpdated({ appDir, exclude = new Set(), blogDir } = {}) {
|
|
70
|
+
return (await collect(appDir, exclude, [], blogDir)).updated;
|
|
62
71
|
}
|
|
63
72
|
|
|
64
73
|
/** Git repo root containing `dir`, or null (so edit links degrade gracefully). */
|
|
65
74
|
const gitRoot = (dir) => runOut("git", ["rev-parse", "--show-toplevel"], dir);
|
|
66
75
|
|
|
67
|
-
async function collect(appDir, exclude, watch) {
|
|
76
|
+
async function collect(appDir, exclude, watch, blogDir) {
|
|
68
77
|
// Plugin options are plain config data, so a relative `appDir` ("app") is relative
|
|
69
78
|
// to the project directory plugins run in. Resolve it here: git runs from each
|
|
70
79
|
// page's own folder, where a relative page path would point somewhere else.
|
|
@@ -76,7 +85,12 @@ async function collect(appDir, exclude, watch) {
|
|
|
76
85
|
await walk(appDir, "", exclude, async (file, route) => {
|
|
77
86
|
watch.push(file);
|
|
78
87
|
const fm = MD_RE.test(file) ? await readFrontmatter(file) : {};
|
|
79
|
-
|
|
88
|
+
// A blog post's "updated" is an author's statement, so it is read from frontmatter
|
|
89
|
+
// alone. Git would date every post to the last bulk commit that touched them all.
|
|
90
|
+
const post = blogDir && route.startsWith(`/${blogDir}/`);
|
|
91
|
+
const iso = post
|
|
92
|
+
? (frontmatterUpdated(fm) ? await resolveLastUpdated(file, frontmatterUpdated(fm)) : null)
|
|
93
|
+
: await resolveLastUpdated(file, fm.lastUpdated);
|
|
80
94
|
if (iso) updated[route] = iso;
|
|
81
95
|
// Repo-relative path (POSIX separators) for the "Edit this page" link.
|
|
82
96
|
if (root0) editPaths[route] = relative(root0, file).split(/[\\/]/).join("/");
|
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/publish.js
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
// Publication state of a Markdown page, from its frontmatter. One rule for every place
|
|
2
|
+
// that lists or emits pages (post list, feeds, docs nav), so a draft can't show up in one
|
|
3
|
+
// and not another.
|
|
4
|
+
//
|
|
5
|
+
// A page is unpublished when it has `draft: true`, or a `date` later than now (a
|
|
6
|
+
// scheduled post). Unpublished pages are shown by the dev server (`esdev start`) only.
|
|
7
|
+
|
|
8
|
+
/** True when the frontmatter marks the page as a draft or schedules it for later. */
|
|
9
|
+
export function isUnpublished(fm, now = Date.now()) {
|
|
10
|
+
if (fm?.draft === true) return true;
|
|
11
|
+
if (fm?.date == null) return false;
|
|
12
|
+
const at = new Date(String(fm.date)).getTime();
|
|
13
|
+
return !Number.isNaN(at) && at > now;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Whether a build shows unpublished pages: only the dev server does. `ctx` is the esdev
|
|
18
|
+
* hook context (its `command` is "start" under `esdev start`); an explicit `drafts`
|
|
19
|
+
* option wins.
|
|
20
|
+
*/
|
|
21
|
+
export function showsUnpublished(drafts, ctx) {
|
|
22
|
+
return drafts ?? ctx?.command === "start";
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** A post's "updated" date from frontmatter (`updated`, or the docs-style `lastUpdated`). */
|
|
26
|
+
export function frontmatterUpdated(fm) {
|
|
27
|
+
const value = fm?.updated ?? fm?.lastUpdated;
|
|
28
|
+
return value == null || value === true || value === false ? undefined : String(value);
|
|
29
|
+
}
|
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
|
+
}
|
|
@@ -17,29 +17,37 @@
|
|
|
17
17
|
// The layout factory re-runs on every navigation (the router rebuilds the route +
|
|
18
18
|
// layout chain), so reading `router.pathname` resolves to the page being shown.
|
|
19
19
|
import { Link, RawHtml, router } from "@opentf/afw";
|
|
20
|
-
import updated from "@opentf/afw-docs/updated";
|
|
21
20
|
|
|
22
21
|
import Navbar from "./Navbar.jsx";
|
|
23
22
|
import Footer from "./Footer.jsx";
|
|
24
23
|
import Toc from "./Toc.jsx";
|
|
25
24
|
import PostBanner from "./PostBanner.jsx";
|
|
26
|
-
import
|
|
25
|
+
import FeedLinks from "./FeedLinks.jsx";
|
|
27
26
|
import { editedAfterPublish } from "./post-dates.js";
|
|
28
27
|
|
|
29
28
|
// Structured data for crawlers: the current post as a BlogPosting, emitted in
|
|
30
29
|
// the body (JSON-LD is discovered wherever it sits). `siteUrl` (optional site
|
|
31
|
-
// origin) absolutizes the post/cover URLs. Fields the post lacks are omitted.
|
|
32
|
-
|
|
30
|
+
// origin) absolutizes the post/cover URLs. Fields the post lacks are omitted. The
|
|
31
|
+
// site (`config.title`, `config.logo`) is the publisher, as Google's article
|
|
32
|
+
// guidelines ask.
|
|
33
|
+
function blogPostingJsonLd(post, siteUrl, dateModified, config = {}) {
|
|
33
34
|
const base = (siteUrl || "").replace(/\/+$/, "");
|
|
34
35
|
const abs = (p) => (p ? base + p : undefined);
|
|
35
36
|
const article = { "@context": "https://schema.org", "@type": "BlogPosting" };
|
|
36
37
|
if (post.title) article.headline = post.title;
|
|
37
38
|
if (post.description) article.description = post.description;
|
|
38
|
-
if (post.path)
|
|
39
|
+
if (post.path) {
|
|
40
|
+
article.url = abs(post.path) || post.path;
|
|
41
|
+
article.mainEntityOfPage = { "@type": "WebPage", "@id": article.url };
|
|
42
|
+
}
|
|
39
43
|
if (post.cover) article.image = abs(post.cover) || post.cover;
|
|
40
44
|
if (post.date) article.datePublished = post.date;
|
|
41
45
|
if (dateModified) article.dateModified = dateModified;
|
|
42
46
|
if (post.author) article.author = { "@type": "Person", name: post.author };
|
|
47
|
+
if (config.title) {
|
|
48
|
+
article.publisher = { "@type": "Organization", name: config.title };
|
|
49
|
+
if (config.logo) article.publisher.logo = { "@type": "ImageObject", url: abs(config.logo) || config.logo };
|
|
50
|
+
}
|
|
43
51
|
const json = JSON.stringify(article).replace(/</g, "\\u003c");
|
|
44
52
|
return `<script type="application/ld+json">${json}</script>`;
|
|
45
53
|
}
|
|
@@ -50,9 +58,12 @@ export default function BlogLayout(props) {
|
|
|
50
58
|
const frame = props.frame !== false;
|
|
51
59
|
const indexPath = props.indexPath || "/blog";
|
|
52
60
|
const siteUrl = props.siteUrl || "";
|
|
61
|
+
// Subscribe links on the index and under each post; `feeds={false}` turns them off.
|
|
62
|
+
const feeds = props.feeds !== false;
|
|
53
63
|
|
|
54
64
|
const post = posts.find((p) => p.path === router.pathname);
|
|
55
|
-
|
|
65
|
+
// The post's own frontmatter `updated`, shown in the banner. Never git: see blog-posts-plugin.js.
|
|
66
|
+
const editedIso = post && editedAfterPublish(post.updated, post.date) ? post.updated : null;
|
|
56
67
|
|
|
57
68
|
const body = post ? (
|
|
58
69
|
<div class="afwd-blog afwd-blog-post">
|
|
@@ -65,16 +76,19 @@ export default function BlogLayout(props) {
|
|
|
65
76
|
<Link href={indexPath} class="afwd-blog-back" data-afw-search-ignore>
|
|
66
77
|
← {config.title ? `${config.title} Blog` : "Blog"}
|
|
67
78
|
</Link>
|
|
68
|
-
<PostBanner post={post} />
|
|
69
|
-
<RawHtml html={blogPostingJsonLd(post, siteUrl, editedIso || post.date)} />
|
|
79
|
+
<PostBanner post={post} showUpdated />
|
|
80
|
+
<RawHtml html={blogPostingJsonLd(post, siteUrl, editedIso || post.date, config)} />
|
|
70
81
|
<article class="afwd-prose">{props.children}</article>
|
|
71
|
-
{
|
|
82
|
+
{feeds ? <FeedLinks base={indexPath} variant="inline" /> : null}
|
|
72
83
|
</main>
|
|
73
84
|
<Toc />
|
|
74
85
|
</div>
|
|
75
86
|
) : (
|
|
76
87
|
<div class="afwd-blog afwd-blog-index">
|
|
77
|
-
<main class="afwd-blog-main">
|
|
88
|
+
<main class="afwd-blog-main">
|
|
89
|
+
{feeds ? <FeedLinks base={indexPath} /> : null}
|
|
90
|
+
{props.children}
|
|
91
|
+
</main>
|
|
78
92
|
</div>
|
|
79
93
|
);
|
|
80
94
|
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
// Subscribe links for a blog's RSS and Atom feeds (`<base>/rss.xml`, `<base>/atom.xml`,
|
|
2
|
+
// written by the release build). Plain anchors, not <Link>: a feed is a file for the
|
|
3
|
+
// browser or a reader app, not a route the client router can render.
|
|
4
|
+
//
|
|
5
|
+
// `variant="icons"` (the index) shows an icon and the format name per feed;
|
|
6
|
+
// `variant="inline"` (a post's foot) is a one-line "Subscribe: RSS · Atom".
|
|
7
|
+
|
|
8
|
+
const FEEDS = [
|
|
9
|
+
{ file: "rss.xml", label: "RSS", type: "application/rss+xml" },
|
|
10
|
+
{ file: "atom.xml", label: "Atom", type: "application/atom+xml" },
|
|
11
|
+
];
|
|
12
|
+
|
|
13
|
+
function FeedIcon() {
|
|
14
|
+
return (
|
|
15
|
+
<svg class="afwd-feed-icon" viewBox="0 0 24 24" width="14" height="14" aria-hidden="true" fill="currentColor">
|
|
16
|
+
<circle cx="5" cy="19" r="2.2" />
|
|
17
|
+
<path d="M3 10.5v3a7.5 7.5 0 0 1 7.5 7.5h3A10.5 10.5 0 0 0 3 10.5Z" />
|
|
18
|
+
<path d="M3 3.5v3A14.5 14.5 0 0 1 17.5 21h3A17.5 17.5 0 0 0 3 3.5Z" />
|
|
19
|
+
</svg>
|
|
20
|
+
);
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export default function FeedLinks(props) {
|
|
24
|
+
const base = (props.base || "/blog").replace(/\/+$/, "");
|
|
25
|
+
return props.variant === "inline" ? (
|
|
26
|
+
<p class="afwd-feed-inline">
|
|
27
|
+
Subscribe:{" "}
|
|
28
|
+
<a href={`${base}/rss.xml`} type="application/rss+xml">RSS</a>
|
|
29
|
+
{" · "}
|
|
30
|
+
<a href={`${base}/atom.xml`} type="application/atom+xml">Atom</a>
|
|
31
|
+
</p>
|
|
32
|
+
) : (
|
|
33
|
+
<nav class="afwd-feed-links" aria-label="Subscribe">
|
|
34
|
+
{FEEDS.map((feed) => (
|
|
35
|
+
<a
|
|
36
|
+
class="afwd-feed-link"
|
|
37
|
+
href={`${base}/${feed.file}`}
|
|
38
|
+
type={feed.type}
|
|
39
|
+
aria-label={`Subscribe via ${feed.label}`}
|
|
40
|
+
>
|
|
41
|
+
<FeedIcon />
|
|
42
|
+
<span>{feed.label}</span>
|
|
43
|
+
</a>
|
|
44
|
+
))}
|
|
45
|
+
</nav>
|
|
46
|
+
);
|
|
47
|
+
}
|