@opentf/afw-docs 0.30.0 → 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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Open Tech Foundation and contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,142 @@
1
+ <div align="center">
2
+
3
+ # @opentf/afw-docs
4
+
5
+ ***Documentation and blog sites built as ordinary AFW apps***
6
+
7
+ [Docs](https://afw.opentechf.org/packages/afw-docs) | [API](https://afw.opentechf.org/api/afw-docs) | [Changelog](https://github.com/Open-Tech-Foundation/afw/blob/main/packages/afw-docs/CHANGELOG.md) | [GitHub](https://github.com/Open-Tech-Foundation/afw)
8
+
9
+ </div>
10
+
11
+ <div align="right">
12
+
13
+ *An [Open Tech Foundation](https://opentechf.org/) project*
14
+
15
+ </div>
16
+
17
+ > Write pages as MDX in `app/`. The theme supplies the navbar, sidebar, table of
18
+ > contents, breadcrumbs, search and prev/next links, and generates the navigation
19
+ > from your folders at build time. The [AFW website](https://afw.opentechf.org) is
20
+ > built with it.
21
+
22
+ ```jsx
23
+ // app/docs/layout.jsx
24
+ import { DocsLayout } from "@opentf/afw-docs";
25
+ import config from "../../afw.config.js";
26
+
27
+ export default function Layout(props) {
28
+ return <DocsLayout config={config.docs}>{props.children}</DocsLayout>;
29
+ }
30
+ ```
31
+
32
+ ```mdx
33
+ ---
34
+ title: Reactivity
35
+ description: Signal-based state.
36
+ ---
37
+
38
+ import { Callout } from "@opentf/afw-docs";
39
+
40
+ # Reactivity
41
+
42
+ <Callout type="tip">Mix components into Markdown freely.</Callout>
43
+ ```
44
+
45
+ Every folder under `app/` with a layout like this becomes its own section with its
46
+ own sidebar: `app/docs` serves `/docs` and `app/api` serves `/api`.
47
+
48
+ > [!NOTE]
49
+ > **Alpha.** Components, options and class names can change between minor
50
+ > versions; see the [changelog](https://github.com/Open-Tech-Foundation/afw/blob/main/packages/afw-docs/CHANGELOG.md).
51
+
52
+ ## Why afw-docs
53
+
54
+ | Need | How afw-docs meets it |
55
+ | --- | --- |
56
+ | 🧭 **Navigation from folders** | The sidebar, breadcrumbs and prev/next are generated from `app/`; `_meta.js` sets order and labels |
57
+ | 🔎 **Search without a service** | A static index built from the prerendered HTML by `afwc`, queried in the browser |
58
+ | ✍️ **MDX with components** | Callouts, tabs, steps, cards and code blocks with copy buttons, highlighted at build time |
59
+ | 📰 **Blog included** | Post lists, banners, reading time and RSS/Atom feeds |
60
+ | 🕒 **Last updated and edit links** | Dates from git history or frontmatter, linked to the source file |
61
+ | 🌗 **Themeable** | Light and dark modes driven by `--afw-*` CSS variables, in an overridable cascade layer |
62
+ | 🤖 **LLM-ready** | `llms.txt` and `llms-full.txt` generated at build |
63
+
64
+ ## Install
65
+
66
+ ```sh
67
+ pnpm add @opentf/afw-docs @opentf/afw
68
+ pnpm add -D @opentf/esdev-plugin-afw @opentf/afw-cli
69
+ ```
70
+
71
+ `esdev create my-docs --template=docs` generates a complete site. To add the theme
72
+ to an existing project, import its stylesheet and register the build plugins:
73
+
74
+ ```css
75
+ /* app/global.css */
76
+ @import "@opentf/afw-docs/theme";
77
+ ```
78
+
79
+ ```json
80
+ {
81
+ "plugins": [
82
+ { "module": "@opentf/esdev-plugin-afw", "options": { "mode": "ssg" } },
83
+ { "module": "@opentf/afw-docs/build", "export": "docsNavPlugin", "options": { "appDir": "app" } },
84
+ { "module": "@opentf/afw-docs/build", "export": "lastUpdatedPlugin", "options": { "appDir": "app" } },
85
+ { "module": "@opentf/afw-docs/build", "export": "blogPostsPlugin", "options": { "appDir": "app", "contentDir": "blog" } }
86
+ ]
87
+ }
88
+ ```
89
+
90
+ `appDir` is resolved from the directory esdev runs in.
91
+
92
+ ## Configure
93
+
94
+ ```js
95
+ // afw.config.js
96
+ import { defineDocsConfig } from "@opentf/afw-docs/config";
97
+
98
+ export default defineDocsConfig({
99
+ site: { url: "https://docs.example.com" },
100
+ docs: {
101
+ title: "My Project",
102
+ github: "https://github.com/me/my-project",
103
+ repoUrl: "https://github.com/me/my-project",
104
+ nav: [
105
+ { label: "Docs", href: "/docs" },
106
+ { label: "Blog", href: "/blog" },
107
+ ],
108
+ lastUpdated: true,
109
+ },
110
+ });
111
+ ```
112
+
113
+ ## Components
114
+
115
+ | Group | Components |
116
+ | --- | --- |
117
+ | **Layouts** | `DocsLayout`, `BlogLayout` |
118
+ | **Shell** | `Navbar`, `NavbarLink`, `Sidebar`, `SidebarToggle`, `Toc`, `Breadcrumbs`, `Pagination`, `Footer`, `LastUpdated`, `ThemeToggle`, `Search`, `SearchTrigger` |
119
+ | **Content** | `Callout`, `Tabs`, `Steps`, `CodeBlock`, `Table`, `Cards`, `Card`, `Tooltip`, `NavIcon` |
120
+ | **Blog** | `PostList`, `PostCard`, `PostBanner`, `PostMeta`, `ReadingTime` |
121
+
122
+ ## Entry points
123
+
124
+ | Import | Contents |
125
+ | --- | --- |
126
+ | `@opentf/afw-docs` | Every component above, plus `createSearch` |
127
+ | `@opentf/afw-docs/theme` | The default light/dark stylesheet |
128
+ | `@opentf/afw-docs/config` | `defineDocsConfig` and the config types |
129
+ | `@opentf/afw-docs/build` | `docsNavPlugin`, `blogPostsPlugin`, `lastUpdatedPlugin`, feed and `llms.txt` renderers |
130
+ | `@opentf/afw-docs/nav`, `/posts`, `/updated` | Generated navigation, post list and last-updated map |
131
+ | `@opentf/afw-docs/search` | Browser search: `createSearch`, `tokenize`, `excerptParts` |
132
+
133
+ ## Styling
134
+
135
+ The theme's own elements use `afwd-*` classes (`.afwd-sidebar`, `.afwd-callout-tip`),
136
+ and its colours come from `--afw-*` variables that switch on `[data-theme='dark']`.
137
+ All theme rules sit in the `afw-docs` cascade layer, so any rule in your own
138
+ stylesheet overrides them without raising specificity.
139
+
140
+ ## License
141
+
142
+ MIT — see [LICENSE](https://github.com/Open-Tech-Foundation/afw/blob/main/LICENSE).
@@ -4,8 +4,10 @@
4
4
  // module `@opentf/afw-docs/posts` to the ordered post list. A pure build-time
5
5
  // consumer of the file tree — no compiler stage, no runtime cost.
6
6
  //
7
- // Post shape: `{ slug, path, title, description?, date?, author?, tags?, readingTime,
8
- // order? }`. Sorted newest-first by `date`; a numeric `order` (frontmatter) overrides.
7
+ // Post shape: `{ slug, path, title, description?, date?, updated?, author?, tags?,
8
+ // readingTime, order? }`. Sorted newest-first by `date`; a numeric `order` (frontmatter)
9
+ // overrides. Drafts and future-dated posts are left out except under `esdev start`
10
+ // (see publish.js).
9
11
 
10
12
  import { join } from "runtime:path";
11
13
 
@@ -13,6 +15,7 @@ import { exists, readEntries, readNames, readText } from "./host.js";
13
15
 
14
16
  import { readFrontmatter } from "./frontmatter.js";
15
17
  import { readingTime } from "./reading-time.js";
18
+ import { frontmatterUpdated, isUnpublished, showsUnpublished } from "./publish.js";
16
19
 
17
20
  const VIRTUAL_ID = "@opentf/afw-docs/posts";
18
21
  // No NUL sentinel: the bundler marks a module virtual explicitly, and a `\0` in
@@ -25,8 +28,10 @@ const PAGE_RE = /^page\.(mdx|md)$/;
25
28
  * @param {string} opts.appDir Absolute path to the project's `app/` directory.
26
29
  * @param {string} [opts.contentDir] Blog content folder under app/ (default "blog").
27
30
  * @param {Set<string>} [opts.exclude] Folder names to skip.
31
+ * @param {boolean} [opts.drafts] List drafts and scheduled posts (default: only under
32
+ * `esdev start`).
28
33
  */
29
- export function blogPostsPlugin({ appDir, contentDir = "blog", exclude = new Set() } = {}) {
34
+ export function blogPostsPlugin({ appDir, contentDir = "blog", exclude = new Set(), drafts } = {}) {
30
35
  const root = join(appDir, contentDir);
31
36
  const base = "/" + contentDir;
32
37
  return {
@@ -37,10 +42,11 @@ export function blogPostsPlugin({ appDir, contentDir = "blog", exclude = new Set
37
42
  },
38
43
  load: {
39
44
  filter: { id: RESOLVED_ID },
40
- async handler(id) {
45
+ async handler(id, ctx) {
41
46
  if (id !== RESOLVED_ID) return null;
42
47
  const watch = [];
43
- const posts = (await exists(root)) ? await collectPosts(root, base, exclude, watch) : [];
48
+ const all = showsUnpublished(drafts, ctx);
49
+ const posts = (await exists(root)) ? await collectPosts(root, base, exclude, watch, all) : [];
44
50
  // The post list is generated from these files, which nothing imports —
45
51
  // declaring them is what rebuilds the chunk when a post's frontmatter changes.
46
52
  return {
@@ -61,16 +67,18 @@ export function blogPostsPlugin({ appDir, contentDir = "blog", exclude = new Set
61
67
  * @param {string} opts.appDir
62
68
  * @param {string} [opts.contentDir]
63
69
  * @param {Set<string>} [opts.exclude]
70
+ * @param {boolean} [opts.drafts] Include drafts and scheduled posts (default false: this
71
+ * feeds production output).
64
72
  */
65
- export async function loadPosts({ appDir, contentDir = "blog", exclude = new Set() } = {}) {
73
+ export async function loadPosts({ appDir, contentDir = "blog", exclude = new Set(), drafts = false } = {}) {
66
74
  const root = join(appDir, contentDir);
67
75
  if (!(await exists(root))) return [];
68
- return collectPosts(root, "/" + contentDir, exclude, []);
76
+ return collectPosts(root, "/" + contentDir, exclude, [], drafts);
69
77
  }
70
78
 
71
79
  // Automatic post metadata describes concrete folders; generated parameters are
72
80
  // unavailable during this scan and must not become card or feed URLs.
73
- async function collectPosts(root, base, exclude, watch) {
81
+ async function collectPosts(root, base, exclude, watch, drafts) {
74
82
  const posts = [];
75
83
  for (const entry of await readEntries(root)) {
76
84
  if (
@@ -90,6 +98,7 @@ async function collectPosts(root, base, exclude, watch) {
90
98
  watch.push(file);
91
99
  const source = await readText(file);
92
100
  const fm = await readFrontmatter(file);
101
+ if (!drafts && isUnpublished(fm)) continue;
93
102
  posts.push(
94
103
  clean({
95
104
  slug: entry.name,
@@ -97,6 +106,10 @@ async function collectPosts(root, base, exclude, watch) {
97
106
  title: fm.title ?? humanize(entry.name),
98
107
  description: fm.description,
99
108
  date: fm.date != null ? String(fm.date) : undefined,
109
+ // Frontmatter only, never git: a bulk commit (a rename, a reformat) touches
110
+ // every post without changing what any of them says.
111
+ updated: frontmatterUpdated(fm),
112
+ draft: drafts && isUnpublished(fm) ? true : undefined,
100
113
  // Cover image (frontmatter `cover`) — shown on the post banner and the card.
101
114
  cover: fm.cover,
102
115
  author: fm.author,
@@ -14,6 +14,7 @@ import { join, toFileURL } from "runtime:path";
14
14
 
15
15
  import { exists, readEntries, readNames, readText } from "./host.js";
16
16
  import { readFrontmatter } from "./frontmatter.js";
17
+ import { isUnpublished, showsUnpublished } from "./publish.js";
17
18
 
18
19
  const VIRTUAL_ID = "@opentf/afw-docs/nav";
19
20
  // No NUL sentinel: the bundler marks a module virtual explicitly, and a `\0` in
@@ -42,8 +43,9 @@ function navDirectory(entry, exclude) {
42
43
  * @param {(file: string) => Promise<any>} [opts.importModule] How to read a `_meta.js`.
43
44
  * The dev server passes a loader that re-evaluates the file after an edit; a plain
44
45
  * `import()` cannot, because the runtime caches ESM by path for the process's life.
46
+ * @param {boolean} [opts.drafts] List draft pages (default: only under `esdev start`).
45
47
  */
46
- export function docsNavPlugin({ appDir, exclude = new Set(), importModule } = {}) {
48
+ export function docsNavPlugin({ appDir, exclude = new Set(), importModule, drafts } = {}) {
47
49
  return {
48
50
  name: "afw-docs-nav",
49
51
  resolve: {
@@ -52,9 +54,9 @@ export function docsNavPlugin({ appDir, exclude = new Set(), importModule } = {}
52
54
  },
53
55
  load: {
54
56
  filter: { id: RESOLVED_ID },
55
- async handler(id) {
57
+ async handler(id, hookCtx) {
56
58
  if (id !== RESOLVED_ID) return null;
57
- const ctx = { watch: [], importModule };
59
+ const ctx = { watch: [], importModule, drafts: showsUnpublished(drafts, hookCtx) };
58
60
  const out = {};
59
61
  for (const entry of await readEntries(appDir)) {
60
62
  if (!navDirectory(entry, exclude)) continue;
@@ -177,13 +179,15 @@ async function buildNode(dir, route, key, parentMeta, ctx, exclude) {
177
179
  if (MD_RE.test(pf)) fm = await readFrontmatter(pf);
178
180
  }
179
181
  const children = await buildSection(dir, route, ctx, false, exclude);
182
+ // An unpublished page is left out of the production nav; its children still show.
183
+ const page = pf && (ctx.drafts || !isUnpublished(fm)) ? pf : null;
180
184
  // A directory that has neither a page nor children contributes nothing.
181
- if (!pf && children.length === 0) return null;
185
+ if (!page && children.length === 0) return null;
182
186
 
183
187
  const title = metaLabel(parentMeta, key) ?? fm.sidebar_label ?? fm.title ?? humanize(key);
184
188
  return clean({
185
189
  title,
186
- path: pf ? route : undefined,
190
+ path: page ? route : undefined,
187
191
  order: fm.order,
188
192
  items: children.length ? children : undefined,
189
193
  });
package/build/feed.js CHANGED
@@ -32,6 +32,32 @@ function iso8601(date) {
32
32
  return Number.isNaN(d.getTime()) ? null : d.toISOString();
33
33
  }
34
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
+
35
61
  /** Newest valid publication instant, independent of post display order. */
36
62
  function newestPostDate(posts) {
37
63
  let newest = -Infinity;
@@ -73,6 +99,8 @@ export function renderBlogFeed({ posts = [], baseUrl, feedPath = "/blog/rss.xml"
73
99
  if (pubDate) parts.push(` <pubDate>${pubDate}</pubDate>`);
74
100
  if (p.author) parts.push(` <dc:creator>${esc(p.author)}</dc:creator>`);
75
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>`);
76
104
  for (const tag of p.tags || []) parts.push(` <category>${esc(tag)}</category>`);
77
105
  return ` <item>\n${parts.join("\n")}\n </item>`;
78
106
  })
@@ -80,7 +108,7 @@ export function renderBlogFeed({ posts = [], baseUrl, feedPath = "/blog/rss.xml"
80
108
 
81
109
  return (
82
110
  `<?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` +
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` +
84
112
  ` <channel>\n` +
85
113
  ` <title>${esc(title)}</title>\n` +
86
114
  ` <link>${esc(link)}</link>\n` +
@@ -121,11 +149,12 @@ export function renderAtomFeed({ posts = [], baseUrl, feedPath = "/blog/atom.xml
121
149
  ` <title>${esc(p.title)}</title>`,
122
150
  ` <link href="${esc(url)}"/>`,
123
151
  ` <id>${esc(url)}</id>`,
124
- ` <updated>${published || updated}</updated>`,
152
+ ` <updated>${iso8601(p.updated) || published || updated}</updated>`,
125
153
  ];
126
154
  if (published) parts.push(` <published>${published}</published>`);
127
155
  parts.push(` <author><name>${esc(p.author || fallbackAuthor)}</name></author>`);
128
156
  if (p.description) parts.push(` <summary>${esc(p.description)}</summary>`);
157
+ if (p.content) parts.push(` <content type="html">${esc(p.content)}</content>`);
129
158
  for (const tag of p.tags || []) parts.push(` <category term="${esc(tag)}"/>`);
130
159
  return ` <entry>\n${parts.join("\n")}\n </entry>`;
131
160
  })
package/build/index.js CHANGED
@@ -7,6 +7,7 @@
7
7
  export { docsNavPlugin } from "./docs-nav-plugin.js";
8
8
  export { blogPostsPlugin, loadPosts } from "./blog-posts-plugin.js";
9
9
  export { lastUpdatedPlugin, loadLastUpdated } from "./last-updated-plugin.js";
10
- export { renderAtomFeed, renderBlogFeed } from "./feed.js";
10
+ export { isUnpublished } from "./publish.js";
11
+ export { postContentHtml, renderAtomFeed, renderBlogFeed } from "./feed.js";
11
12
  export { renderLlmsFullTxt, renderLlmsTxt } from "./llms.js";
12
13
  export { indexWithAfwSearch } from "./search.js";
@@ -14,6 +14,7 @@ import { cwd } from "runtime:process";
14
14
  import { readEntries, runOut } from "./host.js";
15
15
  import { readFrontmatter } from "./frontmatter.js";
16
16
  import { resolveLastUpdated } from "./last-updated.js";
17
+ import { frontmatterUpdated } from "./publish.js";
17
18
 
18
19
  const VIRTUAL_ID = "@opentf/afw-docs/updated";
19
20
  // No NUL sentinel: the bundler marks a module virtual explicitly, and a `\0` in
@@ -26,8 +27,10 @@ const MD_RE = /\.(mdx|md)$/;
26
27
  * @param {Object} opts
27
28
  * @param {string} opts.appDir
28
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`).
29
32
  */
30
- export function lastUpdatedPlugin({ appDir, exclude = new Set() } = {}) {
33
+ export function lastUpdatedPlugin({ appDir, exclude = new Set(), blogDir } = {}) {
31
34
  return {
32
35
  name: "afw-last-updated",
33
36
  resolve: {
@@ -39,7 +42,7 @@ export function lastUpdatedPlugin({ appDir, exclude = new Set() } = {}) {
39
42
  async handler(id) {
40
43
  if (id !== RESOLVED_ID) return null;
41
44
  const watch = [];
42
- const { updated, editPaths } = await collect(appDir, exclude, watch);
45
+ const { updated, editPaths } = await collect(appDir, exclude, watch, blogDir);
43
46
  // Default export: the `{ route: ISO }` last-updated map. Named `editPaths`:
44
47
  // `{ route: repo-relative-file }`, for building "Edit this page" links.
45
48
  return {
@@ -57,14 +60,14 @@ export function lastUpdatedPlugin({ appDir, exclude = new Set() } = {}) {
57
60
  * The `{ [routePath]: ISO }` last-updated map, callable directly (used by the SSG SEO
58
61
  * step). Mirrors what the virtual module exposes.
59
62
  */
60
- export async function loadLastUpdated({ appDir, exclude = new Set() } = {}) {
61
- return (await collect(appDir, exclude, [])).updated;
63
+ export async function loadLastUpdated({ appDir, exclude = new Set(), blogDir } = {}) {
64
+ return (await collect(appDir, exclude, [], blogDir)).updated;
62
65
  }
63
66
 
64
67
  /** Git repo root containing `dir`, or null (so edit links degrade gracefully). */
65
68
  const gitRoot = (dir) => runOut("git", ["rev-parse", "--show-toplevel"], dir);
66
69
 
67
- async function collect(appDir, exclude, watch) {
70
+ async function collect(appDir, exclude, watch, blogDir) {
68
71
  // Plugin options are plain config data, so a relative `appDir` ("app") is relative
69
72
  // to the project directory plugins run in. Resolve it here: git runs from each
70
73
  // page's own folder, where a relative page path would point somewhere else.
@@ -76,7 +79,12 @@ async function collect(appDir, exclude, watch) {
76
79
  await walk(appDir, "", exclude, async (file, route) => {
77
80
  watch.push(file);
78
81
  const fm = MD_RE.test(file) ? await readFrontmatter(file) : {};
79
- const iso = await resolveLastUpdated(file, fm.lastUpdated);
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);
80
88
  if (iso) updated[route] = iso;
81
89
  // Repo-relative path (POSIX separators) for the "Edit this page" link.
82
90
  if (root0) editPaths[route] = relative(root0, file).split(/[\\/]/).join("/");
@@ -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
+ }
@@ -17,29 +17,37 @@
17
17
  // The layout factory re-runs on every navigation (the router rebuilds the route +
18
18
  // layout chain), so reading `router.pathname` resolves to the page being shown.
19
19
  import { Link, RawHtml, router } from "@opentf/afw";
20
- import updated from "@opentf/afw-docs/updated";
21
20
 
22
21
  import Navbar from "./Navbar.jsx";
23
22
  import Footer from "./Footer.jsx";
24
23
  import Toc from "./Toc.jsx";
25
24
  import PostBanner from "./PostBanner.jsx";
26
- import LastUpdated from "./LastUpdated.jsx";
25
+ import FeedLinks from "./FeedLinks.jsx";
27
26
  import { editedAfterPublish } from "./post-dates.js";
28
27
 
29
28
  // Structured data for crawlers: the current post as a BlogPosting, emitted in
30
29
  // the body (JSON-LD is discovered wherever it sits). `siteUrl` (optional site
31
- // origin) absolutizes the post/cover URLs. Fields the post lacks are omitted.
32
- function blogPostingJsonLd(post, siteUrl, dateModified) {
30
+ // origin) absolutizes the post/cover URLs. Fields the post lacks are omitted. The
31
+ // site (`config.title`, `config.logo`) is the publisher, as Google's article
32
+ // guidelines ask.
33
+ function blogPostingJsonLd(post, siteUrl, dateModified, config = {}) {
33
34
  const base = (siteUrl || "").replace(/\/+$/, "");
34
35
  const abs = (p) => (p ? base + p : undefined);
35
36
  const article = { "@context": "https://schema.org", "@type": "BlogPosting" };
36
37
  if (post.title) article.headline = post.title;
37
38
  if (post.description) article.description = post.description;
38
- if (post.path) article.url = abs(post.path) || post.path;
39
+ if (post.path) {
40
+ article.url = abs(post.path) || post.path;
41
+ article.mainEntityOfPage = { "@type": "WebPage", "@id": article.url };
42
+ }
39
43
  if (post.cover) article.image = abs(post.cover) || post.cover;
40
44
  if (post.date) article.datePublished = post.date;
41
45
  if (dateModified) article.dateModified = dateModified;
42
46
  if (post.author) article.author = { "@type": "Person", name: post.author };
47
+ if (config.title) {
48
+ article.publisher = { "@type": "Organization", name: config.title };
49
+ if (config.logo) article.publisher.logo = { "@type": "ImageObject", url: abs(config.logo) || config.logo };
50
+ }
43
51
  const json = JSON.stringify(article).replace(/</g, "\\u003c");
44
52
  return `<script type="application/ld+json">${json}</script>`;
45
53
  }
@@ -50,9 +58,12 @@ export default function BlogLayout(props) {
50
58
  const frame = props.frame !== false;
51
59
  const indexPath = props.indexPath || "/blog";
52
60
  const siteUrl = props.siteUrl || "";
61
+ // Subscribe links on the index and under each post; `feeds={false}` turns them off.
62
+ const feeds = props.feeds !== false;
53
63
 
54
64
  const post = posts.find((p) => p.path === router.pathname);
55
- const editedIso = post && editedAfterPublish(updated[post.path], post.date) ? updated[post.path] : null;
65
+ // The post's own frontmatter `updated`, shown in the banner. Never git: see blog-posts-plugin.js.
66
+ const editedIso = post && editedAfterPublish(post.updated, post.date) ? post.updated : null;
56
67
 
57
68
  const body = post ? (
58
69
  <div class="afwd-blog afwd-blog-post">
@@ -65,16 +76,19 @@ export default function BlogLayout(props) {
65
76
  <Link href={indexPath} class="afwd-blog-back" data-afw-search-ignore>
66
77
  ← {config.title ? `${config.title} Blog` : "Blog"}
67
78
  </Link>
68
- <PostBanner post={post} />
69
- <RawHtml html={blogPostingJsonLd(post, siteUrl, editedIso || post.date)} />
79
+ <PostBanner post={post} showUpdated />
80
+ <RawHtml html={blogPostingJsonLd(post, siteUrl, editedIso || post.date, config)} />
70
81
  <article class="afwd-prose">{props.children}</article>
71
- {editedIso ? <LastUpdated date={editedIso} /> : null}
82
+ {feeds ? <FeedLinks base={indexPath} variant="inline" /> : null}
72
83
  </main>
73
84
  <Toc />
74
85
  </div>
75
86
  ) : (
76
87
  <div class="afwd-blog afwd-blog-index">
77
- <main class="afwd-blog-main">{props.children}</main>
88
+ <main class="afwd-blog-main">
89
+ {feeds ? <FeedLinks base={indexPath} /> : null}
90
+ {props.children}
91
+ </main>
78
92
  </div>
79
93
  );
80
94
 
@@ -0,0 +1,47 @@
1
+ // Subscribe links for a blog's RSS and Atom feeds (`<base>/rss.xml`, `<base>/atom.xml`,
2
+ // written by the release build). Plain anchors, not <Link>: a feed is a file for the
3
+ // browser or a reader app, not a route the client router can render.
4
+ //
5
+ // `variant="icons"` (the index) shows an icon and the format name per feed;
6
+ // `variant="inline"` (a post's foot) is a one-line "Subscribe: RSS · Atom".
7
+
8
+ const FEEDS = [
9
+ { file: "rss.xml", label: "RSS", type: "application/rss+xml" },
10
+ { file: "atom.xml", label: "Atom", type: "application/atom+xml" },
11
+ ];
12
+
13
+ function FeedIcon() {
14
+ return (
15
+ <svg class="afwd-feed-icon" viewBox="0 0 24 24" width="14" height="14" aria-hidden="true" fill="currentColor">
16
+ <circle cx="5" cy="19" r="2.2" />
17
+ <path d="M3 10.5v3a7.5 7.5 0 0 1 7.5 7.5h3A10.5 10.5 0 0 0 3 10.5Z" />
18
+ <path d="M3 3.5v3A14.5 14.5 0 0 1 17.5 21h3A17.5 17.5 0 0 0 3 3.5Z" />
19
+ </svg>
20
+ );
21
+ }
22
+
23
+ export default function FeedLinks(props) {
24
+ const base = (props.base || "/blog").replace(/\/+$/, "");
25
+ return props.variant === "inline" ? (
26
+ <p class="afwd-feed-inline">
27
+ Subscribe:{" "}
28
+ <a href={`${base}/rss.xml`} type="application/rss+xml">RSS</a>
29
+ {" · "}
30
+ <a href={`${base}/atom.xml`} type="application/atom+xml">Atom</a>
31
+ </p>
32
+ ) : (
33
+ <nav class="afwd-feed-links" aria-label="Subscribe">
34
+ {FEEDS.map((feed) => (
35
+ <a
36
+ class="afwd-feed-link"
37
+ href={`${base}/${feed.file}`}
38
+ type={feed.type}
39
+ aria-label={`Subscribe via ${feed.label}`}
40
+ >
41
+ <FeedIcon />
42
+ <span>{feed.label}</span>
43
+ </a>
44
+ ))}
45
+ </nav>
46
+ );
47
+ }
@@ -8,15 +8,13 @@
8
8
  import { formatDate } from "./format.js";
9
9
 
10
10
  export default function LastUpdated(props) {
11
- const date = props.date;
12
- if (!date) return null;
13
11
  const label = props.label || "Last updated on";
14
- return (
12
+ return props.date ? (
15
13
  <div class="afwd-last-updated">
16
14
  {label}{" "}
17
- <time class="afwd-last-updated-time" datetime={String(date)}>
18
- {formatDate(date)}
15
+ <time class="afwd-last-updated-time" datetime={String(props.date)}>
16
+ {formatDate(props.date)}
19
17
  </time>
20
18
  </div>
21
- );
19
+ ) : null;
22
20
  }
@@ -32,7 +32,7 @@ export default function Navbar(props) {
32
32
  <div class="afwd-navbar-lead">
33
33
  <SidebarToggle />
34
34
  <Link href={config.homeUrl || "/"} class="afwd-navbar-brand">
35
- {config.logo ? <img src={config.logo} alt="" class="afwd-navbar-logo" /> : null}
35
+ {config.logo ? <img src={config.logo} alt="" class="afwd-navbar-logo" width="28" height="28" /> : null}
36
36
  <span class="afwd-navbar-title">{config.title || "Docs"}</span>
37
37
  {config.version ? <span class="afwd-navbar-version">{config.version}</span> : null}
38
38
  </Link>
@@ -8,11 +8,11 @@ export default function PostBanner(props) {
8
8
  return (
9
9
  <header class="afwd-post-banner">
10
10
  {post.cover ? (
11
- <img class="afwd-post-cover" src={post.cover} alt={post.title} />
11
+ <img class="afwd-post-cover" src={post.cover} alt="" />
12
12
  ) : null}
13
13
  <h1 class="afwd-post-title">{post.title}</h1>
14
14
  {post.description ? <p class="afwd-post-desc">{post.description}</p> : null}
15
- <PostMeta post={post} />
15
+ <PostMeta post={post} showUpdated={props.showUpdated} />
16
16
  {post.tags && post.tags.length ? (
17
17
  <div class="afwd-post-tags">
18
18
  {post.tags.map((tag) => (
@@ -1,18 +1,23 @@
1
- // One post in the blog index: a link to the post with its meta + title + excerpt.
1
+ // One post in the blog index: a link to the post with its title, excerpt and meta row. `featured` renders it as the index hero.
2
2
  import { Link } from "@opentf/afw";
3
3
  import PostMeta from "./PostMeta.jsx";
4
4
 
5
5
  export default function PostCard(props) {
6
6
  const post = props.post;
7
7
  return (
8
- <Link href={post.path} class={post.cover ? "afwd-post-card afwd-has-cover" : "afwd-post-card"}>
8
+ <Link
9
+ href={post.path}
10
+ class={"afwd-post-card" + (post.cover ? " afwd-has-cover" : "") + (props.featured ? " afwd-post-card-featured" : "")}
11
+ >
9
12
  {post.cover ? (
10
- <img class="afwd-post-card-cover" src={post.cover} alt={post.title} loading="lazy" />
13
+ // Decorative here: the title below already names the link, so a screen reader
14
+ // would otherwise read it twice.
15
+ <img class="afwd-post-card-cover" src={post.cover} alt="" loading={props.featured ? "eager" : "lazy"} />
11
16
  ) : null}
12
17
  <div class="afwd-post-card-body">
13
- <PostMeta post={post} />
14
- <div class="afwd-post-card-title">{post.title}</div>
18
+ <h2 class="afwd-post-card-title">{post.title}</h2>
15
19
  {post.description ? <p class="afwd-post-card-desc">{post.description}</p> : null}
20
+ <PostMeta post={post} />
16
21
  </div>
17
22
  </Link>
18
23
  );
@@ -5,13 +5,21 @@
5
5
  // <PostList posts={posts} />
6
6
  import PostCard from "./PostCard.jsx";
7
7
 
8
+ // The newest post leads as a full-width hero card and the rest follow as compact rows.
9
+ // `featured={false}` lists every post the same way.
8
10
  export default function PostList(props) {
9
11
  const posts = props.posts || [];
12
+ const featured = props.featured !== false && posts.length > 0;
13
+ const rest = featured ? posts.slice(1) : posts;
10
14
  return (
11
15
  <div class="afwd-post-list">
12
- {posts.length
13
- ? posts.map((post) => <PostCard post={post} />)
14
- : <p class="afwd-post-empty">No posts yet.</p>}
16
+ {posts.length ? null : <p class="afwd-post-empty">No posts yet.</p>}
17
+ {featured ? <PostCard post={posts[0]} featured /> : null}
18
+ {rest.length ? (
19
+ <div class="afwd-post-rows">
20
+ {rest.map((post) => <PostCard post={post} />)}
21
+ </div>
22
+ ) : null}
15
23
  </div>
16
24
  );
17
25
  }
@@ -1,8 +1,11 @@
1
1
  // A post's metadata row: date · author · reading time. Pass a post record (from
2
2
  // `@opentf/afw-docs/posts`) as `post`, or the fields directly. Missing fields are
3
- // omitted. Used in both the post banner and the index cards.
3
+ // omitted. Used in both the post banner and the index cards. `showUpdated` (the banner)
4
+ // adds the frontmatter `updated` date when it is a later day than `date`. A draft or
5
+ // scheduled post, listed only by the dev server, is marked as such.
4
6
  import ReadingTime from "./ReadingTime.jsx";
5
7
  import { formatDate } from "./format.js";
8
+ import { editedAfterPublish } from "./post-dates.js";
6
9
 
7
10
  export default function PostMeta(props) {
8
11
  const post = props.post || props;
@@ -11,7 +14,7 @@ export default function PostMeta(props) {
11
14
  {post.author ? (
12
15
  <span class="afwd-post-author">
13
16
  {post.authorAvatar ? (
14
- <img class="afwd-post-avatar" src={post.authorAvatar} alt={post.author} loading="lazy" />
17
+ <img class="afwd-post-avatar" src={post.authorAvatar} alt="" loading="lazy" />
15
18
  ) : null}
16
19
  <span class="afwd-post-author-name">{post.author}</span>
17
20
  {post.authorRole ? <span class="afwd-post-author-role">{post.authorRole}</span> : null}
@@ -22,7 +25,13 @@ export default function PostMeta(props) {
22
25
  {formatDate(post.date)}
23
26
  </time>
24
27
  ) : null}
28
+ {props.showUpdated && editedAfterPublish(post.updated, post.date) ? (
29
+ <span class="afwd-post-updated">
30
+ Updated <time datetime={String(post.updated)}>{formatDate(post.updated)}</time>
31
+ </span>
32
+ ) : null}
25
33
  {post.readingTime ? <ReadingTime minutes={post.readingTime} /> : null}
34
+ {post.draft ? <span class="afwd-post-draft">Draft</span> : null}
26
35
  </div>
27
36
  );
28
37
  }
@@ -1,28 +1,53 @@
1
- // "On this page" table of contents. Built from the rendered content headings (so it
2
- // works for both MDX and JSX pages), with scroll-spy highlighting via
3
- // IntersectionObserver. Rebuilds on route change.
1
+ // "On this page" table of contents, with scroll-spy highlighting via IntersectionObserver.
2
+ // Rebuilds on route change.
4
3
  //
5
- // The MDX front-end already emits stable heading ids (slugs); we read them from the
6
- // DOM after mount. (SSG output ships the heading anchors statically; this nav chrome
7
- // activates once the client bundle mounts.)
4
+ // The outline comes from the page's `toc` export (`router.toc`, emitted by the MDX
5
+ // front-end), so it is in the served HTML and adopted at hydration: no pop-in, no layout
6
+ // shift. A page without one (plain JSX) falls back to reading its headings from the DOM
7
+ // after mount, as before.
8
8
 
9
- import { onMount, router } from "@opentf/afw";
9
+ import { isHydrating, onMount, router } from "@opentf/afw";
10
+
11
+ const sameOutline = (a, b) =>
12
+ a.length === b.length && a.every((h, i) => h.id === b[i].id && h.text === b[i].text && h.sub === b[i].sub);
10
13
 
11
14
  export default function Toc() {
12
- let items = $state([]);
15
+ const fromPage = () =>
16
+ (router.toc ?? [])
17
+ .filter((h) => h.depth === 2 || h.depth === 3)
18
+ .map((h) => ({ id: h.id, text: h.text, sub: h.depth === 3 }));
19
+
20
+ // A server-rendered `<Toc>` upgrades the moment its module defines it, which is during
21
+ // the router's route import and so before `router.toc` is set. It takes the outline the
22
+ // server rendered into it instead, so the adopt walk always sees the markup it expects.
23
+ const fromServer = () =>
24
+ Array.from(document.querySelectorAll("nav.afwd-toc .afwd-toc-link"), (a) => ({
25
+ id: decodeURIComponent((a.getAttribute("href") || "").slice(1)),
26
+ text: a.textContent || "",
27
+ sub: a.parentElement?.classList.contains("afwd-toc-sub") ?? false,
28
+ }));
29
+
30
+ let items = $state(isHydrating() && typeof document !== "undefined" ? fromServer() : fromPage());
13
31
  let activeId = $state("");
14
32
  let observer = null;
15
33
 
16
- const build = () => {
34
+ // `initial`: an outline already rendered (served, then adopted) is kept as is. Assigning
35
+ // an equal array would rebuild the list the server sent, and `router.toc` may not be set
36
+ // yet when this first runs.
37
+ const build = (initial = false) => {
17
38
  if (typeof document === "undefined") return;
18
39
  const root = document.getElementById("afw-content");
19
40
  if (!root) return;
20
41
  const hs = Array.from(root.querySelectorAll("h2[id], h3[id]"));
21
- items = hs.map((h) => ({
22
- id: h.id,
23
- text: h.textContent || "",
24
- sub: h.tagName === "H3",
25
- }));
42
+ const page = fromPage();
43
+ if (!(initial && items.length > 0)) {
44
+ const next = page.length > 0
45
+ ? page
46
+ : hs.map((h) => ({ id: h.id, text: h.textContent || "", sub: h.tagName === "H3" }));
47
+ // Only a real change replaces the list: the router publishing the same headings
48
+ // (at startup, after the served outline was adopted) must not rebuild it.
49
+ if (!sameOutline(items, next)) items = next;
50
+ }
26
51
  if (observer) observer.disconnect();
27
52
  observer = new IntersectionObserver(
28
53
  (entries) => {
@@ -34,11 +59,11 @@ export default function Toc() {
34
59
  };
35
60
 
36
61
  onMount(() => {
37
- build();
62
+ build(true);
38
63
  return () => observer && observer.disconnect();
39
64
  });
40
65
 
41
- // Rebuild when the route changes (content swaps under the same layout). Effects run at
66
+ // Rebuild when the route or its headings change (content swaps under the same layout). Effects run at
42
67
  // construction — before `onMount` — so the first run would schedule a second, redundant
43
68
  // build of the same headings: on first paint the outline was built once by `onMount` and
44
69
  // then torn down and rebuilt a frame later, a visible flicker on every docs page. Skip that
@@ -46,11 +71,13 @@ export default function Toc() {
46
71
  let routed = false;
47
72
  $effect(() => {
48
73
  router.pathname;
74
+ // A hot refresh of the page publishes its new headings without a navigation.
75
+ router.toc;
49
76
  if (!routed) {
50
77
  routed = true;
51
78
  return;
52
79
  }
53
- if (typeof requestAnimationFrame !== "undefined") requestAnimationFrame(build);
80
+ if (typeof requestAnimationFrame !== "undefined") requestAnimationFrame(() => build());
54
81
  });
55
82
 
56
83
  return (
package/index.js CHANGED
@@ -34,6 +34,7 @@ import "./components/PostCard.jsx";
34
34
  import "./components/PostBanner.jsx";
35
35
  import "./components/PostMeta.jsx";
36
36
  import "./components/ReadingTime.jsx";
37
+ import "./components/FeedLinks.jsx";
37
38
 
38
39
  export { createSearch } from "./search.js";
39
40
 
@@ -65,3 +66,4 @@ export { default as PostCard } from "./components/PostCard.jsx";
65
66
  export { default as PostBanner } from "./components/PostBanner.jsx";
66
67
  export { default as PostMeta } from "./components/PostMeta.jsx";
67
68
  export { default as ReadingTime } from "./components/ReadingTime.jsx";
69
+ export { default as FeedLinks } from "./components/FeedLinks.jsx";
package/package.json CHANGED
@@ -1,8 +1,11 @@
1
1
  {
2
2
  "name": "@opentf/afw-docs",
3
- "version": "0.30.0",
4
- "description": "Documentation-site generator for AFW — themed shell components (sidebar, TOC, callouts, tabs), a build-time nav generator, and a default light/dark theme.",
3
+ "version": "0.31.0",
4
+ "description": "Documentation and blog sites built as ordinary AFW apps.",
5
5
  "type": "module",
6
+ "scripts": {
7
+ "build": "cp ../../LICENSE LICENSE"
8
+ },
6
9
  "exports": {
7
10
  ".": {
8
11
  "types": "./types/index.d.ts",
@@ -45,33 +48,34 @@
45
48
  "!**/*.test.js"
46
49
  ],
47
50
  "keywords": [
51
+ "afw",
48
52
  "opentf",
49
53
  "documentation",
50
54
  "docs",
55
+ "blog",
51
56
  "mdx",
52
- "static-site-generator",
53
- "ssg"
57
+ "static-site-generator"
54
58
  ],
55
59
  "repository": {
56
60
  "type": "git",
57
61
  "url": "https://github.com/Open-Tech-Foundation/afw.git",
58
62
  "directory": "packages/afw-docs"
59
63
  },
60
- "homepage": "https://github.com/Open-Tech-Foundation/afw#readme",
64
+ "homepage": "https://afw.opentechf.org/packages/afw-docs",
61
65
  "bugs": "https://github.com/Open-Tech-Foundation/afw/issues",
62
66
  "license": "MIT",
63
67
  "peerDependencies": {
64
- "@opentf/afw": "0.32.0"
68
+ "@opentf/afw": "0.33.0"
65
69
  },
66
70
  "publishConfig": {
67
71
  "access": "public"
68
72
  },
69
73
  "dependencies": {
70
- "@opentf/afw-compiler": "0.20.0"
74
+ "@opentf/afw-compiler": "0.21.0"
71
75
  },
72
76
  "devDependencies": {
73
- "@opentf/afw": "0.32.0",
74
- "@opentf/afw-test": "1.27.0"
77
+ "@opentf/afw": "0.33.0",
78
+ "@opentf/afw-test": "1.28.0"
75
79
  },
76
80
  "types": "./types/index.d.ts"
77
81
  }
package/theme/index.css CHANGED
@@ -1606,6 +1606,45 @@
1606
1606
  justify-self: end;
1607
1607
  }
1608
1608
  }
1609
+ /* Subscribe links: icons at the top of the index, a line under each post. */
1610
+ .afwd-feed-links {
1611
+ display: flex;
1612
+ justify-content: flex-end;
1613
+ gap: 0.5rem;
1614
+ margin-bottom: 0.75rem;
1615
+ }
1616
+ .afwd-feed-link {
1617
+ display: inline-flex;
1618
+ align-items: center;
1619
+ gap: 0.35rem;
1620
+ padding: 0.25rem 0.6rem;
1621
+ border: 1px solid var(--afw-border);
1622
+ border-radius: 9999px;
1623
+ font-size: 0.78rem;
1624
+ font-weight: 600;
1625
+ color: var(--afw-text-muted);
1626
+ text-decoration: none;
1627
+ transition: color 0.15s, border-color 0.15s;
1628
+ }
1629
+ .afwd-feed-link:hover,
1630
+ .afwd-feed-link:focus-visible {
1631
+ color: var(--afw-accent);
1632
+ border-color: var(--afw-accent);
1633
+ }
1634
+ .afwd-feed-icon {
1635
+ flex: none;
1636
+ }
1637
+ .afwd-feed-inline {
1638
+ margin-top: 2.5rem;
1639
+ padding-top: 1rem;
1640
+ border-top: 1px solid var(--afw-border);
1641
+ font-size: 0.85rem;
1642
+ color: var(--afw-text-muted);
1643
+ }
1644
+ .afwd-feed-inline a {
1645
+ color: var(--afw-accent);
1646
+ }
1647
+
1609
1648
  .afwd-blog-back {
1610
1649
  display: inline-block;
1611
1650
  margin-bottom: 1.5rem;
@@ -1654,9 +1693,13 @@
1654
1693
  }
1655
1694
  .afwd-reading-time,
1656
1695
  .afwd-post-author,
1657
- .afwd-post-date {
1696
+ .afwd-post-date,
1697
+ .afwd-post-updated {
1658
1698
  white-space: nowrap;
1659
1699
  }
1700
+ .afwd-post-meta > .afwd-post-draft::before {
1701
+ content: none;
1702
+ }
1660
1703
 
1661
1704
  /* Tags. */
1662
1705
  .afwd-post-tags {
@@ -1675,6 +1718,16 @@
1675
1718
  color: var(--afw-text-muted);
1676
1719
  }
1677
1720
 
1721
+ .afwd-post-draft {
1722
+ padding: 0 0.5rem;
1723
+ border-radius: 9999px;
1724
+ border: 1px dashed var(--afw-border);
1725
+ font-size: 0.72rem;
1726
+ font-weight: 600;
1727
+ text-transform: uppercase;
1728
+ letter-spacing: 0.04em;
1729
+ }
1730
+
1678
1731
  /* Index listing. */
1679
1732
  .afwd-post-list {
1680
1733
  display: flex;
@@ -1691,10 +1744,11 @@
1691
1744
  color: var(--afw-accent);
1692
1745
  }
1693
1746
  .afwd-post-card .afwd-post-meta {
1694
- margin-top: 0;
1747
+ margin-top: 0.75rem;
1695
1748
  }
1696
1749
  .afwd-post-card-title {
1697
- margin-top: 0.4rem;
1750
+ margin: 0;
1751
+ line-height: 1.3;
1698
1752
  font-size: 1.35rem;
1699
1753
  font-weight: 700;
1700
1754
  color: var(--afw-text);
@@ -1746,4 +1800,44 @@
1746
1800
  border: 1px solid var(--afw-border);
1747
1801
  margin-bottom: 1rem;
1748
1802
  }
1803
+
1804
+ /* The newest post: the index's hero. */
1805
+ .afwd-post-card-featured {
1806
+ border-top: 0;
1807
+ padding-top: 0.5rem;
1808
+ }
1809
+ .afwd-post-card-featured .afwd-post-card-cover {
1810
+ margin-bottom: 1.25rem;
1811
+ }
1812
+ .afwd-post-card-featured .afwd-post-card-title {
1813
+ font-size: clamp(1.6rem, 4vw, 2.25rem);
1814
+ line-height: 1.2;
1815
+ }
1816
+ .afwd-post-card-featured .afwd-post-card-desc {
1817
+ font-size: 1.05rem;
1818
+ }
1819
+
1820
+ /* Every other post: a compact row with a thumbnail beside the text. */
1821
+ .afwd-post-rows .afwd-post-card.afwd-has-cover {
1822
+ display: grid;
1823
+ grid-template-columns: minmax(0, 1fr) 7rem;
1824
+ gap: 1rem;
1825
+ align-items: start;
1826
+ }
1827
+ .afwd-post-rows .afwd-post-card-cover {
1828
+ grid-column: 2;
1829
+ grid-row: 1;
1830
+ aspect-ratio: 16 / 10;
1831
+ margin: 0;
1832
+ }
1833
+ .afwd-post-rows .afwd-post-card-body {
1834
+ grid-column: 1;
1835
+ grid-row: 1;
1836
+ }
1837
+ @media (min-width: 640px) {
1838
+ .afwd-post-rows .afwd-post-card.afwd-has-cover {
1839
+ grid-template-columns: minmax(0, 1fr) 11rem;
1840
+ gap: 1.5rem;
1841
+ }
1842
+ }
1749
1843
  }
package/types/config.d.ts CHANGED
@@ -24,6 +24,8 @@ export interface BlogConfig {
24
24
  dir?: string;
25
25
  title?: string;
26
26
  description?: string;
27
+ /** Feed language (RSS `<language>`); defaults to `i18n.defaultLocale`, then "en". */
28
+ language?: string;
27
29
  lastUpdated?: boolean;
28
30
  }
29
31
  export interface SiteConfig {
package/types/index.d.ts CHANGED
@@ -21,6 +21,8 @@ export interface BlogLayoutProps extends ChildrenProps {
21
21
  frame?: boolean;
22
22
  indexPath?: string;
23
23
  siteUrl?: string;
24
+ /** Show RSS/Atom subscribe links on the index and under each post (default true). */
25
+ feeds?: boolean;
24
26
  }
25
27
  export interface NavbarProps {
26
28
  config?: DocsConfig;
@@ -64,3 +66,5 @@ export function PostCard(props: { post: BlogPost }): Node;
64
66
  export function PostBanner(props: { post: BlogPost } | Partial<BlogPost>): Node;
65
67
  export function PostMeta(props: { post: BlogPost } | Partial<BlogPost>): Node;
66
68
  export function ReadingTime(props: { minutes?: number }): Node;
69
+ /** RSS and Atom subscribe links for the feeds under `base` (default "/blog"). */
70
+ export function FeedLinks(props: { base?: string; variant?: "icons" | "inline" }): Node;