@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,99 @@
|
|
|
1
|
+
// Build-time "last updated" map generator (a bundler plugin), sibling of the nav and
|
|
2
|
+
// blog-posts plugins. It walks every page under `app/`, resolves each one's last-updated
|
|
3
|
+
// time (git commit or frontmatter override — see last-updated.js), and resolves the
|
|
4
|
+
// virtual module `@opentf/afw-docs/updated` to a `{ [routePath]: ISO }` map. Layouts look
|
|
5
|
+
// the current route up in that map to render a "Last updated" line — so every section
|
|
6
|
+
// gets it from one switch, no per-section config.
|
|
7
|
+
//
|
|
8
|
+
// The same map is needed by the SSG step for the `article:modified_time` SEO tag, so
|
|
9
|
+
// the scan is exposed as a callable (`loadLastUpdated`) too.
|
|
10
|
+
|
|
11
|
+
import { join, relative, resolve } from "runtime:path";
|
|
12
|
+
import { cwd } from "runtime:process";
|
|
13
|
+
|
|
14
|
+
import { readEntries, runOut } from "./host.js";
|
|
15
|
+
import { readFrontmatter } from "./frontmatter.js";
|
|
16
|
+
import { resolveLastUpdated } from "./last-updated.js";
|
|
17
|
+
|
|
18
|
+
const VIRTUAL_ID = "@opentf/afw-docs/updated";
|
|
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-last-updated";
|
|
22
|
+
const PAGE_RE = /^page\.(mdx|md|[jt]sx)$/;
|
|
23
|
+
const MD_RE = /\.(mdx|md)$/;
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* @param {Object} opts
|
|
27
|
+
* @param {string} opts.appDir
|
|
28
|
+
* @param {Set<string>} [opts.exclude] Folder names to skip (mirrors route exclusions).
|
|
29
|
+
*/
|
|
30
|
+
export function lastUpdatedPlugin({ appDir, exclude = new Set() } = {}) {
|
|
31
|
+
return {
|
|
32
|
+
name: "afw-last-updated",
|
|
33
|
+
resolve: {
|
|
34
|
+
filter: { id: VIRTUAL_ID },
|
|
35
|
+
handler: (source) => (source === VIRTUAL_ID ? { id: RESOLVED_ID, virtual: true } : null),
|
|
36
|
+
},
|
|
37
|
+
load: {
|
|
38
|
+
filter: { id: RESOLVED_ID },
|
|
39
|
+
async handler(id) {
|
|
40
|
+
if (id !== RESOLVED_ID) return null;
|
|
41
|
+
const watch = [];
|
|
42
|
+
const { updated, editPaths } = await collect(appDir, exclude, watch);
|
|
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
|
+
};
|
|
51
|
+
},
|
|
52
|
+
},
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* The `{ [routePath]: ISO }` last-updated map, callable directly (used by the SSG SEO
|
|
58
|
+
* step). Mirrors what the virtual module exposes.
|
|
59
|
+
*/
|
|
60
|
+
export async function loadLastUpdated({ appDir, exclude = new Set() } = {}) {
|
|
61
|
+
return (await collect(appDir, exclude, [])).updated;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Git repo root containing `dir`, or null (so edit links degrade gracefully). */
|
|
65
|
+
const gitRoot = (dir) => runOut("git", ["rev-parse", "--show-toplevel"], dir);
|
|
66
|
+
|
|
67
|
+
async function collect(appDir, exclude, watch) {
|
|
68
|
+
// Plugin options are plain config data, so a relative `appDir` ("app") is relative
|
|
69
|
+
// to the project directory plugins run in. Resolve it here: git runs from each
|
|
70
|
+
// page's own folder, where a relative page path would point somewhere else.
|
|
71
|
+
appDir = resolve(cwd(), appDir);
|
|
72
|
+
const updated = {};
|
|
73
|
+
const editPaths = {};
|
|
74
|
+
const root0 = await gitRoot(appDir);
|
|
75
|
+
// One walk over every page under app/ — covers all sections (and the home page).
|
|
76
|
+
await walk(appDir, "", exclude, async (file, route) => {
|
|
77
|
+
watch.push(file);
|
|
78
|
+
const fm = MD_RE.test(file) ? await readFrontmatter(file) : {};
|
|
79
|
+
const iso = await resolveLastUpdated(file, fm.lastUpdated);
|
|
80
|
+
if (iso) updated[route] = iso;
|
|
81
|
+
// Repo-relative path (POSIX separators) for the "Edit this page" link.
|
|
82
|
+
if (root0) editPaths[route] = relative(root0, file).split(/[\\/]/).join("/");
|
|
83
|
+
});
|
|
84
|
+
return { updated, editPaths };
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** Recursively find every `page.*` under `root`, mapping it to its route path. */
|
|
88
|
+
async function walk(dir, route, exclude, onPage) {
|
|
89
|
+
for (const entry of await readEntries(dir)) {
|
|
90
|
+
if (entry.isDir) {
|
|
91
|
+
if (entry.name.startsWith(".") || entry.name.startsWith("_") || exclude.has(entry.name)) {
|
|
92
|
+
continue;
|
|
93
|
+
}
|
|
94
|
+
await walk(join(dir, entry.name), `${route}/${entry.name}`, exclude, onPage);
|
|
95
|
+
} else if (PAGE_RE.test(entry.name)) {
|
|
96
|
+
await onPage(join(dir, entry.name), route || "/");
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
// "Last updated" resolution for a page file. Two sources only (build time):
|
|
2
|
+
//
|
|
3
|
+
// 1. A frontmatter override — `lastUpdated: 2026-06-25` (any Date-parseable value)
|
|
4
|
+
// pins the date; `lastUpdated: false` hides it for that page.
|
|
5
|
+
// 2. The file's last git commit (committer date, `git log -1 --format=%cI`).
|
|
6
|
+
//
|
|
7
|
+
// No file-mtime fallback: mtime is noise (a checkout/copy bumps it), so when the file
|
|
8
|
+
// isn't in git history the value is simply null and the UI omits it. This runs in dev
|
|
9
|
+
// and build alike — the displayed time is always the real last content change.
|
|
10
|
+
|
|
11
|
+
import { dirname } from "runtime:path";
|
|
12
|
+
|
|
13
|
+
import { runOut } from "./host.js";
|
|
14
|
+
|
|
15
|
+
/** Last git commit (committer ISO-8601) that touched `file`, or null. */
|
|
16
|
+
export async function gitLastUpdated(file) {
|
|
17
|
+
// Empty output = untracked / no history (e.g. a shallow CI clone); null = not a
|
|
18
|
+
// git repo, or git unavailable. Both mean "omit", so both collapse to null.
|
|
19
|
+
const out = await runOut("git", ["log", "-1", "--format=%cI", "--", file], dirname(file));
|
|
20
|
+
return out || null;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** Normalize a frontmatter override to ISO-8601, or keep the raw string if unparseable. */
|
|
24
|
+
function normalize(value) {
|
|
25
|
+
const d = new Date(value);
|
|
26
|
+
return Number.isNaN(d.getTime()) ? String(value) : d.toISOString();
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* Resolve a page's last-updated timestamp.
|
|
31
|
+
*
|
|
32
|
+
* @param {string} file Absolute path to the page file.
|
|
33
|
+
* @param {*} [frontmatter] The frontmatter `lastUpdated` value, if any.
|
|
34
|
+
* @returns {string|null} ISO-8601 (or a raw override string), or null to omit.
|
|
35
|
+
*/
|
|
36
|
+
export async function resolveLastUpdated(file, frontmatter) {
|
|
37
|
+
if (frontmatter === false) return null; // explicit opt-out for this page
|
|
38
|
+
if (frontmatter != null && frontmatter !== true) return normalize(frontmatter);
|
|
39
|
+
return gitLastUpdated(file);
|
|
40
|
+
}
|
package/build/llms.js
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
import { dirname, relative, sep } from "runtime:path";
|
|
2
|
+
|
|
3
|
+
import { exists, readText } from "./host.js";
|
|
4
|
+
|
|
5
|
+
import { readFrontmatter } from "./frontmatter.js";
|
|
6
|
+
|
|
7
|
+
const PAGE_RE = /(^|[\\/])page\.(mdx|md|[jt]sx)$/;
|
|
8
|
+
const MD_RE = /\.(mdx|md)$/;
|
|
9
|
+
|
|
10
|
+
function abs(baseUrl, path) {
|
|
11
|
+
return baseUrl.replace(/\/+$/, "") + (path === "/" ? "/" : path);
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
function routePath(appDir, file) {
|
|
15
|
+
const rel = relative(appDir, file).split(sep).join("/");
|
|
16
|
+
if (!PAGE_RE.test(rel)) return null;
|
|
17
|
+
const dir = dirname(rel).split(sep).join("/");
|
|
18
|
+
if (dir === ".") return "/";
|
|
19
|
+
const segments = dir.split("/");
|
|
20
|
+
if (segments.some((seg) => seg.startsWith("_") || seg.startsWith(".") || seg.includes("["))) {
|
|
21
|
+
return null;
|
|
22
|
+
}
|
|
23
|
+
return "/" + segments.join("/");
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
function humanize(seg) {
|
|
27
|
+
return seg.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
async function titleFor(file, path) {
|
|
31
|
+
const fm = MD_RE.test(file) ? await readFrontmatter(file) : {};
|
|
32
|
+
if (fm.title) return String(fm.title);
|
|
33
|
+
if (path === "/") return "Home";
|
|
34
|
+
return humanize(path.split("/").filter(Boolean).at(-1) ?? "Home");
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
async function descriptionFor(file) {
|
|
38
|
+
const fm = MD_RE.test(file) ? await readFrontmatter(file) : {};
|
|
39
|
+
return fm.description ? String(fm.description) : "";
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
function stripFrontmatter(source) {
|
|
43
|
+
return source.replace(/^?---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function stripMdxBoilerplate(source) {
|
|
47
|
+
const lines = stripFrontmatter(source).split(/\r?\n/);
|
|
48
|
+
const out = [];
|
|
49
|
+
let inFence = false;
|
|
50
|
+
for (const line of lines) {
|
|
51
|
+
if (/^```/.test(line.trim())) inFence = !inFence;
|
|
52
|
+
if (!inFence && /^\s*import\s/.test(line)) continue;
|
|
53
|
+
if (!inFence && /^\s*export\s+(const|let|var|default)\s/.test(line)) continue;
|
|
54
|
+
out.push(line);
|
|
55
|
+
}
|
|
56
|
+
return out.join("\n").trim();
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function sectionFor(path) {
|
|
60
|
+
if (path === "/") return "Start Here";
|
|
61
|
+
if (path.startsWith("/docs")) return "Documentation";
|
|
62
|
+
if (path.startsWith("/api")) return "API Reference";
|
|
63
|
+
if (path.startsWith("/blog")) return "Blog";
|
|
64
|
+
return "Other Routes";
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
async function pageRecords({ appDir, pages = [], baseUrl }) {
|
|
68
|
+
const records = await Promise.all(
|
|
69
|
+
pages
|
|
70
|
+
.filter((file) => PAGE_RE.test(file))
|
|
71
|
+
.map(async (file) => {
|
|
72
|
+
const path = routePath(appDir, file);
|
|
73
|
+
if (!path) return null;
|
|
74
|
+
return {
|
|
75
|
+
file,
|
|
76
|
+
path,
|
|
77
|
+
url: abs(baseUrl, path),
|
|
78
|
+
title: await titleFor(file, path),
|
|
79
|
+
description: await descriptionFor(file),
|
|
80
|
+
markdown:
|
|
81
|
+
MD_RE.test(file) && (await exists(file)) ? stripMdxBoilerplate(await readText(file)) : "",
|
|
82
|
+
};
|
|
83
|
+
}),
|
|
84
|
+
);
|
|
85
|
+
return records
|
|
86
|
+
.filter(Boolean)
|
|
87
|
+
.sort((a, b) => {
|
|
88
|
+
if (a.path === "/") return -1;
|
|
89
|
+
if (b.path === "/") return 1;
|
|
90
|
+
return a.path.localeCompare(b.path);
|
|
91
|
+
});
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
function grouped(records) {
|
|
95
|
+
const out = new Map();
|
|
96
|
+
for (const record of records) {
|
|
97
|
+
const section = sectionFor(record.path);
|
|
98
|
+
if (!out.has(section)) out.set(section, []);
|
|
99
|
+
out.get(section).push(record);
|
|
100
|
+
}
|
|
101
|
+
return out;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* The site's own one-line description for the `> …` summary line — never a
|
|
106
|
+
* framework-authored blurb. In order: an explicit `docs.description`, the site-wide
|
|
107
|
+
* description resolved from the app's metadata (root layout / home route), the home
|
|
108
|
+
* page's own frontmatter description, the blog feed description, and finally a plain
|
|
109
|
+
* sentence built from the site title.
|
|
110
|
+
*/
|
|
111
|
+
function siteDescriptionFor({ config, siteDescription, records, title }) {
|
|
112
|
+
return (
|
|
113
|
+
config?.docs?.description ||
|
|
114
|
+
siteDescription ||
|
|
115
|
+
records.find((record) => record.path === "/")?.description ||
|
|
116
|
+
config?.blog?.description ||
|
|
117
|
+
`Documentation for ${title}.`
|
|
118
|
+
);
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
const SECTION_ORDER = ["Start Here", "Documentation", "API Reference", "Blog", "Other Routes"];
|
|
122
|
+
|
|
123
|
+
export async function renderLlmsTxt({ appDir, pages = [], baseUrl, config = {}, siteDescription = "" } = {}) {
|
|
124
|
+
const title = config?.docs?.title || "AFW";
|
|
125
|
+
const records = await pageRecords({ appDir, pages, baseUrl });
|
|
126
|
+
const description = siteDescriptionFor({ config, siteDescription, records, title });
|
|
127
|
+
const lines = [
|
|
128
|
+
`# ${title}`,
|
|
129
|
+
"",
|
|
130
|
+
`> ${description}`,
|
|
131
|
+
"",
|
|
132
|
+
`This file is a curated entry point for language models. For full page content, see [llms-full.txt](${abs(baseUrl, "/llms-full.txt")}).`,
|
|
133
|
+
"",
|
|
134
|
+
];
|
|
135
|
+
|
|
136
|
+
const groups = grouped(records);
|
|
137
|
+
for (const section of SECTION_ORDER) {
|
|
138
|
+
const items = groups.get(section);
|
|
139
|
+
if (!items?.length) continue;
|
|
140
|
+
lines.push(`## ${section}`, "");
|
|
141
|
+
for (const item of items) {
|
|
142
|
+
const note = item.description ? `: ${item.description}` : "";
|
|
143
|
+
lines.push(`- [${item.title}](${item.url})${note}`);
|
|
144
|
+
}
|
|
145
|
+
lines.push("");
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
if (config?.blog) {
|
|
149
|
+
lines.push("## Optional", "");
|
|
150
|
+
lines.push(`- [RSS feed](${abs(baseUrl, `/${config.blog.dir ?? "blog"}/rss.xml`)}): Blog feed in RSS 2.0 format.`);
|
|
151
|
+
lines.push(`- [Atom feed](${abs(baseUrl, `/${config.blog.dir ?? "blog"}/atom.xml`)}): Blog feed in Atom 1.0 format.`);
|
|
152
|
+
}
|
|
153
|
+
return lines.join("\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
export async function renderLlmsFullTxt({ appDir, pages = [], baseUrl, config = {} } = {}) {
|
|
157
|
+
const title = config?.docs?.title || "AFW";
|
|
158
|
+
const records = (await pageRecords({ appDir, pages, baseUrl })).filter((record) => record.markdown);
|
|
159
|
+
const lines = [
|
|
160
|
+
`# ${title} Full Documentation`,
|
|
161
|
+
"",
|
|
162
|
+
`Generated from filesystem routes for ${baseUrl.replace(/\/+$/, "")}.`,
|
|
163
|
+
"",
|
|
164
|
+
];
|
|
165
|
+
|
|
166
|
+
for (const record of records) {
|
|
167
|
+
lines.push(`## ${record.title}`, "");
|
|
168
|
+
lines.push(`URL: ${record.url}`);
|
|
169
|
+
if (record.description) lines.push(`Description: ${record.description}`);
|
|
170
|
+
lines.push("");
|
|
171
|
+
lines.push(record.markdown);
|
|
172
|
+
lines.push("");
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
return lines.join("\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
|
|
176
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
// Estimate a post's reading time (minutes) from its Markdown source. Strips
|
|
2
|
+
// frontmatter, code, HTML/JSX tags, and Markdown punctuation before counting words,
|
|
3
|
+
// then divides by `wpm` (200 words/min ≈ average adult prose reading). Build-time
|
|
4
|
+
// only — the result ships as data on each post (see blog-posts-plugin.js).
|
|
5
|
+
export function readingTime(source, wpm = 200) {
|
|
6
|
+
const body = String(source || "")
|
|
7
|
+
.replace(/^?---\r?\n[\s\S]*?\r?\n---/, "") // frontmatter
|
|
8
|
+
.replace(/```[\s\S]*?```/g, " ") // fenced code
|
|
9
|
+
.replace(/`[^`]*`/g, " ") // inline code
|
|
10
|
+
.replace(/<[^>]+>/g, " ") // html / jsx tags
|
|
11
|
+
.replace(/!\[[^\]]*\]\([^)]*\)/g, " ") // images
|
|
12
|
+
.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // links → their text
|
|
13
|
+
.replace(/[#>*_~`\-]+/g, " "); // residual md punctuation
|
|
14
|
+
const words = body.split(/\s+/).filter(Boolean).length;
|
|
15
|
+
return Math.max(1, Math.round(words / wpm));
|
|
16
|
+
}
|
package/build/search.js
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
// Build-time AFW Search indexing; called after prerendering by the finish plugin.
|
|
2
|
+
|
|
3
|
+
import { join } from "runtime:path";
|
|
4
|
+
import { Command } from "runtime:system";
|
|
5
|
+
import { afwcPath } from "@opentf/afw-compiler";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Build the index from prerendered HTML using the unified native toolchain.
|
|
9
|
+
* Published toolchains ship one afwc binary; source checkouts build it
|
|
10
|
+
* from `cargo build -p afw_cli`.
|
|
11
|
+
*/
|
|
12
|
+
export async function indexWithAfwSearch({ siteDir, afwc }) {
|
|
13
|
+
const binary = afwc || await afwcPath();
|
|
14
|
+
const out = new Command(binary, {
|
|
15
|
+
args: ["docs", "index", siteDir, "--out", join(siteDir, "_search"), "--root", "main"],
|
|
16
|
+
stdout: "piped",
|
|
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);
|
|
23
|
+
const indexed = /indexed\s+(\d+)\s+page/.exec(message);
|
|
24
|
+
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
|
+
const pages = Number(indexed[1]);
|
|
26
|
+
return { pages };
|
|
27
|
+
}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
// Blog section layout. Wraps both the index (`/blog`) and individual posts
|
|
2
|
+
// (`/blog/<slug>`). It identifies the current page by matching `router.pathname`
|
|
3
|
+
// against the post list (from `@opentf/afw-docs/posts`):
|
|
4
|
+
//
|
|
5
|
+
// import BlogLayout from "@opentf/afw-docs"; // BlogLayout
|
|
6
|
+
// import { posts } from "@opentf/afw-docs/posts";
|
|
7
|
+
// import config from "../../afw.config.js";
|
|
8
|
+
// export default function (props) {
|
|
9
|
+
// return <BlogLayout config={config.docs} posts={posts} frame={false}>{props.children}</BlogLayout>;
|
|
10
|
+
// }
|
|
11
|
+
//
|
|
12
|
+
// On a post it renders the PostBanner (from the post's frontmatter) above the prose
|
|
13
|
+
// body, plus a reusable "On this page" TOC; on the index it just renders the children
|
|
14
|
+
// (typically a <PostList/>). `frame` (default true) adds the navbar/footer chrome;
|
|
15
|
+
// pass `frame={false}` when nesting inside a site layout that already provides them.
|
|
16
|
+
//
|
|
17
|
+
// The layout factory re-runs on every navigation (the router rebuilds the route +
|
|
18
|
+
// layout chain), so reading `router.pathname` resolves to the page being shown.
|
|
19
|
+
import { Link, RawHtml, router } from "@opentf/afw";
|
|
20
|
+
import updated from "@opentf/afw-docs/updated";
|
|
21
|
+
|
|
22
|
+
import Navbar from "./Navbar.jsx";
|
|
23
|
+
import Footer from "./Footer.jsx";
|
|
24
|
+
import Toc from "./Toc.jsx";
|
|
25
|
+
import PostBanner from "./PostBanner.jsx";
|
|
26
|
+
import LastUpdated from "./LastUpdated.jsx";
|
|
27
|
+
import { editedAfterPublish } from "./post-dates.js";
|
|
28
|
+
|
|
29
|
+
// Structured data for crawlers: the current post as a BlogPosting, emitted in
|
|
30
|
+
// 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
|
+
function blogPostingJsonLd(post, siteUrl, dateModified) {
|
|
33
|
+
const base = (siteUrl || "").replace(/\/+$/, "");
|
|
34
|
+
const abs = (p) => (p ? base + p : undefined);
|
|
35
|
+
const article = { "@context": "https://schema.org", "@type": "BlogPosting" };
|
|
36
|
+
if (post.title) article.headline = post.title;
|
|
37
|
+
if (post.description) article.description = post.description;
|
|
38
|
+
if (post.path) article.url = abs(post.path) || post.path;
|
|
39
|
+
if (post.cover) article.image = abs(post.cover) || post.cover;
|
|
40
|
+
if (post.date) article.datePublished = post.date;
|
|
41
|
+
if (dateModified) article.dateModified = dateModified;
|
|
42
|
+
if (post.author) article.author = { "@type": "Person", name: post.author };
|
|
43
|
+
const json = JSON.stringify(article).replace(/</g, "\\u003c");
|
|
44
|
+
return `<script type="application/ld+json">${json}</script>`;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export default function BlogLayout(props) {
|
|
48
|
+
const config = props.config || {};
|
|
49
|
+
const posts = props.posts || [];
|
|
50
|
+
const frame = props.frame !== false;
|
|
51
|
+
const indexPath = props.indexPath || "/blog";
|
|
52
|
+
const siteUrl = props.siteUrl || "";
|
|
53
|
+
|
|
54
|
+
const post = posts.find((p) => p.path === router.pathname);
|
|
55
|
+
const editedIso = post && editedAfterPublish(updated[post.path], post.date) ? updated[post.path] : null;
|
|
56
|
+
|
|
57
|
+
const body = post ? (
|
|
58
|
+
<div class="afwd-blog afwd-blog-post">
|
|
59
|
+
{/* `afw-content` so the shared Toc can read this article's headings. */}
|
|
60
|
+
<main id="afw-content" class="afwd-blog-main" data-afw-search-body>
|
|
61
|
+
{/* Give blog posts a search breadcrumb too (docs get theirs from <Breadcrumbs>),
|
|
62
|
+
so a result looks the same whether it's a doc or a post. Inline `key:value`
|
|
63
|
+
syntax sets the meta literally, independent of visible text. */}
|
|
64
|
+
<span data-afw-search-meta="breadcrumb:Blog" hidden></span>
|
|
65
|
+
<Link href={indexPath} class="afwd-blog-back" data-afw-search-ignore>
|
|
66
|
+
← {config.title ? `${config.title} Blog` : "Blog"}
|
|
67
|
+
</Link>
|
|
68
|
+
<PostBanner post={post} />
|
|
69
|
+
<RawHtml html={blogPostingJsonLd(post, siteUrl, editedIso || post.date)} />
|
|
70
|
+
<article class="afwd-prose">{props.children}</article>
|
|
71
|
+
{editedIso ? <LastUpdated date={editedIso} /> : null}
|
|
72
|
+
</main>
|
|
73
|
+
<Toc />
|
|
74
|
+
</div>
|
|
75
|
+
) : (
|
|
76
|
+
<div class="afwd-blog afwd-blog-index">
|
|
77
|
+
<main class="afwd-blog-main">{props.children}</main>
|
|
78
|
+
</div>
|
|
79
|
+
);
|
|
80
|
+
|
|
81
|
+
return frame ? (
|
|
82
|
+
<div class="afwd-shell">
|
|
83
|
+
<Navbar config={config} />
|
|
84
|
+
<div class="afwd-shell-body">{body}</div>
|
|
85
|
+
<Footer config={config} />
|
|
86
|
+
</div>
|
|
87
|
+
) : (
|
|
88
|
+
body
|
|
89
|
+
);
|
|
90
|
+
}
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
// Breadcrumb trail for the current page, derived from the nav tree + router path.
|
|
2
|
+
|
|
3
|
+
import { Link, RawHtml, router } from "@opentf/afw";
|
|
4
|
+
|
|
5
|
+
// Structured data for crawlers: the visible trail above as a BreadcrumbList.
|
|
6
|
+
// Emitted beside the nav (JSON-LD is discovered wherever it sits). `siteUrl`
|
|
7
|
+
// (optional site origin) absolutizes the item URLs; without it they stay
|
|
8
|
+
// route-relative. `<` is escaped so the payload can't break out of the script.
|
|
9
|
+
function breadcrumbJsonLd(trail, siteUrl) {
|
|
10
|
+
if (!trail.length) return "";
|
|
11
|
+
const base = (siteUrl || "").replace(/\/+$/, "");
|
|
12
|
+
const items = trail.map((it, i) => {
|
|
13
|
+
const entry = {
|
|
14
|
+
"@type": "ListItem",
|
|
15
|
+
position: i + 1,
|
|
16
|
+
name: it.title,
|
|
17
|
+
};
|
|
18
|
+
if (it.path) entry.item = base + it.path;
|
|
19
|
+
return entry;
|
|
20
|
+
});
|
|
21
|
+
const json = JSON.stringify({
|
|
22
|
+
"@context": "https://schema.org",
|
|
23
|
+
"@type": "BreadcrumbList",
|
|
24
|
+
itemListElement: items,
|
|
25
|
+
}).replace(/</g, "\\u003c");
|
|
26
|
+
return `<script type="application/ld+json">${json}</script>`;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export default function Breadcrumbs(props) {
|
|
30
|
+
const nav = props.nav || [];
|
|
31
|
+
const siteUrl = props.siteUrl || "";
|
|
32
|
+
|
|
33
|
+
const findTrail = (items, path, trail) => {
|
|
34
|
+
for (const it of items) {
|
|
35
|
+
const next = trail.concat(it);
|
|
36
|
+
if (it.path === path) return next;
|
|
37
|
+
if (it.items) {
|
|
38
|
+
const found = findTrail(it.items, path, next);
|
|
39
|
+
if (found) return found;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
return null;
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
// Direct-child `.map` (not wrapped in a `{() => …}` thunk) so the compiler
|
|
46
|
+
// lowers it to a reactive list whose item renderer receives `it`/`i`. The
|
|
47
|
+
// source re-runs on `router.pathname`, so the trail tracks navigation.
|
|
48
|
+
// `data-afw-search-meta="breadcrumb"` exposes this trail to the search index, so each
|
|
49
|
+
// result can show which page (and section) it belongs to.
|
|
50
|
+
// The JSON-LD trail below re-reads the same source (a second subscription, kept
|
|
51
|
+
// out of the list so the lowering above is untouched).
|
|
52
|
+
return (
|
|
53
|
+
<nav class="afwd-breadcrumbs" aria-label="Breadcrumb" data-afw-search-meta="breadcrumb">
|
|
54
|
+
<RawHtml
|
|
55
|
+
html={breadcrumbJsonLd(findTrail(nav, router.pathname, []) || [], siteUrl)}
|
|
56
|
+
/>
|
|
57
|
+
{(findTrail(nav, router.pathname, []) || []).map((it, i) => (
|
|
58
|
+
<span class="afwd-crumb">
|
|
59
|
+
{i > 0 ? <span class="afwd-crumb-sep">/</span> : null}
|
|
60
|
+
{it.path ? (
|
|
61
|
+
<Link href={it.path} class="afwd-crumb-link">
|
|
62
|
+
{it.title}
|
|
63
|
+
</Link>
|
|
64
|
+
) : (
|
|
65
|
+
<span class="afwd-crumb-text">{it.title}</span>
|
|
66
|
+
)}
|
|
67
|
+
</span>
|
|
68
|
+
))}
|
|
69
|
+
</nav>
|
|
70
|
+
);
|
|
71
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
// Admonition / callout box. `type` is note | tip | info | warning | danger.
|
|
2
|
+
//
|
|
3
|
+
// <Callout type="warning" title="Heads up">…</Callout>
|
|
4
|
+
|
|
5
|
+
const ICONS = {
|
|
6
|
+
note: "✎",
|
|
7
|
+
tip: "💡",
|
|
8
|
+
info: "🛈",
|
|
9
|
+
warning: "⚠",
|
|
10
|
+
danger: "⛔",
|
|
11
|
+
};
|
|
12
|
+
|
|
13
|
+
export default function Callout(props) {
|
|
14
|
+
const type = props.type || "note";
|
|
15
|
+
const title = props.title || type.charAt(0).toUpperCase() + type.slice(1);
|
|
16
|
+
const icon = ICONS[type] || ICONS.note;
|
|
17
|
+
|
|
18
|
+
return (
|
|
19
|
+
<div class={"afwd-callout afwd-callout-" + type}>
|
|
20
|
+
<span class="afwd-callout-icon" aria-hidden="true">
|
|
21
|
+
{icon}
|
|
22
|
+
</span>
|
|
23
|
+
<div class="afwd-callout-content">
|
|
24
|
+
<div class="afwd-callout-title">{title}</div>
|
|
25
|
+
<div class="afwd-callout-body">{props.children}</div>
|
|
26
|
+
</div>
|
|
27
|
+
</div>
|
|
28
|
+
);
|
|
29
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
// A single tile in a <Cards> grid: a title, an optional description, and a link. An
|
|
2
|
+
// internal `href` uses SPA navigation (<Link>); an `external` href is a plain anchor.
|
|
3
|
+
// `desc` (prop) or children supply the body.
|
|
4
|
+
|
|
5
|
+
import { Link } from "@opentf/afw";
|
|
6
|
+
|
|
7
|
+
export default function Card(props) {
|
|
8
|
+
return props.external ? (
|
|
9
|
+
<a href={props.href} target="_blank" rel="noreferrer" class="afwd-card">
|
|
10
|
+
<span class="afwd-card-title">{props.title}</span>
|
|
11
|
+
{props.desc ? <span class="afwd-card-desc">{props.desc}</span> : null}
|
|
12
|
+
{props.children}
|
|
13
|
+
</a>
|
|
14
|
+
) : (
|
|
15
|
+
<Link href={props.href} class="afwd-card">
|
|
16
|
+
<span class="afwd-card-title">{props.title}</span>
|
|
17
|
+
{props.desc ? <span class="afwd-card-desc">{props.desc}</span> : null}
|
|
18
|
+
{props.children}
|
|
19
|
+
</Link>
|
|
20
|
+
);
|
|
21
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
// A responsive grid of <Card>s. Used on index/landing docs pages (e.g. the API
|
|
2
|
+
// reference overview) to present a set of links as tiles instead of a bullet list.
|
|
3
|
+
//
|
|
4
|
+
// import { Cards, Card } from "@opentf/afw-docs";
|
|
5
|
+
// <Cards>
|
|
6
|
+
// <Card title="Core" href="/docs/api/core" desc="Runtime API." />
|
|
7
|
+
// </Cards>
|
|
8
|
+
|
|
9
|
+
export default function Cards(props) {
|
|
10
|
+
return <div class="afwd-cards">{props.children}</div>;
|
|
11
|
+
}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
// A code block matching the MDX front-end's `.afw-code` structure (header bar with
|
|
2
|
+
// an optional language/filename label and a copy button, above a `<pre>`). Use it for
|
|
3
|
+
// code that doesn't come from a Markdown fence — e.g. a code panel inside `Tabs`:
|
|
4
|
+
// `{ label, content: <CodeBlock code="…" /> }`. The text is NOT syntax-highlighted —
|
|
5
|
+
// highlighting is a build-time (syntect) pass that only sees literal Markdown fences,
|
|
6
|
+
// not a runtime string prop; runtime highlighting here is deferred future work. The
|
|
7
|
+
// copy button owns its own behavior via `onclick` (see `copyWithFeedback`), so it
|
|
8
|
+
// works in any layout — not just the docs shell. The icon glyphs go through `RawHtml`
|
|
9
|
+
// because inline `<svg>` would be created in the HTML namespace and not render.
|
|
10
|
+
import { RawHtml, copyWithFeedback } from "@opentf/afw";
|
|
11
|
+
|
|
12
|
+
const COPY_SVG =
|
|
13
|
+
'<svg class="afw-copy-icon" viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="9" y="9" width="11" height="11" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>';
|
|
14
|
+
const CHECK_SVG =
|
|
15
|
+
'<svg class="afw-check-icon" viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20 6 9 17l-5-5"/></svg>';
|
|
16
|
+
const ICONS = COPY_SVG + CHECK_SVG;
|
|
17
|
+
|
|
18
|
+
export default function CodeBlock(props) {
|
|
19
|
+
return (
|
|
20
|
+
<div class="afw-code">
|
|
21
|
+
<div class="afw-code-head">
|
|
22
|
+
{props.lang ? <span class="afw-code-lang">{props.lang}</span> : null}
|
|
23
|
+
{props.name ? <span class="afw-code-name">{props.name}</span> : null}
|
|
24
|
+
<button
|
|
25
|
+
class="afw-copy"
|
|
26
|
+
type="button"
|
|
27
|
+
aria-label="Copy code"
|
|
28
|
+
onclick={(e) => copyWithFeedback(e.currentTarget, props.code)}
|
|
29
|
+
>
|
|
30
|
+
<RawHtml html={ICONS} />
|
|
31
|
+
<span class="afw-copy-label">Copy</span>
|
|
32
|
+
</button>
|
|
33
|
+
</div>
|
|
34
|
+
<pre>
|
|
35
|
+
<code>{props.code}</code>
|
|
36
|
+
</pre>
|
|
37
|
+
</div>
|
|
38
|
+
);
|
|
39
|
+
}
|