@opentf/web-docs 0.2.0 → 0.4.0

package/build/blog-posts-plugin.js

@@ -43,8 +43,8 @@ export function blogPostsPlugin({ appDir, contentDir = "blog", exclude = new Set
 
 /**
  * Scan the blog content folder and return the ordered post list — the same array the
- * `blogPostsPlugin` virtual module exposes, but callable directly (used by the RSS
- * feed generator at build time). Returns `[]` when the folder is absent.
+ * `blogPostsPlugin` virtual module exposes, but callable directly (used by the feed
+ * generator at build time). Returns `[]` when the folder is absent.
  *
  * @param {Object} opts
  * @param {string} opts.appDir

package/build/feed.js

@@ -1,7 +1,7 @@
-// RSS 2.0 feed generation for the blog. A pure, build-time counterpart to the
+// RSS/Atom feed generation for the blog. Pure, build-time counterparts to the
 // sitemap: given the post list (from `loadPosts`) plus the site origin and channel
-// metadata, it renders an `rss.xml` string. The web-cli build writes it to
-// `dist/<blogDir>/rss.xml` when a base URL is configured.
+// metadata, render feed XML strings. The web-cli build writes them to
+// `dist/<blogDir>/rss.xml` and `dist/<blogDir>/atom.xml` when a base URL is configured.
 //
 // RSS 2.0 (https://www.rssboard.org/rss-specification) is the lowest-common-
 // denominator feed format: every reader supports it, and `<pubDate>` must be RFC-822.
@@ -25,6 +25,13 @@ function rfc822(date) {
   return Number.isNaN(d.getTime()) ? null : d.toUTCString();
 }
 
+/** `YYYY-MM-DD` (or any Date-parseable string) -> ISO-8601 for Atom timestamps. */
+function iso8601(date) {
+  if (!date) return null;
+  const d = new Date(date);
+  return Number.isNaN(d.getTime()) ? null : d.toISOString();
+}
+
 /**
  * Render an RSS 2.0 feed.
  *
@@ -76,3 +83,54 @@ export function renderBlogFeed({ posts = [], baseUrl, feedPath = "/blog/rss.xml"
     `</rss>\n`
   );
 }
+
+/**
+ * Render an Atom 1.0 feed.
+ *
+ * @param {Object} opts
+ * @param {Array}  opts.posts        Post list (from `loadPosts`).
+ * @param {string} opts.baseUrl      Canonical site origin (required; absolute links).
+ * @param {string} [opts.feedPath]   Path of the feed itself (for `<link rel=self>`).
+ * @param {Object} [opts.channel]    `{ title, description, link, author }`.
+ * @returns {string} The `atom.xml` document.
+ */
+export function renderAtomFeed({ posts = [], baseUrl, feedPath = "/blog/atom.xml", channel = {} } = {}) {
+  const title = channel.title || "Blog";
+  const description = channel.description || title;
+  const link = channel.link ? abs(baseUrl, channel.link) : abs(baseUrl, "/blog");
+  const self = abs(baseUrl, feedPath);
+  const updated = iso8601(posts.find((p) => p.date)?.date) || new Date().toISOString();
+  const fallbackAuthor = channel.author || title;
+
+  const entries = posts
+    .map((p) => {
+      const url = abs(baseUrl, p.path);
+      const published = iso8601(p.date);
+      const parts = [
+        `    <title>${esc(p.title)}</title>`,
+        `    <link href="${esc(url)}"/>`,
+        `    <id>${esc(url)}</id>`,
+        `    <updated>${published || updated}</updated>`,
+      ];
+      if (published) parts.push(`    <published>${published}</published>`);
+      parts.push(`    <author><name>${esc(p.author || fallbackAuthor)}</name></author>`);
+      if (p.description) parts.push(`    <summary>${esc(p.description)}</summary>`);
+      for (const tag of p.tags || []) parts.push(`    <category term="${esc(tag)}"/>`);
+      return `  <entry>\n${parts.join("\n")}\n  </entry>`;
+    })
+    .join("\n");
+
+  return (
+    `<?xml version="1.0" encoding="UTF-8"?>\n` +
+    `<feed xmlns="http://www.w3.org/2005/Atom">\n` +
+    `  <title>${esc(title)}</title>\n` +
+    `  <subtitle>${esc(description)}</subtitle>\n` +
+    `  <link href="${esc(link)}"/>\n` +
+    `  <link href="${esc(self)}" rel="self" type="application/atom+xml"/>\n` +
+    `  <id>${esc(link)}</id>\n` +
+    `  <updated>${updated}</updated>\n` +
+    `  <generator>@opentf/web-docs</generator>\n` +
+    (entries ? entries + "\n" : "") +
+    `</feed>\n`
+  );
+}

package/build/index.js

@@ -7,5 +7,6 @@
 export { docsNavPlugin } from "./docs-nav-plugin.js";
 export { blogPostsPlugin, loadPosts } from "./blog-posts-plugin.js";
 export { lastUpdatedPlugin, loadLastUpdated } from "./last-updated-plugin.js";
-export { renderBlogFeed } from "./feed.js";
+export { renderAtomFeed, renderBlogFeed } from "./feed.js";
+export { renderLlmsFullTxt, renderLlmsTxt } from "./llms.js";
 export { indexWithPagefind } from "./pagefind.js";

package/build/llms.js

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, relative, sep } from "node:path";
+
+import { readFrontmatter } from "./frontmatter.js";
+
+const PAGE_RE = /(^|[\\/])page\.(mdx|md|[jt]sx)$/;
+const MD_RE = /\.(mdx|md)$/;
+
+function abs(baseUrl, path) {
+  return baseUrl.replace(/\/+$/, "") + (path === "/" ? "/" : path);
+}
+
+function routePath(appDir, file) {
+  const rel = relative(appDir, file).split(sep).join("/");
+  if (!PAGE_RE.test(rel)) return null;
+  const dir = dirname(rel).split(sep).join("/");
+  if (dir === ".") return "/";
+  const segments = dir.split("/");
+  if (segments.some((seg) => seg.startsWith("_") || seg.startsWith(".") || seg.includes("["))) {
+    return null;
+  }
+  return "/" + segments.join("/");
+}
+
+function humanize(seg) {
+  return seg.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function titleFor(file, path) {
+  const fm = MD_RE.test(file) ? readFrontmatter(file) : {};
+  if (fm.title) return String(fm.title);
+  if (path === "/") return "Home";
+  return humanize(path.split("/").filter(Boolean).at(-1) ?? "Home");
+}
+
+function descriptionFor(file) {
+  const fm = MD_RE.test(file) ? readFrontmatter(file) : {};
+  return fm.description ? String(fm.description) : "";
+}
+
+function stripFrontmatter(source) {
+  return source.replace(/^?---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+}
+
+function stripMdxBoilerplate(source) {
+  const lines = stripFrontmatter(source).split(/\r?\n/);
+  const out = [];
+  let inFence = false;
+  for (const line of lines) {
+    if (/^```/.test(line.trim())) inFence = !inFence;
+    if (!inFence && /^\s*import\s/.test(line)) continue;
+    if (!inFence && /^\s*export\s+(const|let|var|default)\s/.test(line)) continue;
+    out.push(line);
+  }
+  return out.join("\n").trim();
+}
+
+function sectionFor(path) {
+  if (path === "/") return "Start Here";
+  if (path.startsWith("/docs")) return "Documentation";
+  if (path.startsWith("/api")) return "API Reference";
+  if (path.startsWith("/blog")) return "Blog";
+  return "Other Routes";
+}
+
+function pageRecords({ appDir, pages = [], baseUrl }) {
+  return pages
+    .filter((file) => PAGE_RE.test(file))
+    .map((file) => {
+      const path = routePath(appDir, file);
+      if (!path) return null;
+      return {
+        file,
+        path,
+        url: abs(baseUrl, path),
+        title: titleFor(file, path),
+        description: descriptionFor(file),
+        markdown: MD_RE.test(file) && existsSync(file) ? stripMdxBoilerplate(readFileSync(file, "utf8")) : "",
+      };
+    })
+    .filter(Boolean)
+    .sort((a, b) => {
+      if (a.path === "/") return -1;
+      if (b.path === "/") return 1;
+      return a.path.localeCompare(b.path);
+    });
+}
+
+function grouped(records) {
+  const out = new Map();
+  for (const record of records) {
+    const section = sectionFor(record.path);
+    if (!out.has(section)) out.set(section, []);
+    out.get(section).push(record);
+  }
+  return out;
+}
+
+const SECTION_ORDER = ["Start Here", "Documentation", "API Reference", "Blog", "Other Routes"];
+
+export function renderLlmsTxt({ appDir, pages = [], baseUrl, config = {} } = {}) {
+  const title = config?.docs?.title || "OTF Web";
+  const records = pageRecords({ appDir, pages, baseUrl });
+  const description =
+    config?.docs?.description ||
+    "Documentation, API reference, and blog content for the OTF Web framework.";
+  const lines = [
+    `# ${title}`,
+    "",
+    `> ${description}`,
+    "",
+    `This file is a curated entry point for language models. For full page content, see [llms-full.txt](${abs(baseUrl, "/llms-full.txt")}).`,
+    "",
+  ];
+
+  const groups = grouped(records);
+  for (const section of SECTION_ORDER) {
+    const items = groups.get(section);
+    if (!items?.length) continue;
+    lines.push(`## ${section}`, "");
+    for (const item of items) {
+      const note = item.description ? `: ${item.description}` : "";
+      lines.push(`- [${item.title}](${item.url})${note}`);
+    }
+    lines.push("");
+  }
+
+  if (config?.blog) {
+    lines.push("## Optional", "");
+    lines.push(`- [RSS feed](${abs(baseUrl, `/${config.blog.dir ?? "blog"}/rss.xml`)}): Blog feed in RSS 2.0 format.`);
+    lines.push(`- [Atom feed](${abs(baseUrl, `/${config.blog.dir ?? "blog"}/atom.xml`)}): Blog feed in Atom 1.0 format.`);
+  }
+  return lines.join("\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
+}
+
+export function renderLlmsFullTxt({ appDir, pages = [], baseUrl, config = {} } = {}) {
+  const title = config?.docs?.title || "OTF Web";
+  const records = pageRecords({ appDir, pages, baseUrl }).filter((record) => record.markdown);
+  const lines = [
+    `# ${title} Full Documentation`,
+    "",
+    `Generated from filesystem routes for ${baseUrl.replace(/\/+$/, "")}.`,
+    "",
+  ];
+
+  for (const record of records) {
+    lines.push(`## ${record.title}`, "");
+    lines.push(`URL: ${record.url}`);
+    if (record.description) lines.push(`Description: ${record.description}`);
+    lines.push("");
+    lines.push(record.markdown);
+    lines.push("");
+  }
+
+  return lines.join("\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
+}

package/config.js

@@ -42,15 +42,17 @@
  *                            `<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 {string} [title]        Feed title (default `"<docs.title> Blog"`).
+ * @property {string} [description]  Feed description (default the title). RSS and Atom
+ *                            feeds (`<dir>/rss.xml`, `<dir>/atom.xml`) are generated
+ *                            by `otfw build`; production docs/blog builds require
+ *                            `site.url` or `--base-url` so feed URLs are absolute.
  * @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 {{ url?: string }} [site]   Canonical site origin (required for production
+ *                              docs/blog builds unless `--base-url` is passed).
  * @property {DocsConfig} [docs]         Documentation generator config.
  * @property {BlogConfig} [blog]         Blog generator config.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentf/web-docs",
-  "version": "0.2.0",
+  "version": "0.4.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": {
@@ -52,7 +52,7 @@
     "pagefind": "^1.5.2"
   },
   "devDependencies": {
-    "@opentf/web": "0.6.0",
-    "@opentf/web-test": "1.1.0"
+    "@opentf/web": "0.8.0",
+    "@opentf/web-test": "1.3.0"
   }
 }

package/updated-virtual.js

@@ -6,4 +6,5 @@
 // each page, from git or a frontmatter override. This file is loaded only when the
 // plugin is NOT active, in which case the map is empty and the UI omits the line.
 
+export const editPaths = {};
 export default {};