@opentf/afw-docs 0.0.0-stage → 0.31.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 +141 -2
- package/build/blog-posts-plugin.js +154 -0
- package/build/docs-nav-plugin.js +200 -0
- package/build/feed.js +176 -0
- package/build/frontmatter.js +45 -0
- package/build/host.js +54 -0
- package/build/index.js +13 -0
- package/build/last-updated-plugin.js +107 -0
- package/build/last-updated.js +40 -0
- package/build/llms.js +176 -0
- package/build/publish.js +29 -0
- package/build/reading-time.js +16 -0
- package/build/search.js +27 -0
- package/components/BlogLayout.jsx +104 -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/FeedLinks.jsx +47 -0
- package/components/Footer.jsx +25 -0
- package/components/LastUpdated.jsx +20 -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 +24 -0
- package/components/PostList.jsx +25 -0
- package/components/PostMeta.jsx +37 -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 +106 -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 +69 -0
- package/nav-virtual.js +18 -0
- package/package.json +79 -4
- package/posts-virtual.js +17 -0
- package/search.js +285 -0
- package/theme/index.css +1843 -0
- package/types/config.d.ts +39 -0
- package/types/index.d.ts +70 -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/build/feed.js
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
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
|
+
/**
|
|
36
|
+
* A post's body for a feed, from its prerendered page: the inner HTML of the page's
|
|
37
|
+
* `<article class="afwd-prose">`, with what only a live page needs removed (hydration
|
|
38
|
+
* comments, scripts, `<template>`s, the copy buttons on code blocks) and root-relative
|
|
39
|
+
* `src`/`href` made absolute, since a feed reader has no base URL. A `cover` leads the
|
|
40
|
+
* body as an image. Returns "" when the page has no prose article.
|
|
41
|
+
*/
|
|
42
|
+
export function postContentHtml(pageHtml, baseUrl, cover) {
|
|
43
|
+
const m = String(pageHtml).match(/<article class="afwd-prose">([\s\S]*)<\/article>/);
|
|
44
|
+
if (!m) return "";
|
|
45
|
+
const body = m[1]
|
|
46
|
+
.replace(/<!--[\s\S]*?-->/g, "")
|
|
47
|
+
.replace(/<script\b[\s\S]*?<\/script>/gi, "")
|
|
48
|
+
.replace(/<template\b[\s\S]*?<\/template>/gi, "")
|
|
49
|
+
.replace(/<button\b[\s\S]*?<\/button>/gi, "")
|
|
50
|
+
.replace(/\s(src|href)="\/(?!\/)/g, (_, attr) => ` ${attr}="${baseUrl.replace(/\/+$/, "")}/`)
|
|
51
|
+
.trim();
|
|
52
|
+
const image = cover ? `<p><img src="${esc(abs(baseUrl, cover))}" alt=""></p>` : "";
|
|
53
|
+
return image + body;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** CDATA section around `s`, splitting any `]]>` inside it. */
|
|
57
|
+
function cdata(s) {
|
|
58
|
+
return `<![CDATA[${String(s).replace(/]]>/g, "]]]]><![CDATA[>")}]]>`;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** Newest valid publication instant, independent of post display order. */
|
|
62
|
+
function newestPostDate(posts) {
|
|
63
|
+
let newest = -Infinity;
|
|
64
|
+
for (const post of posts) {
|
|
65
|
+
if (!post.date) continue;
|
|
66
|
+
const timestamp = new Date(post.date).getTime();
|
|
67
|
+
if (!Number.isNaN(timestamp) && timestamp > newest) newest = timestamp;
|
|
68
|
+
}
|
|
69
|
+
return newest === -Infinity ? null : new Date(newest);
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Render an RSS 2.0 feed.
|
|
74
|
+
*
|
|
75
|
+
* @param {Object} opts
|
|
76
|
+
* @param {Array} opts.posts Post list (from `loadPosts`).
|
|
77
|
+
* @param {string} opts.baseUrl Canonical site origin (required; absolute links).
|
|
78
|
+
* @param {string} [opts.feedPath] Path of the feed itself (for `<atom:link rel=self>`).
|
|
79
|
+
* @param {Object} [opts.channel] `{ title, description, link, language }`.
|
|
80
|
+
* @returns {string} The `rss.xml` document.
|
|
81
|
+
*/
|
|
82
|
+
export function renderBlogFeed({ posts = [], baseUrl, feedPath = "/blog/rss.xml", channel = {} } = {}) {
|
|
83
|
+
const title = channel.title || "Blog";
|
|
84
|
+
const description = channel.description || title;
|
|
85
|
+
const link = channel.link ? abs(baseUrl, channel.link) : abs(baseUrl, "/blog");
|
|
86
|
+
const language = channel.language || "en";
|
|
87
|
+
const self = abs(baseUrl, feedPath);
|
|
88
|
+
const lastBuild = rfc822(newestPostDate(posts)) || new Date().toUTCString();
|
|
89
|
+
|
|
90
|
+
const items = posts
|
|
91
|
+
.map((p) => {
|
|
92
|
+
const url = abs(baseUrl, p.path);
|
|
93
|
+
const pubDate = rfc822(p.date);
|
|
94
|
+
const parts = [
|
|
95
|
+
` <title>${esc(p.title)}</title>`,
|
|
96
|
+
` <link>${esc(url)}</link>`,
|
|
97
|
+
` <guid isPermaLink="true">${esc(url)}</guid>`,
|
|
98
|
+
];
|
|
99
|
+
if (pubDate) parts.push(` <pubDate>${pubDate}</pubDate>`);
|
|
100
|
+
if (p.author) parts.push(` <dc:creator>${esc(p.author)}</dc:creator>`);
|
|
101
|
+
if (p.description) parts.push(` <description>${esc(p.description)}</description>`);
|
|
102
|
+
// The full post (`postContentHtml`), so a reader can show it without a click-through.
|
|
103
|
+
if (p.content) parts.push(` <content:encoded>${cdata(p.content)}</content:encoded>`);
|
|
104
|
+
for (const tag of p.tags || []) parts.push(` <category>${esc(tag)}</category>`);
|
|
105
|
+
return ` <item>\n${parts.join("\n")}\n </item>`;
|
|
106
|
+
})
|
|
107
|
+
.join("\n");
|
|
108
|
+
|
|
109
|
+
return (
|
|
110
|
+
`<?xml version="1.0" encoding="UTF-8"?>\n` +
|
|
111
|
+
`<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/">\n` +
|
|
112
|
+
` <channel>\n` +
|
|
113
|
+
` <title>${esc(title)}</title>\n` +
|
|
114
|
+
` <link>${esc(link)}</link>\n` +
|
|
115
|
+
` <atom:link href="${esc(self)}" rel="self" type="application/rss+xml"/>\n` +
|
|
116
|
+
` <description>${esc(description)}</description>\n` +
|
|
117
|
+
` <language>${esc(language)}</language>\n` +
|
|
118
|
+
` <lastBuildDate>${lastBuild}</lastBuildDate>\n` +
|
|
119
|
+
` <generator>@opentf/afw-docs</generator>\n` +
|
|
120
|
+
(items ? items + "\n" : "") +
|
|
121
|
+
` </channel>\n` +
|
|
122
|
+
`</rss>\n`
|
|
123
|
+
);
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* Render an Atom 1.0 feed.
|
|
128
|
+
*
|
|
129
|
+
* @param {Object} opts
|
|
130
|
+
* @param {Array} opts.posts Post list (from `loadPosts`).
|
|
131
|
+
* @param {string} opts.baseUrl Canonical site origin (required; absolute links).
|
|
132
|
+
* @param {string} [opts.feedPath] Path of the feed itself (for `<link rel=self>`).
|
|
133
|
+
* @param {Object} [opts.channel] `{ title, description, link, author }`.
|
|
134
|
+
* @returns {string} The `atom.xml` document.
|
|
135
|
+
*/
|
|
136
|
+
export function renderAtomFeed({ posts = [], baseUrl, feedPath = "/blog/atom.xml", channel = {} } = {}) {
|
|
137
|
+
const title = channel.title || "Blog";
|
|
138
|
+
const description = channel.description || title;
|
|
139
|
+
const link = channel.link ? abs(baseUrl, channel.link) : abs(baseUrl, "/blog");
|
|
140
|
+
const self = abs(baseUrl, feedPath);
|
|
141
|
+
const updated = iso8601(newestPostDate(posts)) || new Date().toISOString();
|
|
142
|
+
const fallbackAuthor = channel.author || title;
|
|
143
|
+
|
|
144
|
+
const entries = posts
|
|
145
|
+
.map((p) => {
|
|
146
|
+
const url = abs(baseUrl, p.path);
|
|
147
|
+
const published = iso8601(p.date);
|
|
148
|
+
const parts = [
|
|
149
|
+
` <title>${esc(p.title)}</title>`,
|
|
150
|
+
` <link href="${esc(url)}"/>`,
|
|
151
|
+
` <id>${esc(url)}</id>`,
|
|
152
|
+
` <updated>${iso8601(p.updated) || published || updated}</updated>`,
|
|
153
|
+
];
|
|
154
|
+
if (published) parts.push(` <published>${published}</published>`);
|
|
155
|
+
parts.push(` <author><name>${esc(p.author || fallbackAuthor)}</name></author>`);
|
|
156
|
+
if (p.description) parts.push(` <summary>${esc(p.description)}</summary>`);
|
|
157
|
+
if (p.content) parts.push(` <content type="html">${esc(p.content)}</content>`);
|
|
158
|
+
for (const tag of p.tags || []) parts.push(` <category term="${esc(tag)}"/>`);
|
|
159
|
+
return ` <entry>\n${parts.join("\n")}\n </entry>`;
|
|
160
|
+
})
|
|
161
|
+
.join("\n");
|
|
162
|
+
|
|
163
|
+
return (
|
|
164
|
+
`<?xml version="1.0" encoding="UTF-8"?>\n` +
|
|
165
|
+
`<feed xmlns="http://www.w3.org/2005/Atom">\n` +
|
|
166
|
+
` <title>${esc(title)}</title>\n` +
|
|
167
|
+
` <subtitle>${esc(description)}</subtitle>\n` +
|
|
168
|
+
` <link href="${esc(link)}"/>\n` +
|
|
169
|
+
` <link href="${esc(self)}" rel="self" type="application/atom+xml"/>\n` +
|
|
170
|
+
` <id>${esc(link)}</id>\n` +
|
|
171
|
+
` <updated>${updated}</updated>\n` +
|
|
172
|
+
` <generator>@opentf/afw-docs</generator>\n` +
|
|
173
|
+
(entries ? entries + "\n" : "") +
|
|
174
|
+
`</feed>\n`
|
|
175
|
+
);
|
|
176
|
+
}
|
|
@@ -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,13 @@
|
|
|
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 { isUnpublished } from "./publish.js";
|
|
11
|
+
export { postContentHtml, renderAtomFeed, renderBlogFeed } from "./feed.js";
|
|
12
|
+
export { renderLlmsFullTxt, renderLlmsTxt } from "./llms.js";
|
|
13
|
+
export { indexWithAfwSearch } from "./search.js";
|
|
@@ -0,0 +1,107 @@
|
|
|
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
|
+
import { frontmatterUpdated } from "./publish.js";
|
|
18
|
+
|
|
19
|
+
const VIRTUAL_ID = "@opentf/afw-docs/updated";
|
|
20
|
+
// No NUL sentinel: the bundler marks a module virtual explicitly, and a `\0` in
|
|
21
|
+
// a hook filter is an invalid regex — which silently matches *everything*.
|
|
22
|
+
const RESOLVED_ID = "afw-virtual:afw-last-updated";
|
|
23
|
+
const PAGE_RE = /^page\.(mdx|md|[jt]sx)$/;
|
|
24
|
+
const MD_RE = /\.(mdx|md)$/;
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* @param {Object} opts
|
|
28
|
+
* @param {string} opts.appDir
|
|
29
|
+
* @param {Set<string>} [opts.exclude] Folder names to skip (mirrors route exclusions).
|
|
30
|
+
* @param {string} [opts.blogDir] The blog folder under `app/`. Its posts take their date
|
|
31
|
+
* from frontmatter `updated` only, never git (see `collect`).
|
|
32
|
+
*/
|
|
33
|
+
export function lastUpdatedPlugin({ appDir, exclude = new Set(), blogDir } = {}) {
|
|
34
|
+
return {
|
|
35
|
+
name: "afw-last-updated",
|
|
36
|
+
resolve: {
|
|
37
|
+
filter: { id: VIRTUAL_ID },
|
|
38
|
+
handler: (source) => (source === VIRTUAL_ID ? { id: RESOLVED_ID, virtual: true } : null),
|
|
39
|
+
},
|
|
40
|
+
load: {
|
|
41
|
+
filter: { id: RESOLVED_ID },
|
|
42
|
+
async handler(id) {
|
|
43
|
+
if (id !== RESOLVED_ID) return null;
|
|
44
|
+
const watch = [];
|
|
45
|
+
const { updated, editPaths } = await collect(appDir, exclude, watch, blogDir);
|
|
46
|
+
// Default export: the `{ route: ISO }` last-updated map. Named `editPaths`:
|
|
47
|
+
// `{ route: repo-relative-file }`, for building "Edit this page" links.
|
|
48
|
+
return {
|
|
49
|
+
code:
|
|
50
|
+
`export default ${JSON.stringify(updated)};\n` +
|
|
51
|
+
`export const editPaths = ${JSON.stringify(editPaths)};\n`,
|
|
52
|
+
dependsOn: watch,
|
|
53
|
+
};
|
|
54
|
+
},
|
|
55
|
+
},
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* The `{ [routePath]: ISO }` last-updated map, callable directly (used by the SSG SEO
|
|
61
|
+
* step). Mirrors what the virtual module exposes.
|
|
62
|
+
*/
|
|
63
|
+
export async function loadLastUpdated({ appDir, exclude = new Set(), blogDir } = {}) {
|
|
64
|
+
return (await collect(appDir, exclude, [], blogDir)).updated;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** Git repo root containing `dir`, or null (so edit links degrade gracefully). */
|
|
68
|
+
const gitRoot = (dir) => runOut("git", ["rev-parse", "--show-toplevel"], dir);
|
|
69
|
+
|
|
70
|
+
async function collect(appDir, exclude, watch, blogDir) {
|
|
71
|
+
// Plugin options are plain config data, so a relative `appDir` ("app") is relative
|
|
72
|
+
// to the project directory plugins run in. Resolve it here: git runs from each
|
|
73
|
+
// page's own folder, where a relative page path would point somewhere else.
|
|
74
|
+
appDir = resolve(cwd(), appDir);
|
|
75
|
+
const updated = {};
|
|
76
|
+
const editPaths = {};
|
|
77
|
+
const root0 = await gitRoot(appDir);
|
|
78
|
+
// One walk over every page under app/ — covers all sections (and the home page).
|
|
79
|
+
await walk(appDir, "", exclude, async (file, route) => {
|
|
80
|
+
watch.push(file);
|
|
81
|
+
const fm = MD_RE.test(file) ? await readFrontmatter(file) : {};
|
|
82
|
+
// A blog post's "updated" is an author's statement, so it is read from frontmatter
|
|
83
|
+
// alone. Git would date every post to the last bulk commit that touched them all.
|
|
84
|
+
const post = blogDir && route.startsWith(`/${blogDir}/`);
|
|
85
|
+
const iso = post
|
|
86
|
+
? (frontmatterUpdated(fm) ? await resolveLastUpdated(file, frontmatterUpdated(fm)) : null)
|
|
87
|
+
: await resolveLastUpdated(file, fm.lastUpdated);
|
|
88
|
+
if (iso) updated[route] = iso;
|
|
89
|
+
// Repo-relative path (POSIX separators) for the "Edit this page" link.
|
|
90
|
+
if (root0) editPaths[route] = relative(root0, file).split(/[\\/]/).join("/");
|
|
91
|
+
});
|
|
92
|
+
return { updated, editPaths };
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** Recursively find every `page.*` under `root`, mapping it to its route path. */
|
|
96
|
+
async function walk(dir, route, exclude, onPage) {
|
|
97
|
+
for (const entry of await readEntries(dir)) {
|
|
98
|
+
if (entry.isDir) {
|
|
99
|
+
if (entry.name.startsWith(".") || entry.name.startsWith("_") || exclude.has(entry.name)) {
|
|
100
|
+
continue;
|
|
101
|
+
}
|
|
102
|
+
await walk(join(dir, entry.name), `${route}/${entry.name}`, exclude, onPage);
|
|
103
|
+
} else if (PAGE_RE.test(entry.name)) {
|
|
104
|
+
await onPage(join(dir, entry.name), route || "/");
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
}
|
|
@@ -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
|
+
}
|
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
|
+
}
|
|
@@ -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
|
+
}
|