@dogsbay/format-astro 0.2.0-beta.153 → 0.2.0-beta.155

package/dist/llms-txt.d.ts

@@ -24,6 +24,12 @@ export interface BuildLlmsTxtOptions {
      * the host root.
      */
     hrefPrefix?: string;
+    /**
+     * The home page's Markdown copy, when the host knows it (format-astro's project: `<prefix>.md`
+     * beside a `site.basePath` mount, `<prefix>/index.md` under a base from `site.url`'s path, where
+     * Astro serves only below the base). Default: `<prefix>.md`, `/index.md` at the host root.
+     */
+    indexMirrorHref?: string;
     /**
      * When the site has a siteUrl, emitted entry URLs become absolute
      * (e.g. `https://example.com/docs/x.md`). When omitted, URLs stay

package/dist/llms-txt.js

@@ -77,7 +77,7 @@ function mapInputs(siteConfig, nav, pages, options) {
         const key = item.href ? hrefToSlug(item.href, hrefPrefix) : null;
         return { label: item.label, ...(key !== null ? { key } : {}), children: toNav(item.children ?? []) };
     });
-    return { pages: records, byKey, nav: toNav(nav), url: (key) => absoluteUrl(slugToHref(key, hrefPrefix), siteUrl) };
+    return { pages: records, byKey, nav: toNav(nav), url: (key) => absoluteUrl(slugToHref(key, hrefPrefix, options.indexMirrorHref), siteUrl) };
 }
 // ── Internals: page lookup + URL math ───────────────────────────
 function indexPagesBySlug(pages) {
@@ -96,10 +96,10 @@ function hrefToSlug(href, hrefPrefix) {
     let slug = href.slice(prefix.length).replace(/^\//, "").replace(/\/$/, "");
     return slug === "" ? "index" : slug;
 }
-function slugToHref(slug, hrefPrefix) {
+function slugToHref(slug, hrefPrefix, indexHref) {
     const prefix = hrefPrefix.endsWith("/") ? hrefPrefix.slice(0, -1) : hrefPrefix;
     if (slug === "" || slug === "index")
-        return indexMirrorHref(prefix);
+        return indexHref ?? indexMirrorHref(prefix);
     return `${prefix}/${slug}.md`;
 }
 /**

package/dist/project.d.ts

@@ -1,4 +1,5 @@
 import type { ExportPage, NavItem } from "@dogsbay/types";
+import { type MarkdownStyle } from "@dogsbay/format-dogsbay-md";
 import { type SiteChrome } from "@dogsbay/site-files";
 import { type VersionMenu, type ProductModel } from "@dogsbay/site-files";
 import { type BlogEmitConfig } from "./blog.js";
@@ -102,6 +103,7 @@ export interface AstroProjectOptions {
         into?: string;
         mediaOnly?: boolean;
         root?: string;
+        skip?: string[];
     }[];
     /**
      * Per-source asset directories with the URL prefix their content refs
@@ -369,6 +371,17 @@ export interface AstroProjectOptions {
      * to static `.md` files in `dist/`. Default `true`.
      */
     mdMirror?: boolean;
+    /**
+     * Where links in the Markdown copies (each `.md` and llms-full.txt) go: `html` (default), the
+     * page as the site serves it, so a person follows what an agent quotes; `md`, a page's `.md`
+     * copy (links to anything without one stay as they are). Absolute with `siteUrl`. Same key and
+     * meaning as dogsbay-ssg's `agent.mdMirrorLinks` (plans/md-mirror-links.md).
+     */
+    mdMirrorLinks?: "html" | "md";
+    /** Write llms-full.txt. Default true; off with `mdMirror: false` too (as dogsbay-ssg). */
+    llmsFull?: boolean;
+    /** How the Markdown copies are written: the site's `style:` (dogsbay.config.yml). */
+    markdownStyle?: MarkdownStyle;
     /**
      * Granularity views — emit aggregate "single-page" views alongside the
      * topic-grained pages. Additive: the topic site is unchanged; aggregates

package/dist/project.js

@@ -12,7 +12,7 @@ import { fileURLToPath } from "node:url";
 import { treeToDogsbayMd } from "@dogsbay/format-dogsbay-md";
 import { treeToAstro } from "./serialize.js";
 import { apiPageLayout } from "@dogsbay/serialize-core";
-import { missingTranslations } from "@dogsbay/site-files";
+import { missingTranslations, rewriteTreeLinks } from "@dogsbay/site-files";
 import { sanitizeTree } from "@dogsbay/render-html/sanitize";
 import { generateGlobalCss, themeCss } from "./theme-css.js";
 /**
@@ -143,8 +143,8 @@ function rewriteTreeHrefs(nodes, prefix) {
         if (node.inline) {
             rewriteInlineHrefs(node.inline, prefix);
         }
-        // Rewrite hrefs in pre-rendered HTML
-        if (node.html) {
+        // Rewrite hrefs in pre-rendered HTML; a code block's `html` is its code, shown as written
+        if (node.html && node.type !== "code" && node.type !== "math-block") {
             node.html = rewriteHtmlHrefs(node.html, prefix);
         }
         // Rewrite href in props (e.g. card, link-button)
@@ -203,7 +203,8 @@ function rewriteTreeImageSrcs(nodes, prefix) {
         if (node.inline) {
             rewriteInlineImageSrcs(node.inline, prefix);
         }
-        if (node.html) {
+        // a code block's `html` is its code, shown as written
+        if (node.html && node.type !== "code" && node.type !== "math-block") {
             node.html = rewriteHtmlImageSrcs(node.html, prefix);
         }
         if (node.children) {
@@ -1658,10 +1659,11 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             const dest = mount.into
                 ? join(outputDir, "public", mount.root ?? "_assets", mount.into)
                 : join(outputDir, "public", mount.root ?? "_assets");
+            const skipped = new Set((mount.skip ?? []).map((f) => join(mount.dir, f)));
             if (mount.mediaOnly)
-                copyMediaTree(mount.dir, dest);
+                copyMediaTree(mount.dir, dest, skipped);
             else
-                cpSync(mount.dir, dest, { recursive: true });
+                cpSync(mount.dir, dest, { recursive: true, filter: (src) => !skipped.has(src) });
         }
     }
     let generated = 0;
@@ -1682,6 +1684,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
     // combined === basePath (back-compat). For GH Pages project pages
     // and multi-mount Cloudflare, combined adds the urlBase layer.
     const hrefPrefix = combined;
+    const mirrorMd = mirrorSerializer(options, pages);
     // Route-exclusion gate. Two signals, either is enough:
     //   - frontmatter `_fragment: true` (loader-stamped — the importer
     //     knew this .md was include-only, not a navigable page)
@@ -2294,7 +2297,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             if (options.mdMirror !== false) {
                 const mdEndpointPath = join(pagesDir, section ? section : "", `${page.slug}.md.ts`);
                 mkdirSync(dirname(mdEndpointPath), { recursive: true });
-                const endpointBody = buildMdEndpoint(page, sourceRel);
+                const endpointBody = buildMdEndpoint(page, sourceRel, mirrorMd);
                 writeFileSync(mdEndpointPath, endpointBody);
                 generatedPaths.add(relative(outputDir, mdEndpointPath));
                 // Sibling-level mirror for the index page under a non-empty
@@ -3127,10 +3130,66 @@ const LLMS_TXT_EXTERNAL_RE = /^(?:https?:\/\/|mailto:|tel:|#)/i;
  * frontmatter included, body normalized. Used for both the .md
  * mirror endpoints and the body summary in llms-full.txt.
  */
-function serializePageMd(page) {
-    return treeToDogsbayMd(page.tree, {
-        frontmatter: page.frontmatter,
-    });
+/**
+ * The URL of a page's Markdown copy. The home page's is `<prefix>.md` beside a `site.basePath`
+ * mount (a sibling endpoint is written there) and `<prefix>/index.md` otherwise: under a base from
+ * `site.url`'s path Astro serves nothing outside the base, and llms.txt named `/repo.md`, a 404.
+ */
+function mirrorHref(slug, options) {
+    const prefix = combinedPrefix(options).replace(/\/$/, "");
+    if (slug === "" || slug === "index")
+        return basePathSegments(normalizeBasePath(options.basePath)).length ? `${prefix}.md` : `${prefix}/index.md`;
+    return `${prefix}/${slug}.md`;
+}
+/** A page with a route (and a `.md` copy): not a fragment, not excluded from routes, not a redirect. */
+function hasRoute(p, options) {
+    const fragment = p.fragment === true || p.frontmatter?._fragment === true;
+    return !fragment && !makeSlugExcluder(options.excludeFromRoutes)(p.slug) && !(typeof p.redirect === "string" && p.redirect.trim());
+}
+/**
+ * Writes a page's Markdown copy (its `.md`, its part of llms-full.txt) in the site's `style:`, its
+ * links as the site serves them: the tree already carries the base path (emitAstroPages), so
+ * here a link becomes absolute with `siteUrl`, and with `mdMirrorLinks: md` a page link names that
+ * page's copy. In llms-full.txt (`where: "full"`) a same-page `#x` names its page. Shared walker:
+ * `rewriteTreeLinks` (@dogsbay/site-files), as dogsbay-ssg's copies.
+ */
+function mirrorSerializer(options, pages) {
+    const prefix = combinedPrefix(options).replace(/\/$/, "");
+    const site = options.siteUrl && /^https?:\/\//i.test(options.siteUrl) ? parseSiteUrl(options.siteUrl).origin : undefined;
+    const htmlPath = (slug) => (slug === "" || slug === "index" ? `${prefix}/` : `${prefix}/${slug}`);
+    const key = (path) => path.replace(/\/index$/, "").replace(/\/+$/, "") || "/";
+    // Only pages with a route of their own have a copy: not a fragment, a slug excludeFromRoutes
+    // names, or a page that is a `redirect:` (review: `.md` links to them were 404s)
+    const bySite = new Map();
+    for (const p of pages)
+        if (hasRoute(p, options))
+            bySite.set(key(htmlPath(p.slug)), p.slug);
+    const abs = (path) => (site && path.startsWith("/") && !path.startsWith("//") ? `${site}${path}` : path);
+    return (page, where) => {
+        const link = (href) => {
+            // A same-page `#x` names its page in llms-full.txt, and in a copy too when links are absolute
+            // (dogsbay-ssg writes it so: a copy pasted elsewhere still points at the page)
+            if (href.startsWith("#"))
+                return where === "full" || site ? abs(htmlPath(page.slug)) + href : href;
+            if (!href.startsWith("/") || href.startsWith("//"))
+                return href;
+            const at = href.search(/[?#]/);
+            const path = at === -1 ? href : href.slice(0, at);
+            const rest = at === -1 ? "" : href.slice(at);
+            const slug = options.mdMirrorLinks === "md" ? bySite.get(key(path)) : undefined;
+            return abs(slug !== undefined ? mirrorHref(slug, options) : path) + rest;
+        };
+        const restore = rewriteTreeLinks(page.tree, { link, asset: (src) => abs(src) });
+        try {
+            return treeToDogsbayMd(page.tree, {
+                frontmatter: page.frontmatter,
+                ...(options.markdownStyle ?? {}),
+            });
+        }
+        finally {
+            restore();
+        }
+    };
 }
 /**
  * Build the contents of `public/robots.txt`.
@@ -3264,8 +3323,8 @@ function buildMiddlewareSource(config) {
  * markdown body is embedded as a string literal at convert time;
  * Astro prerenders the endpoint into a static `.md` file under `dist/`.
  */
-function buildMdEndpoint(page, sourceRel) {
-    const body = serializePageMd(page);
+function buildMdEndpoint(page, sourceRel, serialize) {
+    const body = serialize(page, "copy");
     return [
         "// AUTO-GENERATED by `dogsbay convert` — do not edit.",
         `// Source: ${sourceRel}`,
@@ -3315,14 +3374,27 @@ function emitLlmsTxtFiles(outputDir, siteName, options, nav, pages) {
     mkdirSync(mountDir, { recursive: true });
     writeFileSync(join(mountDir, "llms.txt"), buildLlmsTxt(siteConfig, nav, pages, {
         hrefPrefix,
+        indexMirrorHref: mirrorHref("index", options),
         aggregates: options.aggregates,
         whenToUse: options.llmsWhenToUse,
     }));
-    writeFileSync(join(mountDir, "llms-full.txt"), buildLlmsFullTxt(siteConfig, nav, pages, {
-        summary: "body",
-        serializePage: serializePageMd,
-        hrefPrefix,
-    }));
+    // llms-full.txt is every page's copy in one file: off with `llmsFull: false`, and with
+    // `mdMirror: false` (no copies), as in dogsbay-ssg
+    const full = join(mountDir, "llms-full.txt");
+    if (options.llmsFull !== false && options.mdMirror !== false) {
+        const serialize = mirrorSerializer(options, pages);
+        writeFileSync(full, 
+        // only pages with a route: the others' links never got the site's prefix, and they have no
+        // page for an agent to cite (review)
+        buildLlmsFullTxt(siteConfig, nav, pages.filter((p) => hasRoute(p, options)), {
+            summary: "body",
+            serializePage: (page) => serialize(page, "full"),
+            hrefPrefix,
+            indexMirrorHref: mirrorHref("index", options),
+        }));
+    }
+    else if (existsSync(full))
+        rmSync(full);
     // Per-section files. `deriveSectionDir` returns a host-absolute
     // path derived from nav hrefs, which since the combined-prefix
     // refactor (commit 132891e) include urlBase + basePath — NOT just
@@ -3363,7 +3435,7 @@ function emitLlmsTxtFiles(outputDir, siteName, options, nav, pages) {
         }
         const sectionPath = join(mountDir, relDir, "llms.txt");
         mkdirSync(dirname(sectionPath), { recursive: true });
-        writeFileSync(sectionPath, buildSectionLlmsTxt(siteConfig, group, pages, { hrefPrefix }));
+        writeFileSync(sectionPath, buildSectionLlmsTxt(siteConfig, group, pages, { hrefPrefix, indexMirrorHref: mirrorHref("index", options) }));
     }
 }
 /**
@@ -3592,11 +3664,13 @@ const MOUNT_MEDIA_EXTS = new Set([
     ".svg", ".ico", ".pdf", ".mp4", ".webm",
 ]);
 /** Recursively copy only media files, preserving relative structure. */
-function copyMediaTree(srcDir, destDir) {
+function copyMediaTree(srcDir, destDir, skip) {
     for (const entry of readdirSync(srcDir)) {
         const full = join(srcDir, entry);
+        if (skip?.has(full))
+            continue;
         if (statSync(full).isDirectory()) {
-            copyMediaTree(full, join(destDir, entry));
+            copyMediaTree(full, join(destDir, entry), skip);
             continue;
         }
         const dot = entry.lastIndexOf(".");

package/dist/serialize.js

@@ -276,8 +276,18 @@ function nodeToAstroBase(node, ctx) {
             });
         case "unordered-list":
             return wrapBlock("ul", "", node, childrenToAstro(node, ctx));
-        case "list-item":
-            return wrapBlock("li", "", node, leafContent(node, ctx));
+        case "list-item": {
+            // a task item: a disabled checkbox before its text, as render-html draws it
+            const c = node.props?.checked;
+            if (typeof c !== "boolean")
+                return wrapBlock("li", "", node, leafContent(node, ctx));
+            // the checkbox labelled by the item's text (axe: a form control needs a label); nested blocks after
+            const text = node.inline && node.inline.length ? leafContent({ ...node, children: undefined }, ctx) : "";
+            const rest = node.children?.length ? childrenToAstro({ ...node, inline: undefined }, ctx) : "";
+            // no text of its own: the checkbox is named "Task"
+            const lead = text ? `<label><input type="checkbox" disabled${c ? " checked" : ""} /> ${text}</label>` : `<input type="checkbox" disabled${c ? " checked" : ""} aria-label="Task" />`;
+            return wrapBlock("li", "", node, `${lead}${rest}`);
+        }
         case "blockquote":
             return wrapBlock("blockquote", "border-l-4 border-border pl-4 italic text-muted-foreground", node, childrenToAstro(node, ctx));
         // A transparent grouping wrapper: renders its children inside a plain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-astro",
-  "version": "0.2.0-beta.153",
+  "version": "0.2.0-beta.155",
   "description": "Astro format plugin for Dogsbay — export TreeNode[] to Astro component markup",
   "type": "module",
   "main": "dist/index.js",
@@ -32,13 +32,13 @@
   "license": "MIT",
   "dependencies": {
     "markdown-it": "^14.3.0",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.153",
-    "@dogsbay/render-html": "0.2.0-beta.153",
-    "@dogsbay/icons": "0.2.0-beta.153",
-    "@dogsbay/serialize-core": "0.2.0-beta.153",
-    "@dogsbay/site-files": "0.2.0-beta.153",
-    "@dogsbay/types": "0.2.0-beta.153",
-    "@dogsbay/ui": "0.2.0-beta.153"
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.155",
+    "@dogsbay/icons": "0.2.0-beta.155",
+    "@dogsbay/render-html": "0.2.0-beta.155",
+    "@dogsbay/serialize-core": "0.2.0-beta.155",
+    "@dogsbay/site-files": "0.2.0-beta.155",
+    "@dogsbay/types": "0.2.0-beta.155",
+    "@dogsbay/ui": "0.2.0-beta.155"
   },
   "repository": {
     "type": "git",