@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 +21 -0
- package/README.md +142 -0
- package/build/blog-posts-plugin.js +21 -8
- package/build/docs-nav-plugin.js +9 -5
- package/build/feed.js +31 -2
- package/build/index.js +2 -1
- package/build/last-updated-plugin.js +14 -6
- package/build/publish.js +29 -0
- package/components/BlogLayout.jsx +24 -10
- package/components/FeedLinks.jsx +47 -0
- package/components/LastUpdated.jsx +4 -6
- package/components/Navbar.jsx +1 -1
- package/components/PostBanner.jsx +2 -2
- package/components/PostCard.jsx +10 -5
- package/components/PostList.jsx +11 -3
- package/components/PostMeta.jsx +11 -2
- package/components/Toc.jsx +44 -17
- package/index.js +2 -0
- package/package.json +13 -9
- package/theme/index.css +97 -3
- package/types/config.d.ts +2 -0
- package/types/index.d.ts +4 -0
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?,
|
|
8
|
-
// order? }`. Sorted newest-first by `date`; a numeric `order` (frontmatter)
|
|
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
|
|
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,
|
package/build/docs-nav-plugin.js
CHANGED
|
@@ -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 (!
|
|
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:
|
|
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 {
|
|
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
|
-
|
|
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("/");
|
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
|
+
}
|
|
@@ -17,29 +17,37 @@
|
|
|
17
17
|
// The layout factory re-runs on every navigation (the router rebuilds the route +
|
|
18
18
|
// layout chain), so reading `router.pathname` resolves to the page being shown.
|
|
19
19
|
import { Link, RawHtml, router } from "@opentf/afw";
|
|
20
|
-
import updated from "@opentf/afw-docs/updated";
|
|
21
20
|
|
|
22
21
|
import Navbar from "./Navbar.jsx";
|
|
23
22
|
import Footer from "./Footer.jsx";
|
|
24
23
|
import Toc from "./Toc.jsx";
|
|
25
24
|
import PostBanner from "./PostBanner.jsx";
|
|
26
|
-
import
|
|
25
|
+
import FeedLinks from "./FeedLinks.jsx";
|
|
27
26
|
import { editedAfterPublish } from "./post-dates.js";
|
|
28
27
|
|
|
29
28
|
// Structured data for crawlers: the current post as a BlogPosting, emitted in
|
|
30
29
|
// the body (JSON-LD is discovered wherever it sits). `siteUrl` (optional site
|
|
31
|
-
// origin) absolutizes the post/cover URLs. Fields the post lacks are omitted.
|
|
32
|
-
|
|
30
|
+
// origin) absolutizes the post/cover URLs. Fields the post lacks are omitted. The
|
|
31
|
+
// site (`config.title`, `config.logo`) is the publisher, as Google's article
|
|
32
|
+
// guidelines ask.
|
|
33
|
+
function blogPostingJsonLd(post, siteUrl, dateModified, config = {}) {
|
|
33
34
|
const base = (siteUrl || "").replace(/\/+$/, "");
|
|
34
35
|
const abs = (p) => (p ? base + p : undefined);
|
|
35
36
|
const article = { "@context": "https://schema.org", "@type": "BlogPosting" };
|
|
36
37
|
if (post.title) article.headline = post.title;
|
|
37
38
|
if (post.description) article.description = post.description;
|
|
38
|
-
if (post.path)
|
|
39
|
+
if (post.path) {
|
|
40
|
+
article.url = abs(post.path) || post.path;
|
|
41
|
+
article.mainEntityOfPage = { "@type": "WebPage", "@id": article.url };
|
|
42
|
+
}
|
|
39
43
|
if (post.cover) article.image = abs(post.cover) || post.cover;
|
|
40
44
|
if (post.date) article.datePublished = post.date;
|
|
41
45
|
if (dateModified) article.dateModified = dateModified;
|
|
42
46
|
if (post.author) article.author = { "@type": "Person", name: post.author };
|
|
47
|
+
if (config.title) {
|
|
48
|
+
article.publisher = { "@type": "Organization", name: config.title };
|
|
49
|
+
if (config.logo) article.publisher.logo = { "@type": "ImageObject", url: abs(config.logo) || config.logo };
|
|
50
|
+
}
|
|
43
51
|
const json = JSON.stringify(article).replace(/</g, "\\u003c");
|
|
44
52
|
return `<script type="application/ld+json">${json}</script>`;
|
|
45
53
|
}
|
|
@@ -50,9 +58,12 @@ export default function BlogLayout(props) {
|
|
|
50
58
|
const frame = props.frame !== false;
|
|
51
59
|
const indexPath = props.indexPath || "/blog";
|
|
52
60
|
const siteUrl = props.siteUrl || "";
|
|
61
|
+
// Subscribe links on the index and under each post; `feeds={false}` turns them off.
|
|
62
|
+
const feeds = props.feeds !== false;
|
|
53
63
|
|
|
54
64
|
const post = posts.find((p) => p.path === router.pathname);
|
|
55
|
-
|
|
65
|
+
// The post's own frontmatter `updated`, shown in the banner. Never git: see blog-posts-plugin.js.
|
|
66
|
+
const editedIso = post && editedAfterPublish(post.updated, post.date) ? post.updated : null;
|
|
56
67
|
|
|
57
68
|
const body = post ? (
|
|
58
69
|
<div class="afwd-blog afwd-blog-post">
|
|
@@ -65,16 +76,19 @@ export default function BlogLayout(props) {
|
|
|
65
76
|
<Link href={indexPath} class="afwd-blog-back" data-afw-search-ignore>
|
|
66
77
|
← {config.title ? `${config.title} Blog` : "Blog"}
|
|
67
78
|
</Link>
|
|
68
|
-
<PostBanner post={post} />
|
|
69
|
-
<RawHtml html={blogPostingJsonLd(post, siteUrl, editedIso || post.date)} />
|
|
79
|
+
<PostBanner post={post} showUpdated />
|
|
80
|
+
<RawHtml html={blogPostingJsonLd(post, siteUrl, editedIso || post.date, config)} />
|
|
70
81
|
<article class="afwd-prose">{props.children}</article>
|
|
71
|
-
{
|
|
82
|
+
{feeds ? <FeedLinks base={indexPath} variant="inline" /> : null}
|
|
72
83
|
</main>
|
|
73
84
|
<Toc />
|
|
74
85
|
</div>
|
|
75
86
|
) : (
|
|
76
87
|
<div class="afwd-blog afwd-blog-index">
|
|
77
|
-
<main class="afwd-blog-main">
|
|
88
|
+
<main class="afwd-blog-main">
|
|
89
|
+
{feeds ? <FeedLinks base={indexPath} /> : null}
|
|
90
|
+
{props.children}
|
|
91
|
+
</main>
|
|
78
92
|
</div>
|
|
79
93
|
);
|
|
80
94
|
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
// Subscribe links for a blog's RSS and Atom feeds (`<base>/rss.xml`, `<base>/atom.xml`,
|
|
2
|
+
// written by the release build). Plain anchors, not <Link>: a feed is a file for the
|
|
3
|
+
// browser or a reader app, not a route the client router can render.
|
|
4
|
+
//
|
|
5
|
+
// `variant="icons"` (the index) shows an icon and the format name per feed;
|
|
6
|
+
// `variant="inline"` (a post's foot) is a one-line "Subscribe: RSS · Atom".
|
|
7
|
+
|
|
8
|
+
const FEEDS = [
|
|
9
|
+
{ file: "rss.xml", label: "RSS", type: "application/rss+xml" },
|
|
10
|
+
{ file: "atom.xml", label: "Atom", type: "application/atom+xml" },
|
|
11
|
+
];
|
|
12
|
+
|
|
13
|
+
function FeedIcon() {
|
|
14
|
+
return (
|
|
15
|
+
<svg class="afwd-feed-icon" viewBox="0 0 24 24" width="14" height="14" aria-hidden="true" fill="currentColor">
|
|
16
|
+
<circle cx="5" cy="19" r="2.2" />
|
|
17
|
+
<path d="M3 10.5v3a7.5 7.5 0 0 1 7.5 7.5h3A10.5 10.5 0 0 0 3 10.5Z" />
|
|
18
|
+
<path d="M3 3.5v3A14.5 14.5 0 0 1 17.5 21h3A17.5 17.5 0 0 0 3 3.5Z" />
|
|
19
|
+
</svg>
|
|
20
|
+
);
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export default function FeedLinks(props) {
|
|
24
|
+
const base = (props.base || "/blog").replace(/\/+$/, "");
|
|
25
|
+
return props.variant === "inline" ? (
|
|
26
|
+
<p class="afwd-feed-inline">
|
|
27
|
+
Subscribe:{" "}
|
|
28
|
+
<a href={`${base}/rss.xml`} type="application/rss+xml">RSS</a>
|
|
29
|
+
{" · "}
|
|
30
|
+
<a href={`${base}/atom.xml`} type="application/atom+xml">Atom</a>
|
|
31
|
+
</p>
|
|
32
|
+
) : (
|
|
33
|
+
<nav class="afwd-feed-links" aria-label="Subscribe">
|
|
34
|
+
{FEEDS.map((feed) => (
|
|
35
|
+
<a
|
|
36
|
+
class="afwd-feed-link"
|
|
37
|
+
href={`${base}/${feed.file}`}
|
|
38
|
+
type={feed.type}
|
|
39
|
+
aria-label={`Subscribe via ${feed.label}`}
|
|
40
|
+
>
|
|
41
|
+
<FeedIcon />
|
|
42
|
+
<span>{feed.label}</span>
|
|
43
|
+
</a>
|
|
44
|
+
))}
|
|
45
|
+
</nav>
|
|
46
|
+
);
|
|
47
|
+
}
|
|
@@ -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
|
}
|
package/components/Navbar.jsx
CHANGED
|
@@ -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=
|
|
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) => (
|
package/components/PostCard.jsx
CHANGED
|
@@ -1,18 +1,23 @@
|
|
|
1
|
-
// One post in the blog index: a link to the post with its meta
|
|
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
|
|
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
|
-
|
|
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
|
-
<
|
|
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
|
);
|
package/components/PostList.jsx
CHANGED
|
@@ -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
|
-
|
|
14
|
-
|
|
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
|
}
|
package/components/PostMeta.jsx
CHANGED
|
@@ -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=
|
|
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
|
}
|
package/components/Toc.jsx
CHANGED
|
@@ -1,28 +1,53 @@
|
|
|
1
|
-
// "On this page" table of contents
|
|
2
|
-
//
|
|
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
|
|
6
|
-
//
|
|
7
|
-
//
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
|
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.
|
|
4
|
-
"description": "Documentation
|
|
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://
|
|
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.
|
|
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.
|
|
74
|
+
"@opentf/afw-compiler": "0.21.0"
|
|
71
75
|
},
|
|
72
76
|
"devDependencies": {
|
|
73
|
-
"@opentf/afw": "0.
|
|
74
|
-
"@opentf/afw-test": "1.
|
|
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
|
|
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;
|