afw-docs API Reference
@opentf/afw-docs is the documentation- and blog-site toolkit: a config helper, a set of themed components, build-time virtual modules, and esdev plugins. For guides, see Packages → afw-docs.
Entry points
| Import | Provides |
|---|---|
@opentf/afw-docs | Named component exports and defineDocsConfig. |
@opentf/afw-docs/config | defineDocsConfig — the typed config identity helper. |
@opentf/afw-docs/theme | The default light/dark theme stylesheet. |
@opentf/afw-docs/nav | Generated section map { "/<dir>": tree } (resolved by docsNavPlugin); DocsLayout reads it. |
@opentf/afw-docs/posts | Generated blog post list (resolved by blogPostsPlugin). |
@opentf/afw-docs/updated | Generated { route: ISO } map + editPaths (last-updated plugin). |
@opentf/afw-docs/build | Build plugins and helpers (below). |
@opentf/afw-docs/search | Browser index reader: createSearch, tokenize, excerptParts. |
defineDocsConfig(config)
Identity helper that types afw.config.js. Key fields:
| Field | Type | Notes |
|---|---|---|
site.url | string | Canonical origin — pass to the prerender helper as baseUrl for absolute metadata and feed URLs. |
docs | object | Docs generator: title, version, logo, github, repoUrl, dir, nav, footer, search, lastUpdated. |
blog | object | Blog generator: dir, title, description, lastUpdated. |
See Configuration for the full field list.
Components
Themed building blocks, all exported from @opentf/afw-docs:
| Group | Components |
|---|---|
| Layout | DocsLayout, BlogLayout, Navbar, Sidebar, Footer, Breadcrumbs, Pagination, Toc, LastUpdated |
| Content | Callout, CodeBlock, Tabs, Steps, Table, Cards, Card |
| Search | Search, SearchTrigger |
| Blog | PostList, PostCard, PostBanner, PostMeta, ReadingTime |
| Misc | ThemeToggle, NavbarLink, NavIcon |
Build (@opentf/afw-docs/build)
Register plugins explicitly in the top-level plugins array of esdev.json. The callable helpers support custom prerender/output scripts:
| Export | Purpose |
|---|---|
docsNavPlugin | Resolves @opentf/afw-docs/nav to the section map (one tree per top-level folder). |
blogPostsPlugin / loadPosts | Resolves @opentf/afw-docs/posts; loadPosts is the callable scan. |
lastUpdatedPlugin / loadLastUpdated | Resolves @opentf/afw-docs/updated (git/frontmatter dates + edit paths). |
renderBlogFeed | Renders the RSS 2.0 feed from the post list. |
renderAtomFeed | Renders the Atom 1.0 feed from the post list. |
renderLlmsTxt / renderLlmsFullTxt | Renders compact and full LLM context files from filesystem routes. |
indexWithAfwSearch({ siteDir, afwc? }) | Runs the native indexer over prerendered HTML and returns { pages }. |
Use Configuration for plugin entries. siteOutputPlugin comes from @opentf/afw-cli/ssg; it calls the indexing, feed and LLM helpers in esdev's release-only finish hook after prerendering. See Static Generation.
Browser search (@opentf/afw-docs/search)
import { createSearch, excerptParts } from "@opentf/afw-docs/search"; const search = createSearch({ base: "/_search/" }); const { results, total } = await search.query("routing", { limit: 10 });
results contains cards with url, title, section, excerpt and highlights. URLs include the matched section anchor when available. total counts matching pages. excerptParts(result.excerpt, result.highlights) returns { text, match } segments for rendering text and <mark> without inserting raw HTML. Pass an AbortSignal as signal to cancel a query.
The index is generated during the release build; the reader loads it in the browser and caches index fragments. It does not need a search server.