@opentf/afw-docs 0.0.0-stage → 0.30.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/build/blog-posts-plugin.js +141 -0
- package/build/docs-nav-plugin.js +196 -0
- package/build/feed.js +147 -0
- package/build/frontmatter.js +45 -0
- package/build/host.js +54 -0
- package/build/index.js +12 -0
- package/build/last-updated-plugin.js +99 -0
- package/build/last-updated.js +40 -0
- package/build/llms.js +176 -0
- package/build/reading-time.js +16 -0
- package/build/search.js +27 -0
- package/components/BlogLayout.jsx +90 -0
- package/components/Breadcrumbs.jsx +71 -0
- package/components/Callout.jsx +29 -0
- package/components/Card.jsx +21 -0
- package/components/Cards.jsx +11 -0
- package/components/CodeBlock.jsx +39 -0
- package/components/DocsLayout.jsx +106 -0
- package/components/Footer.jsx +25 -0
- package/components/LastUpdated.jsx +22 -0
- package/components/NavIcon.jsx +34 -0
- package/components/Navbar.jsx +64 -0
- package/components/NavbarLink.jsx +40 -0
- package/components/Pagination.jsx +49 -0
- package/components/PostBanner.jsx +25 -0
- package/components/PostCard.jsx +19 -0
- package/components/PostList.jsx +17 -0
- package/components/PostMeta.jsx +28 -0
- package/components/ReadingTime.jsx +6 -0
- package/components/Search.jsx +191 -0
- package/components/SearchTrigger.jsx +32 -0
- package/components/Sidebar.jsx +199 -0
- package/components/SidebarNode.jsx +143 -0
- package/components/SidebarToggle.jsx +47 -0
- package/components/Steps.jsx +14 -0
- package/components/Table.jsx +10 -0
- package/components/Tabs.jsx +77 -0
- package/components/ThemeToggle.jsx +164 -0
- package/components/Toc.jsx +79 -0
- package/components/Tooltip.jsx +19 -0
- package/components/format.js +21 -0
- package/components/post-dates.js +21 -0
- package/components/sidebar-collapse.js +38 -0
- package/config.js +77 -0
- package/index.js +67 -0
- package/nav-virtual.js +18 -0
- package/package.json +75 -4
- package/posts-virtual.js +17 -0
- package/search.js +285 -0
- package/theme/index.css +1749 -0
- package/types/config.d.ts +37 -0
- package/types/index.d.ts +66 -0
- package/types/nav.d.ts +9 -0
- package/types/posts.d.ts +17 -0
- package/types/search.d.ts +28 -0
- package/types/updated.d.ts +4 -0
- package/updated-virtual.js +10 -0
- package/README.md +0 -3
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
// Build-time blog post index generator (a Rolldown plugin), the blog counterpart of
|
|
2
|
+
// docs-nav-plugin.js. It scans `app/<dir>` for post folders (`<slug>/page.{mdx,md}`),
|
|
3
|
+
// reads each post's frontmatter + computes its reading time, and resolves the virtual
|
|
4
|
+
// module `@opentf/afw-docs/posts` to the ordered post list. A pure build-time
|
|
5
|
+
// consumer of the file tree — no compiler stage, no runtime cost.
|
|
6
|
+
//
|
|
7
|
+
// Post shape: `{ slug, path, title, description?, date?, author?, tags?, readingTime,
|
|
8
|
+
// order? }`. Sorted newest-first by `date`; a numeric `order` (frontmatter) overrides.
|
|
9
|
+
|
|
10
|
+
import { join } from "runtime:path";
|
|
11
|
+
|
|
12
|
+
import { exists, readEntries, readNames, readText } from "./host.js";
|
|
13
|
+
|
|
14
|
+
import { readFrontmatter } from "./frontmatter.js";
|
|
15
|
+
import { readingTime } from "./reading-time.js";
|
|
16
|
+
|
|
17
|
+
const VIRTUAL_ID = "@opentf/afw-docs/posts";
|
|
18
|
+
// No NUL sentinel: the bundler marks a module virtual explicitly, and a `\0` in
|
|
19
|
+
// a hook filter is an invalid regex — which silently matches *everything*.
|
|
20
|
+
const RESOLVED_ID = "afw-virtual:afw-blog-posts";
|
|
21
|
+
const PAGE_RE = /^page\.(mdx|md)$/;
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* @param {Object} opts
|
|
25
|
+
* @param {string} opts.appDir Absolute path to the project's `app/` directory.
|
|
26
|
+
* @param {string} [opts.contentDir] Blog content folder under app/ (default "blog").
|
|
27
|
+
* @param {Set<string>} [opts.exclude] Folder names to skip.
|
|
28
|
+
*/
|
|
29
|
+
export function blogPostsPlugin({ appDir, contentDir = "blog", exclude = new Set() } = {}) {
|
|
30
|
+
const root = join(appDir, contentDir);
|
|
31
|
+
const base = "/" + contentDir;
|
|
32
|
+
return {
|
|
33
|
+
name: "afw-blog-posts",
|
|
34
|
+
resolve: {
|
|
35
|
+
filter: { id: VIRTUAL_ID },
|
|
36
|
+
handler: (source) => (source === VIRTUAL_ID ? { id: RESOLVED_ID, virtual: true } : null),
|
|
37
|
+
},
|
|
38
|
+
load: {
|
|
39
|
+
filter: { id: RESOLVED_ID },
|
|
40
|
+
async handler(id) {
|
|
41
|
+
if (id !== RESOLVED_ID) return null;
|
|
42
|
+
const watch = [];
|
|
43
|
+
const posts = (await exists(root)) ? await collectPosts(root, base, exclude, watch) : [];
|
|
44
|
+
// The post list is generated from these files, which nothing imports —
|
|
45
|
+
// declaring them is what rebuilds the chunk when a post's frontmatter changes.
|
|
46
|
+
return {
|
|
47
|
+
code: `export const posts = ${JSON.stringify(posts)};\nexport default posts;\n`,
|
|
48
|
+
dependsOn: watch,
|
|
49
|
+
};
|
|
50
|
+
},
|
|
51
|
+
},
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Scan the blog content folder and return the ordered post list — the same array the
|
|
57
|
+
* `blogPostsPlugin` virtual module exposes, but callable directly (used by the feed
|
|
58
|
+
* generator at build time). Returns `[]` when the folder is absent.
|
|
59
|
+
*
|
|
60
|
+
* @param {Object} opts
|
|
61
|
+
* @param {string} opts.appDir
|
|
62
|
+
* @param {string} [opts.contentDir]
|
|
63
|
+
* @param {Set<string>} [opts.exclude]
|
|
64
|
+
*/
|
|
65
|
+
export async function loadPosts({ appDir, contentDir = "blog", exclude = new Set() } = {}) {
|
|
66
|
+
const root = join(appDir, contentDir);
|
|
67
|
+
if (!(await exists(root))) return [];
|
|
68
|
+
return collectPosts(root, "/" + contentDir, exclude, []);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
// Automatic post metadata describes concrete folders; generated parameters are
|
|
72
|
+
// unavailable during this scan and must not become card or feed URLs.
|
|
73
|
+
async function collectPosts(root, base, exclude, watch) {
|
|
74
|
+
const posts = [];
|
|
75
|
+
for (const entry of await readEntries(root)) {
|
|
76
|
+
if (
|
|
77
|
+
!entry.isDir ||
|
|
78
|
+
entry.name.startsWith(".") ||
|
|
79
|
+
entry.name.startsWith("_") ||
|
|
80
|
+
/\[[^\]]+\]/.test(entry.name) ||
|
|
81
|
+
exclude.has(entry.name)
|
|
82
|
+
) {
|
|
83
|
+
continue;
|
|
84
|
+
}
|
|
85
|
+
const dir = join(root, entry.name);
|
|
86
|
+
const page = (await readNames(dir)).find((n) => PAGE_RE.test(n));
|
|
87
|
+
if (!page) continue;
|
|
88
|
+
|
|
89
|
+
const file = join(dir, page);
|
|
90
|
+
watch.push(file);
|
|
91
|
+
const source = await readText(file);
|
|
92
|
+
const fm = await readFrontmatter(file);
|
|
93
|
+
posts.push(
|
|
94
|
+
clean({
|
|
95
|
+
slug: entry.name,
|
|
96
|
+
path: `${base}/${entry.name}`,
|
|
97
|
+
title: fm.title ?? humanize(entry.name),
|
|
98
|
+
description: fm.description,
|
|
99
|
+
date: fm.date != null ? String(fm.date) : undefined,
|
|
100
|
+
// Cover image (frontmatter `cover`) — shown on the post banner and the card.
|
|
101
|
+
cover: fm.cover,
|
|
102
|
+
author: fm.author,
|
|
103
|
+
authorAvatar: fm.author_avatar,
|
|
104
|
+
authorRole: fm.author_role,
|
|
105
|
+
// Frontmatter is flat scalars, so `tags: a, b` arrives as a string; normalize
|
|
106
|
+
// to a trimmed array. Components can render chips from it.
|
|
107
|
+
tags: typeof fm.tags === "string" ? splitTags(fm.tags) : undefined,
|
|
108
|
+
readingTime: readingTime(source),
|
|
109
|
+
order: typeof fm.order === "number" ? fm.order : undefined,
|
|
110
|
+
}),
|
|
111
|
+
);
|
|
112
|
+
}
|
|
113
|
+
return sortPosts(posts);
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/** Newest-first by `date`; a numeric `order` wins when present; title breaks ties. */
|
|
117
|
+
function sortPosts(posts) {
|
|
118
|
+
return posts.sort((a, b) => {
|
|
119
|
+
if (a.order != null || b.order != null) {
|
|
120
|
+
return (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER);
|
|
121
|
+
}
|
|
122
|
+
if (a.date && b.date && a.date !== b.date) return a.date < b.date ? 1 : -1;
|
|
123
|
+
if (a.date && !b.date) return -1;
|
|
124
|
+
if (!a.date && b.date) return 1;
|
|
125
|
+
return a.title.localeCompare(b.title);
|
|
126
|
+
});
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
function splitTags(s) {
|
|
130
|
+
const tags = s.split(",").map((t) => t.trim()).filter(Boolean);
|
|
131
|
+
return tags.length ? tags : undefined;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
function humanize(seg) {
|
|
135
|
+
return seg.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
function clean(node) {
|
|
139
|
+
for (const k of Object.keys(node)) if (node[k] === undefined) delete node[k];
|
|
140
|
+
return node;
|
|
141
|
+
}
|
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
// Build-time navigation generator (a bundler plugin).
|
|
2
|
+
//
|
|
3
|
+
// The sidebar / breadcrumbs / prev-next need the whole documentation tree, which
|
|
4
|
+
// only exists on disk at build time. This plugin scans `app/<dir>` for routes,
|
|
5
|
+
// reads each folder's `_meta.{js,json}` for ordering + labels and each page's
|
|
6
|
+
// frontmatter for titles, and resolves `@opentf/afw-docs/nav` to a generated module
|
|
7
|
+
// exporting the ordered tree. It is a pure build-time *consumer* of the file tree
|
|
8
|
+
// (ARCHITECTURE.md §6) — no new compiler stage, no runtime cost.
|
|
9
|
+
//
|
|
10
|
+
// Tree node shape: `{ title, path?, order?, items?: Node[] }`. A node with `path`
|
|
11
|
+
// is a link; a node with `items` is a (possibly also linked) group.
|
|
12
|
+
|
|
13
|
+
import { join, toFileURL } from "runtime:path";
|
|
14
|
+
|
|
15
|
+
import { exists, readEntries, readNames, readText } from "./host.js";
|
|
16
|
+
import { readFrontmatter } from "./frontmatter.js";
|
|
17
|
+
|
|
18
|
+
const VIRTUAL_ID = "@opentf/afw-docs/nav";
|
|
19
|
+
// No NUL sentinel: the bundler marks a module virtual explicitly, and a `\0` in
|
|
20
|
+
// a hook filter is an invalid regex — which silently matches *everything*.
|
|
21
|
+
const RESOLVED_ID = "afw-virtual:afw-docs-nav";
|
|
22
|
+
const PAGE_RE = /^page\.(mdx|md|[jt]sx)$/;
|
|
23
|
+
const MD_RE = /\.(mdx|md)$/;
|
|
24
|
+
|
|
25
|
+
// Folder scans know route patterns, not the parameter values a page generates.
|
|
26
|
+
// Omit the whole branch so descendants never inherit a placeholder URL.
|
|
27
|
+
function navDirectory(entry, exclude) {
|
|
28
|
+
return entry.isDir && !entry.name.startsWith(".") &&
|
|
29
|
+
!entry.name.startsWith("_") && !exclude.has(entry.name) &&
|
|
30
|
+
!/\[[^\]]+\]/.test(entry.name);
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Generates `@opentf/afw-docs/nav` as a **section map** — `{ "/<dir>": tree }`, one entry
|
|
35
|
+
* per top-level folder under `app/`. Each folder is a potential `DocsLayout` section; the
|
|
36
|
+
* layout selects its own subtree by the current route, so any number of sections (`/docs`,
|
|
37
|
+
* `/api`, …) "just work" with no config — drop a folder in and give it a `DocsLayout`.
|
|
38
|
+
*
|
|
39
|
+
* @param {Object} opts
|
|
40
|
+
* @param {string} opts.appDir Absolute path to the project's `app/` directory.
|
|
41
|
+
* @param {Set<string>} [opts.exclude] Folder names to skip (mirrors route exclusions).
|
|
42
|
+
* @param {(file: string) => Promise<any>} [opts.importModule] How to read a `_meta.js`.
|
|
43
|
+
* The dev server passes a loader that re-evaluates the file after an edit; a plain
|
|
44
|
+
* `import()` cannot, because the runtime caches ESM by path for the process's life.
|
|
45
|
+
*/
|
|
46
|
+
export function docsNavPlugin({ appDir, exclude = new Set(), importModule } = {}) {
|
|
47
|
+
return {
|
|
48
|
+
name: "afw-docs-nav",
|
|
49
|
+
resolve: {
|
|
50
|
+
filter: { id: VIRTUAL_ID },
|
|
51
|
+
handler: (source) => (source === VIRTUAL_ID ? { id: RESOLVED_ID, virtual: true } : null),
|
|
52
|
+
},
|
|
53
|
+
load: {
|
|
54
|
+
filter: { id: RESOLVED_ID },
|
|
55
|
+
async handler(id) {
|
|
56
|
+
if (id !== RESOLVED_ID) return null;
|
|
57
|
+
const ctx = { watch: [], importModule };
|
|
58
|
+
const out = {};
|
|
59
|
+
for (const entry of await readEntries(appDir)) {
|
|
60
|
+
if (!navDirectory(entry, exclude)) continue;
|
|
61
|
+
const base = "/" + entry.name;
|
|
62
|
+
out[base] = await buildSection(join(appDir, entry.name), base, ctx, true, exclude);
|
|
63
|
+
}
|
|
64
|
+
// The files this tree was generated from. They are not imports, so nothing else
|
|
65
|
+
// ties them to this module — declaring them is what makes the dev server rebuild the
|
|
66
|
+
// chunk holding the sidebar when a page's frontmatter or a `_meta.*` changes.
|
|
67
|
+
return { code: `export default ${JSON.stringify(out)};\n`, dependsOn: ctx.watch };
|
|
68
|
+
},
|
|
69
|
+
},
|
|
70
|
+
};
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** Load a folder's `_meta` (ordering + labels). Supports `.js`/`.mjs`/`.json`. */
|
|
74
|
+
async function loadMeta(dir, ctx) {
|
|
75
|
+
for (const name of ["_meta.js", "_meta.mjs", "_meta.json"]) {
|
|
76
|
+
const p = join(dir, name);
|
|
77
|
+
if (!(await exists(p))) continue;
|
|
78
|
+
ctx.watch.push(p);
|
|
79
|
+
try {
|
|
80
|
+
if (name.endsWith(".json")) return JSON.parse(await readText(p));
|
|
81
|
+
// A query string does not bust the ESM cache (it is keyed by path and ignores
|
|
82
|
+
// `?t=`), so a host that needs live `_meta` edits supplies a loader that can
|
|
83
|
+
// re-read the file; without one this is a plain, once-per-process import.
|
|
84
|
+
const mod = await (ctx.importModule?.(p) ?? import(toFileURL(p).href));
|
|
85
|
+
return mod.default ?? mod;
|
|
86
|
+
} catch (e) {
|
|
87
|
+
console.warn(`⚠ [@opentf/afw-docs] could not load ${p}: ${e?.message ?? e}`);
|
|
88
|
+
}
|
|
89
|
+
return null;
|
|
90
|
+
}
|
|
91
|
+
return null;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** The `page.*` file directly in `dir`, or null. */
|
|
95
|
+
async function pageFile(dir) {
|
|
96
|
+
for (const name of await readNames(dir)) {
|
|
97
|
+
if (PAGE_RE.test(name)) return join(dir, name);
|
|
98
|
+
}
|
|
99
|
+
return null;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
function humanize(seg) {
|
|
103
|
+
return seg.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** Order child keys: those named in `_meta` first (in declared order), rest A→Z. */
|
|
107
|
+
function orderKeys(keys, meta) {
|
|
108
|
+
if (!meta) return keys.slice().sort();
|
|
109
|
+
const metaKeys = Array.isArray(meta) ? meta : Object.keys(meta);
|
|
110
|
+
const named = metaKeys.filter((k) => keys.includes(k));
|
|
111
|
+
const rest = keys.filter((k) => !metaKeys.includes(k)).sort();
|
|
112
|
+
return [...named, ...rest];
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** A label declared in `_meta` for `key`, or null. */
|
|
116
|
+
function metaLabel(meta, key) {
|
|
117
|
+
if (!meta || Array.isArray(meta)) return null;
|
|
118
|
+
const v = meta[key];
|
|
119
|
+
if (typeof v === "string") return v;
|
|
120
|
+
if (v && typeof v === "object") return v.title ?? v.label ?? null;
|
|
121
|
+
return null;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Build the ordered items of a section directory. Each subdirectory becomes a child
|
|
126
|
+
* node (a link and/or a group). At the docs root (`withIndex`), the root's own
|
|
127
|
+
* `page.*` is emitted as a standalone "Overview"-style entry; in nested groups the
|
|
128
|
+
* folder's own page is the group node's link (added by `buildNode`), so it is not
|
|
129
|
+
* repeated here. Order + labels come from `_meta`.
|
|
130
|
+
*/
|
|
131
|
+
async function buildSection(dir, route, ctx, withIndex = false, exclude = new Set()) {
|
|
132
|
+
const meta = await loadMeta(dir, ctx);
|
|
133
|
+
const entries = await readEntries(dir);
|
|
134
|
+
const subdirs = entries
|
|
135
|
+
.filter((entry) => navDirectory(entry, exclude))
|
|
136
|
+
.map((e) => e.name);
|
|
137
|
+
|
|
138
|
+
const items = [];
|
|
139
|
+
|
|
140
|
+
// The docs root's own landing page (e.g. app/docs/page.mdx → /docs).
|
|
141
|
+
const indexFile = withIndex ? await pageFile(dir) : null;
|
|
142
|
+
const keys = subdirs.slice();
|
|
143
|
+
if (indexFile) keys.unshift("index");
|
|
144
|
+
|
|
145
|
+
let ordered = orderKeys(keys, meta);
|
|
146
|
+
// Default the landing page to the top unless `_meta` orders it.
|
|
147
|
+
const metaOrdersIndex = meta && !Array.isArray(meta) && "index" in meta;
|
|
148
|
+
if (indexFile && !metaOrdersIndex) {
|
|
149
|
+
ordered = ["index", ...ordered.filter((k) => k !== "index")];
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
for (const key of ordered) {
|
|
153
|
+
if (key === "index") {
|
|
154
|
+
ctx.watch.push(indexFile);
|
|
155
|
+
const fm = MD_RE.test(indexFile) ? await readFrontmatter(indexFile) : {};
|
|
156
|
+
items.push(
|
|
157
|
+
clean({
|
|
158
|
+
title: metaLabel(meta, "index") ?? fm.sidebar_label ?? fm.title ?? "Overview",
|
|
159
|
+
path: route || "/",
|
|
160
|
+
order: fm.order,
|
|
161
|
+
}),
|
|
162
|
+
);
|
|
163
|
+
continue;
|
|
164
|
+
}
|
|
165
|
+
const node = await buildNode(join(dir, key), `${route}/${key}`, key, meta, ctx, exclude);
|
|
166
|
+
if (node) items.push(node);
|
|
167
|
+
}
|
|
168
|
+
return items;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/** Build a single subdirectory node: its own link (if it has a page) + children. */
|
|
172
|
+
async function buildNode(dir, route, key, parentMeta, ctx, exclude) {
|
|
173
|
+
const pf = await pageFile(dir);
|
|
174
|
+
let fm = {};
|
|
175
|
+
if (pf) {
|
|
176
|
+
ctx.watch.push(pf);
|
|
177
|
+
if (MD_RE.test(pf)) fm = await readFrontmatter(pf);
|
|
178
|
+
}
|
|
179
|
+
const children = await buildSection(dir, route, ctx, false, exclude);
|
|
180
|
+
// A directory that has neither a page nor children contributes nothing.
|
|
181
|
+
if (!pf && children.length === 0) return null;
|
|
182
|
+
|
|
183
|
+
const title = metaLabel(parentMeta, key) ?? fm.sidebar_label ?? fm.title ?? humanize(key);
|
|
184
|
+
return clean({
|
|
185
|
+
title,
|
|
186
|
+
path: pf ? route : undefined,
|
|
187
|
+
order: fm.order,
|
|
188
|
+
items: children.length ? children : undefined,
|
|
189
|
+
});
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/** Drop undefined fields so the emitted JSON stays small. */
|
|
193
|
+
function clean(node) {
|
|
194
|
+
for (const k of Object.keys(node)) if (node[k] === undefined) delete node[k];
|
|
195
|
+
return node;
|
|
196
|
+
}
|
package/build/feed.js
ADDED
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
// RSS/Atom feed generation for the blog. Pure, build-time counterparts to the
|
|
2
|
+
// sitemap: given the post list (from `loadPosts`) plus the site origin and channel
|
|
3
|
+
// metadata, render feed XML strings. The afw-cli build writes them to
|
|
4
|
+
// `dist/<blogDir>/rss.xml` and `dist/<blogDir>/atom.xml` when a base URL is configured.
|
|
5
|
+
//
|
|
6
|
+
// RSS 2.0 (https://www.rssboard.org/rss-specification) is the lowest-common-
|
|
7
|
+
// denominator feed format: every reader supports it, and `<pubDate>` must be RFC-822.
|
|
8
|
+
|
|
9
|
+
/** XML text-escape (the five predefined entities). */
|
|
10
|
+
function esc(s) {
|
|
11
|
+
return String(s).replace(/[&<>'"]/g, (c) =>
|
|
12
|
+
c === "&" ? "&" : c === "<" ? "<" : c === ">" ? ">" : c === "'" ? "'" : """,
|
|
13
|
+
);
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** Absolute URL from a (trailing-slash-trimmed) origin + an absolute path. */
|
|
17
|
+
function abs(baseUrl, path) {
|
|
18
|
+
return baseUrl.replace(/\/+$/, "") + (path.startsWith("/") ? path : "/" + path);
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** `YYYY-MM-DD` (or any Date-parseable string) → RFC-822, e.g. for `<pubDate>`. */
|
|
22
|
+
function rfc822(date) {
|
|
23
|
+
if (!date) return null;
|
|
24
|
+
const d = new Date(date);
|
|
25
|
+
return Number.isNaN(d.getTime()) ? null : d.toUTCString();
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** `YYYY-MM-DD` (or any Date-parseable string) -> ISO-8601 for Atom timestamps. */
|
|
29
|
+
function iso8601(date) {
|
|
30
|
+
if (!date) return null;
|
|
31
|
+
const d = new Date(date);
|
|
32
|
+
return Number.isNaN(d.getTime()) ? null : d.toISOString();
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Newest valid publication instant, independent of post display order. */
|
|
36
|
+
function newestPostDate(posts) {
|
|
37
|
+
let newest = -Infinity;
|
|
38
|
+
for (const post of posts) {
|
|
39
|
+
if (!post.date) continue;
|
|
40
|
+
const timestamp = new Date(post.date).getTime();
|
|
41
|
+
if (!Number.isNaN(timestamp) && timestamp > newest) newest = timestamp;
|
|
42
|
+
}
|
|
43
|
+
return newest === -Infinity ? null : new Date(newest);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Render an RSS 2.0 feed.
|
|
48
|
+
*
|
|
49
|
+
* @param {Object} opts
|
|
50
|
+
* @param {Array} opts.posts Post list (from `loadPosts`).
|
|
51
|
+
* @param {string} opts.baseUrl Canonical site origin (required; absolute links).
|
|
52
|
+
* @param {string} [opts.feedPath] Path of the feed itself (for `<atom:link rel=self>`).
|
|
53
|
+
* @param {Object} [opts.channel] `{ title, description, link, language }`.
|
|
54
|
+
* @returns {string} The `rss.xml` document.
|
|
55
|
+
*/
|
|
56
|
+
export function renderBlogFeed({ posts = [], baseUrl, feedPath = "/blog/rss.xml", channel = {} } = {}) {
|
|
57
|
+
const title = channel.title || "Blog";
|
|
58
|
+
const description = channel.description || title;
|
|
59
|
+
const link = channel.link ? abs(baseUrl, channel.link) : abs(baseUrl, "/blog");
|
|
60
|
+
const language = channel.language || "en";
|
|
61
|
+
const self = abs(baseUrl, feedPath);
|
|
62
|
+
const lastBuild = rfc822(newestPostDate(posts)) || new Date().toUTCString();
|
|
63
|
+
|
|
64
|
+
const items = posts
|
|
65
|
+
.map((p) => {
|
|
66
|
+
const url = abs(baseUrl, p.path);
|
|
67
|
+
const pubDate = rfc822(p.date);
|
|
68
|
+
const parts = [
|
|
69
|
+
` <title>${esc(p.title)}</title>`,
|
|
70
|
+
` <link>${esc(url)}</link>`,
|
|
71
|
+
` <guid isPermaLink="true">${esc(url)}</guid>`,
|
|
72
|
+
];
|
|
73
|
+
if (pubDate) parts.push(` <pubDate>${pubDate}</pubDate>`);
|
|
74
|
+
if (p.author) parts.push(` <dc:creator>${esc(p.author)}</dc:creator>`);
|
|
75
|
+
if (p.description) parts.push(` <description>${esc(p.description)}</description>`);
|
|
76
|
+
for (const tag of p.tags || []) parts.push(` <category>${esc(tag)}</category>`);
|
|
77
|
+
return ` <item>\n${parts.join("\n")}\n </item>`;
|
|
78
|
+
})
|
|
79
|
+
.join("\n");
|
|
80
|
+
|
|
81
|
+
return (
|
|
82
|
+
`<?xml version="1.0" encoding="UTF-8"?>\n` +
|
|
83
|
+
`<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">\n` +
|
|
84
|
+
` <channel>\n` +
|
|
85
|
+
` <title>${esc(title)}</title>\n` +
|
|
86
|
+
` <link>${esc(link)}</link>\n` +
|
|
87
|
+
` <atom:link href="${esc(self)}" rel="self" type="application/rss+xml"/>\n` +
|
|
88
|
+
` <description>${esc(description)}</description>\n` +
|
|
89
|
+
` <language>${esc(language)}</language>\n` +
|
|
90
|
+
` <lastBuildDate>${lastBuild}</lastBuildDate>\n` +
|
|
91
|
+
` <generator>@opentf/afw-docs</generator>\n` +
|
|
92
|
+
(items ? items + "\n" : "") +
|
|
93
|
+
` </channel>\n` +
|
|
94
|
+
`</rss>\n`
|
|
95
|
+
);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Render an Atom 1.0 feed.
|
|
100
|
+
*
|
|
101
|
+
* @param {Object} opts
|
|
102
|
+
* @param {Array} opts.posts Post list (from `loadPosts`).
|
|
103
|
+
* @param {string} opts.baseUrl Canonical site origin (required; absolute links).
|
|
104
|
+
* @param {string} [opts.feedPath] Path of the feed itself (for `<link rel=self>`).
|
|
105
|
+
* @param {Object} [opts.channel] `{ title, description, link, author }`.
|
|
106
|
+
* @returns {string} The `atom.xml` document.
|
|
107
|
+
*/
|
|
108
|
+
export function renderAtomFeed({ posts = [], baseUrl, feedPath = "/blog/atom.xml", channel = {} } = {}) {
|
|
109
|
+
const title = channel.title || "Blog";
|
|
110
|
+
const description = channel.description || title;
|
|
111
|
+
const link = channel.link ? abs(baseUrl, channel.link) : abs(baseUrl, "/blog");
|
|
112
|
+
const self = abs(baseUrl, feedPath);
|
|
113
|
+
const updated = iso8601(newestPostDate(posts)) || new Date().toISOString();
|
|
114
|
+
const fallbackAuthor = channel.author || title;
|
|
115
|
+
|
|
116
|
+
const entries = posts
|
|
117
|
+
.map((p) => {
|
|
118
|
+
const url = abs(baseUrl, p.path);
|
|
119
|
+
const published = iso8601(p.date);
|
|
120
|
+
const parts = [
|
|
121
|
+
` <title>${esc(p.title)}</title>`,
|
|
122
|
+
` <link href="${esc(url)}"/>`,
|
|
123
|
+
` <id>${esc(url)}</id>`,
|
|
124
|
+
` <updated>${published || updated}</updated>`,
|
|
125
|
+
];
|
|
126
|
+
if (published) parts.push(` <published>${published}</published>`);
|
|
127
|
+
parts.push(` <author><name>${esc(p.author || fallbackAuthor)}</name></author>`);
|
|
128
|
+
if (p.description) parts.push(` <summary>${esc(p.description)}</summary>`);
|
|
129
|
+
for (const tag of p.tags || []) parts.push(` <category term="${esc(tag)}"/>`);
|
|
130
|
+
return ` <entry>\n${parts.join("\n")}\n </entry>`;
|
|
131
|
+
})
|
|
132
|
+
.join("\n");
|
|
133
|
+
|
|
134
|
+
return (
|
|
135
|
+
`<?xml version="1.0" encoding="UTF-8"?>\n` +
|
|
136
|
+
`<feed xmlns="http://www.w3.org/2005/Atom">\n` +
|
|
137
|
+
` <title>${esc(title)}</title>\n` +
|
|
138
|
+
` <subtitle>${esc(description)}</subtitle>\n` +
|
|
139
|
+
` <link href="${esc(link)}"/>\n` +
|
|
140
|
+
` <link href="${esc(self)}" rel="self" type="application/atom+xml"/>\n` +
|
|
141
|
+
` <id>${esc(link)}</id>\n` +
|
|
142
|
+
` <updated>${updated}</updated>\n` +
|
|
143
|
+
` <generator>@opentf/afw-docs</generator>\n` +
|
|
144
|
+
(entries ? entries + "\n" : "") +
|
|
145
|
+
`</feed>\n`
|
|
146
|
+
);
|
|
147
|
+
}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
// Minimal YAML frontmatter reader for the nav generator.
|
|
2
|
+
//
|
|
3
|
+
// Mirrors the flat-scalar parser in the Rust MDX front-end
|
|
4
|
+
// (crates/afw_compiler/src/mdx.rs `frontmatter_object`): a leading `---` block of
|
|
5
|
+
// `key: value` lines, scalars only. Unquoted booleans/numbers are coerced;
|
|
6
|
+
// everything else is a string. Nested maps / lists are out of scope (a follow-up, same as the Rust side).
|
|
7
|
+
|
|
8
|
+
import { readText } from "./host.js";
|
|
9
|
+
|
|
10
|
+
/** Parse the leading frontmatter block of an .mdx/.md file into a flat object. */
|
|
11
|
+
export async function readFrontmatter(file) {
|
|
12
|
+
let source;
|
|
13
|
+
try {
|
|
14
|
+
source = await readText(file);
|
|
15
|
+
} catch {
|
|
16
|
+
return {};
|
|
17
|
+
}
|
|
18
|
+
const m = source.match(/^?---\r?\n([\s\S]*?)\r?\n---/);
|
|
19
|
+
if (!m) return {};
|
|
20
|
+
const out = {};
|
|
21
|
+
for (const raw of m[1].split(/\r?\n/)) {
|
|
22
|
+
const line = raw.trim();
|
|
23
|
+
if (!line || line.startsWith("#")) continue;
|
|
24
|
+
const idx = line.indexOf(":");
|
|
25
|
+
if (idx < 0) continue;
|
|
26
|
+
const key = line.slice(0, idx).trim();
|
|
27
|
+
if (!key) continue;
|
|
28
|
+
const value = line.slice(idx + 1).trim();
|
|
29
|
+
// Strip a single matching pair of surrounding quotes.
|
|
30
|
+
if (
|
|
31
|
+
value.length >= 2 && (
|
|
32
|
+
(value.startsWith('"') && value.endsWith('"')) ||
|
|
33
|
+
(value.startsWith("'") && value.endsWith("'"))
|
|
34
|
+
)
|
|
35
|
+
) {
|
|
36
|
+
out[key] = value.slice(1, -1);
|
|
37
|
+
continue;
|
|
38
|
+
}
|
|
39
|
+
if (value === "true") out[key] = true;
|
|
40
|
+
else if (value === "false") out[key] = false;
|
|
41
|
+
else if (value !== "" && !Number.isNaN(Number(value))) out[key] = Number(value);
|
|
42
|
+
else out[key] = value;
|
|
43
|
+
}
|
|
44
|
+
return out;
|
|
45
|
+
}
|
package/build/host.js
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
// Host primitives for the docs build hooks.
|
|
2
|
+
//
|
|
3
|
+
// These run inside the toolchain, on the ES-Runtime, where the filesystem is async
|
|
4
|
+
// only — there are no synchronous variants to fall back on. A small local shim keeps
|
|
5
|
+
// the plugins readable and avoids a build-time dependency on `@opentf/afw-cli`, whose
|
|
6
|
+
// equivalent helpers are private to it.
|
|
7
|
+
|
|
8
|
+
import { exists as fsExists, file, readDir } from "runtime:fs";
|
|
9
|
+
import { Command } from "runtime:system";
|
|
10
|
+
|
|
11
|
+
/** Whether `path` exists — false rather than throwing when it is out of reach. */
|
|
12
|
+
export async function exists(path) {
|
|
13
|
+
try {
|
|
14
|
+
return await fsExists(path);
|
|
15
|
+
} catch {
|
|
16
|
+
return false;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
export const readText = (path) => file(path).text();
|
|
21
|
+
|
|
22
|
+
/** Directory entries, or `[]` when the directory is missing. */
|
|
23
|
+
export async function readEntries(dir) {
|
|
24
|
+
try {
|
|
25
|
+
return await readDir(dir);
|
|
26
|
+
} catch {
|
|
27
|
+
return [];
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** Entry names only — the `readdirSync(dir)` shape. */
|
|
32
|
+
export async function readNames(dir) {
|
|
33
|
+
return (await readEntries(dir)).map((e) => e.name);
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Run a command and return its trimmed stdout, or null if it failed. Git is the only
|
|
38
|
+
* caller, and a repo-less checkout must degrade to "no last-updated", never throw.
|
|
39
|
+
*/
|
|
40
|
+
export async function runOut(program, args, cwd) {
|
|
41
|
+
try {
|
|
42
|
+
const out = await new Command(program, {
|
|
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();
|
|
51
|
+
} catch {
|
|
52
|
+
return null;
|
|
53
|
+
}
|
|
54
|
+
}
|
package/build/index.js
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
// Build-time entry for the docs toolchain integration.
|
|
2
|
+
//
|
|
3
|
+
// Re-exports the nav plugin (registered by @opentf/afw-cli when a project
|
|
4
|
+
// has a `docs` config) and the AFW Search indexing function. Importing this
|
|
5
|
+
// from afw-cli keeps all docs-specific build logic owned by this package.
|
|
6
|
+
|
|
7
|
+
export { docsNavPlugin } from "./docs-nav-plugin.js";
|
|
8
|
+
export { blogPostsPlugin, loadPosts } from "./blog-posts-plugin.js";
|
|
9
|
+
export { lastUpdatedPlugin, loadLastUpdated } from "./last-updated-plugin.js";
|
|
10
|
+
export { renderAtomFeed, renderBlogFeed } from "./feed.js";
|
|
11
|
+
export { renderLlmsFullTxt, renderLlmsTxt } from "./llms.js";
|
|
12
|
+
export { indexWithAfwSearch } from "./search.js";
|