@opentf/web-docs 0.1.0 → 0.2.0

package/components/format.js

@@ -0,0 +1,11 @@
+// Small shared formatting helpers for the docs/blog components.
+
+// `2026-06-24` (or any Date-parseable value) → `June 24, 2026`. Falls back to the raw
+// string for anything the Date constructor can't parse, so a non-ISO value still
+// renders.
+export function formatDate(value) {
+  if (!value) return "";
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) return String(value);
+  return d.toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric" });
+}

package/config.js

@@ -11,6 +11,8 @@
  * @typedef {Object} DocsNavLink
  * @property {string} label
  * @property {string} href
+ * @property {string} [icon]        NavIcon name shown before the label (e.g. "book").
+ * @property {boolean} [external]   Render as a plain target=_blank anchor (no SPA nav).
  *
  * @typedef {Object} DocsFooter
  * @property {string} [text]
@@ -18,17 +20,39 @@
  *
  * @typedef {Object} DocsConfig
  * @property {string} [title]        Site/product name shown in the navbar.
+ * @property {string} [version]      Version badge shown next to the brand (e.g. "v0.4.0").
  * @property {string} [logo]         URL of the navbar logo image.
  * @property {string} [homeUrl]      Where the navbar brand links to (default "/").
  * @property {string} [github]       GitHub URL (shown in the navbar).
- * @property {string} [dir]          Docs content folder under app/ (default "docs").
+ * @property {string} [repoUrl]      Source repository URL. When set (with `lastUpdated`),
+ *                            each docs page gets an "Edit this page" link to its file on
+ *                            GitHub (`<repoUrl>/edit/main/<path>`).
+ * @property {string} [dir]          Docs content folder under app/ (default "docs"). Any
+ *                            other top-level folder with a `DocsLayout` is its own section
+ *                            (e.g. `app/api` → `/api`) — no extra config needed.
  * @property {DocsNavLink[]} [nav]   Top-level navbar links.
  * @property {DocsFooter} [footer]   Footer content.
  * @property {{ provider?: string }} [search]  Search provider (Phase 2: "pagefind").
+ * @property {boolean} [lastUpdated] Show a "Last updated" line per docs page (from the
+ *                            file's last git commit, or a `lastUpdated` frontmatter
+ *                            override; `lastUpdated: false` in frontmatter hides a page).
+ *
+ * @typedef {Object} BlogConfig
+ * @property {string} [dir]   Blog content folder under app/ (default "blog"). Each
+ *                            `<dir>/<slug>/page.mdx` is a post; its frontmatter
+ *                            (title, description, date, author, tags) feeds the
+ *                            generated `@opentf/web-docs/posts` list.
+ * @property {string} [title]        RSS channel title (default `"<docs.title> Blog"`).
+ * @property {string} [description]  RSS channel description (default the title). The
+ *                            feed (`<dir>/rss.xml`) is generated by `otfw build` when
+ *                            `site.url` is set; a `public/<dir>/rss.xml` override wins.
+ * @property {boolean} [lastUpdated] Show a "Last updated" line on a post when it was
+ *                            edited after its publish date (from git / frontmatter).
  *
  * @typedef {Object} SiteConfig
  * @property {{ url?: string }} [site]   Canonical site origin (for SEO / sitemap).
  * @property {DocsConfig} [docs]         Documentation generator config.
+ * @property {BlogConfig} [blog]         Blog generator config.
  */
 
 /**

package/index.js

@@ -16,23 +16,50 @@ import "./components/Toc.jsx";
 import "./components/Footer.jsx";
 import "./components/Breadcrumbs.jsx";
 import "./components/Pagination.jsx";
+import "./components/LastUpdated.jsx";
 import "./components/ThemeToggle.jsx";
 import "./components/SearchTrigger.jsx";
+import "./components/Search.jsx";
 import "./components/Callout.jsx";
+import "./components/CodeBlock.jsx";
 import "./components/Tabs.jsx";
-import "./components/CodeGroup.jsx";
+import "./components/Steps.jsx";
 import "./components/Table.jsx";
+import "./components/Cards.jsx";
+import "./components/Card.jsx";
+import "./components/Tooltip.jsx";
+import "./components/BlogLayout.jsx";
+import "./components/PostList.jsx";
+import "./components/PostCard.jsx";
+import "./components/PostBanner.jsx";
+import "./components/PostMeta.jsx";
+import "./components/ReadingTime.jsx";
 
 export { default as DocsLayout } from "./components/DocsLayout.jsx";
 export { default as Navbar } from "./components/Navbar.jsx";
+export { default as NavbarLink } from "./components/NavbarLink.jsx";
+export { default as SidebarToggle } from "./components/SidebarToggle.jsx";
+export { default as NavIcon } from "./components/NavIcon.jsx";
 export { default as Sidebar } from "./components/Sidebar.jsx";
 export { default as Toc } from "./components/Toc.jsx";
 export { default as Footer } from "./components/Footer.jsx";
 export { default as Breadcrumbs } from "./components/Breadcrumbs.jsx";
 export { default as Pagination } from "./components/Pagination.jsx";
+export { default as LastUpdated } from "./components/LastUpdated.jsx";
 export { default as ThemeToggle } from "./components/ThemeToggle.jsx";
 export { default as SearchTrigger } from "./components/SearchTrigger.jsx";
+export { default as Search } from "./components/Search.jsx";
 export { default as Callout } from "./components/Callout.jsx";
+export { default as CodeBlock } from "./components/CodeBlock.jsx";
 export { default as Tabs } from "./components/Tabs.jsx";
-export { default as CodeGroup } from "./components/CodeGroup.jsx";
+export { default as Steps } from "./components/Steps.jsx";
 export { default as Table } from "./components/Table.jsx";
+export { default as Cards } from "./components/Cards.jsx";
+export { default as Card } from "./components/Card.jsx";
+export { default as Tooltip } from "./components/Tooltip.jsx";
+export { default as BlogLayout } from "./components/BlogLayout.jsx";
+export { default as PostList } from "./components/PostList.jsx";
+export { default as PostCard } from "./components/PostCard.jsx";
+export { default as PostBanner } from "./components/PostBanner.jsx";
+export { default as PostMeta } from "./components/PostMeta.jsx";
+export { default as ReadingTime } from "./components/ReadingTime.jsx";

package/nav-virtual.js

@@ -2,9 +2,11 @@
 //
 // When `docsNavPlugin` is active (the toolchain registers it whenever the project
 // has a `docs` config), it intercepts this specifier and replaces it with a
-// build-time-generated module exporting the real navigation tree. This file is only
-// loaded when the plugin is NOT active (e.g. an editor, or a non-docs build), in
-// which case the nav is simply empty.
+// build-time-generated module exporting the real navigation. This file is only loaded
+// when the plugin is NOT active (e.g. an editor, or a non-docs build).
+//
+// Shape: a section map `{ [base]: tree }` (e.g. `{ "/docs": [...], "/api": [...] }`);
+// empty here.
 
 if (typeof console !== "undefined") {
   console.warn(
@@ -13,4 +15,4 @@ if (typeof console !== "undefined") {
   );
 }
 
-export default [];
+export default {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentf/web-docs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Documentation-site generator for OTF Web — themed shell components (sidebar, TOC, callouts, tabs), a build-time nav generator, and a default light/dark theme.",
   "type": "module",
   "exports": {
@@ -8,12 +8,16 @@
     "./theme": "./theme/index.css",
     "./config": "./config.js",
     "./nav": "./nav-virtual.js",
+    "./posts": "./posts-virtual.js",
+    "./updated": "./updated-virtual.js",
     "./build": "./build/index.js"
   },
   "files": [
     "index.js",
     "config.js",
     "nav-virtual.js",
+    "posts-virtual.js",
+    "updated-virtual.js",
     "components",
     "theme",
     "build",
@@ -40,5 +44,15 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "test": "bun test --env=happy-dom"
+  },
+  "dependencies": {
+    "pagefind": "^1.5.2"
+  },
+  "devDependencies": {
+    "@opentf/web": "0.6.0",
+    "@opentf/web-test": "1.1.0"
   }
 }

package/posts-virtual.js

@@ -0,0 +1,17 @@
+// Fallback for `@opentf/web-docs/posts`.
+//
+// When `blogPostsPlugin` is active (the toolchain registers it whenever the project
+// has a `blog` config), it intercepts this specifier and replaces it with a
+// build-time-generated module exporting the post list. This file is only loaded when
+// the plugin is NOT active (e.g. an editor, or a project without a blog), in which
+// case the list is simply empty.
+
+if (typeof console !== "undefined") {
+  console.warn(
+    "[@opentf/web-docs] posts requested but blogPostsPlugin is not active — " +
+      "did you add a `blog` block to otfw.config.js? Returning an empty list.",
+  );
+}
+
+export const posts = [];
+export default posts;