@dogsbay/format-astro 0.2.0-beta.1 → 0.2.0-beta.100

package/dist/base-path.d.ts

@@ -1,10 +1,12 @@
 /**
  * Single source of truth for the `basePath` URL prefix.
  *
- * `basePath` is the path-under-host where docs are served. By default
- * it's `/docs` (every existing dogsbay site uses this); set
- * `site.basePath: ""` in `dogsbay.config.yml` to serve at the host
- * root, or `"/handbook"` (etc.) for any other prefix.
+ * `basePath` is the path-under-host where docs are served. The default
+ * is `""` (host root, matching every other SSG); set
+ * `site.basePath: "/docs"` in `dogsbay.config.yml` for the legacy
+ * "docs nested under marketing site" shape, or `"/handbook"` (etc.)
+ * for any other prefix. See plans/default-basepath-root.md for the
+ * rationale behind the default flip in v0.3.
  *
  * Every emitter that builds URLs, file paths, or rewrites links
  * reads from `AstroProjectOptions.basePath` and runs it through
@@ -22,8 +24,18 @@
  *
  * See plans/configurable-base-path.md.
  */
-/** Default `basePath` when no override is supplied. */
-export declare const DEFAULT_BASE_PATH = "/docs";
+/**
+ * Default `basePath` when no override is supplied.
+ *
+ * Changed in v0.3 from `"/docs"` to `""` (host root) so the default
+ * matches the plurality of doc-site deployments (GH Pages project
+ * sites, `docs.acme.com` subdomains, standalone wikis) and aligns
+ * with peer SSGs (Astro, Next, MkDocs, Docusaurus). The `cli`'s
+ * `site build` emits a one-shot migration warning when this default
+ * is hit so users from the `/docs` era can opt in to either value
+ * explicitly. See plans/default-basepath-root.md.
+ */
+export declare const DEFAULT_BASE_PATH = "";
 /**
  * Normalize a user-supplied `basePath` to canonical form.
  *
@@ -33,7 +45,7 @@ export declare const DEFAULT_BASE_PATH = "/docs";
  *   non-empty prefix.
  *
  * Examples:
- * - `undefined` → `"/docs"` (default)
+ * - `undefined` → `""` (default in v0.3+; was `"/docs"` previously)
  * - `""` → `""`
  * - `"/"` → `""`
  * - `"docs"` → `"/docs"`
@@ -68,6 +80,92 @@ export declare function basePathSegments(basePath: string): string[];
  * - `joinBaseUrl("", undefined, "")` → `"/"`
  */
 export declare function joinBaseUrl(basePath: string, section: string | undefined, slug: string): string;
+/**
+ * Prepend the normalized `basePath` onto a raw config-supplied
+ * `indexPath` (e.g. `/tags` from `taxonomies.tags.indexPath`),
+ * producing the URL prefix that components use to compose hrefs.
+ *
+ * Different from `joinBaseUrl` because it preserves absolute paths
+ * with internal `/` segments and does NOT add a trailing slash —
+ * downstream consumers do `${out}/<term>/` themselves.
+ *
+ * - `withBasePath("/docs", "/tags")` → `"/docs/tags"`
+ * - `withBasePath("/docs", "tags")`  → `"/docs/tags"`
+ * - `withBasePath("",      "/tags")` → `"/tags"`
+ * - `withBasePath("/docs", "/by-type")` → `"/docs/by-type"`
+ *
+ * Used for the URL-bearing `indexPath` baked into the taxonomy data
+ * file and the `tagsIndexPath` / `taxonomyIndexPaths` Astro props,
+ * so components like `<TagList>`, `<TaxonomyIndex>`, `<TaxonomyTerm>`,
+ * and `<TypeBadge>` produce hrefs that resolve under the configured
+ * site base. Without this prefix, taxonomy navigation 404s on any
+ * site with `site.basePath` set.
+ */
+export declare function withBasePath(basePath: string, indexPath: string): string;
+/**
+ * Parse `site.url` into its origin and path-component parts. The
+ * path component (if any) becomes the **urlBase** — the prefix the
+ * host serves dist/ at, distinct from `basePath` (which is the
+ * filesystem position of content within that served space).
+ *
+ * Used by emitters that need to (a) emit Astro's `base` config
+ * (= urlBase), (b) produce absolute URLs in sitemap / canonical /
+ * llms.txt (= origin + combined prefix + slug), or (c) build the
+ * combined prefix that internal hrefs need (`combinePrefix` below).
+ *
+ * Returns `origin` undefined when `siteUrl` is missing or unparseable
+ * — the caller then degrades to relative URLs (existing behavior).
+ *
+ * - `undefined` → `{ origin: undefined, urlBase: "" }`
+ * - `"https://example.com"` → `{ origin: "https://example.com", urlBase: "" }`
+ * - `"https://example.com/"` → `{ origin: "https://example.com", urlBase: "" }`
+ * - `"https://example.com/docs"` → `{ origin: "https://example.com", urlBase: "/docs" }`
+ * - `"https://example.com/docs/"` → `{ origin: "https://example.com", urlBase: "/docs" }`
+ * - `"https://user.github.io/dogsbay-docs"` → `{ origin: "https://user.github.io", urlBase: "/dogsbay-docs" }`
+ * - `"/relative-path"` → `{ origin: undefined, urlBase: "" }` (not a full URL)
+ *
+ * See plans/astro-base-from-site-url.md.
+ */
+export declare function parseSiteUrl(siteUrl: string | undefined): {
+    origin: string | undefined;
+    urlBase: string;
+};
+/**
+ * Combine a urlBase (host subpath, from `site.url`) with a
+ * basePath (filesystem layout prefix, from `site.basePath`) into the
+ * single prefix that nav hrefs, sitemap URLs, llms.txt, and the
+ * link rewriter all need.
+ *
+ * Both inputs MUST already be normalized (output of `normalizeBasePath`
+ * or `parseSiteUrl`): empty string OR a single leading slash with no
+ * trailing slash. The output respects the same shape.
+ *
+ * - `combinePrefix("", "")` → `""`
+ * - `combinePrefix("", "/docs")` → `"/docs"`
+ * - `combinePrefix("/repo", "")` → `"/repo"`
+ * - `combinePrefix("/repo", "/docs")` → `"/repo/docs"`
+ * - `combinePrefix("/handbook", "/team-docs")` → `"/handbook/team-docs"`
+ *
+ * See plans/astro-base-from-site-url.md.
+ */
+export declare function combinePrefix(urlBase: string, basePath: string): string;
+/**
+ * One-shot resolver: given the user's `site.url` + `site.basePath`,
+ * return everything emitters need. Convenience wrapper around
+ * `parseSiteUrl` + `normalizeBasePath` + `combinePrefix` so callers
+ * only do the math once.
+ *
+ * Used at the boundary in cli/site-build and cli/site-init to compute
+ * the effective prefixes before threading them into the emit tier.
+ *
+ * See plans/astro-base-from-site-url.md.
+ */
+export declare function resolvePrefixes(siteUrl: string | undefined, basePath: string | undefined): {
+    origin: string | undefined;
+    urlBase: string;
+    basePath: string;
+    combined: string;
+};
 /**
  * Build the `currentPath` value embedded in generated `.astro` pages
  * for `getPagination` lookups. No trailing slash so it matches the
@@ -78,6 +176,16 @@ export declare function joinBaseUrl(basePath: string, section: string | undefine
  * - default basePath, empty slug → `"/docs"`
  * - empty basePath, slug "auth" → `"/auth"`
  * - empty basePath, empty slug → `"/"`
+ * - empty basePath, slug "index" → `"/"` (root home)
+ *
+ * A bare `index` slug means the directory root: `content/index.md` is
+ * deliberately loaded with slug `"index"` (so the root-home and `.md`-mirror
+ * special cases fire — see plans/dir-index-slug-nav-drop.md), but the page is
+ * served at the directory URL and its nav href drops `index` (via
+ * `fileToHref`'s `/index` strip). `currentPath` must match that nav href for
+ * `getPagination` to find the home page, so we drop a whole-slug `index` here
+ * too. Without this the home page's `currentPath` (`/base/index`) never matches
+ * its nav entry (`/base`), so prev/next silently falls back to the first item.
  */
 export declare function buildCurrentPath(basePath: string, section: string | undefined, slug: string): string;
 //# sourceMappingURL=base-path.d.ts.map

package/dist/base-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-path.d.ts","sourceRoot":"","sources":["../src/base-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAKnE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAE3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAMR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAMR"}
+{"version":3,"file":"base-path.d.ts","sourceRoot":"","sources":["../src/base-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAKnE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAE3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAMR;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG;IACzD,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB,CAiBA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMvE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B;IACD,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CASA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAMR"}

package/dist/base-path.js

@@ -1,10 +1,12 @@
 /**
  * Single source of truth for the `basePath` URL prefix.
  *
- * `basePath` is the path-under-host where docs are served. By default
- * it's `/docs` (every existing dogsbay site uses this); set
- * `site.basePath: ""` in `dogsbay.config.yml` to serve at the host
- * root, or `"/handbook"` (etc.) for any other prefix.
+ * `basePath` is the path-under-host where docs are served. The default
+ * is `""` (host root, matching every other SSG); set
+ * `site.basePath: "/docs"` in `dogsbay.config.yml` for the legacy
+ * "docs nested under marketing site" shape, or `"/handbook"` (etc.)
+ * for any other prefix. See plans/default-basepath-root.md for the
+ * rationale behind the default flip in v0.3.
  *
  * Every emitter that builds URLs, file paths, or rewrites links
  * reads from `AstroProjectOptions.basePath` and runs it through
@@ -22,8 +24,18 @@
  *
  * See plans/configurable-base-path.md.
  */
-/** Default `basePath` when no override is supplied. */
-export const DEFAULT_BASE_PATH = "/docs";
+/**
+ * Default `basePath` when no override is supplied.
+ *
+ * Changed in v0.3 from `"/docs"` to `""` (host root) so the default
+ * matches the plurality of doc-site deployments (GH Pages project
+ * sites, `docs.acme.com` subdomains, standalone wikis) and aligns
+ * with peer SSGs (Astro, Next, MkDocs, Docusaurus). The `cli`'s
+ * `site build` emits a one-shot migration warning when this default
+ * is hit so users from the `/docs` era can opt in to either value
+ * explicitly. See plans/default-basepath-root.md.
+ */
+export const DEFAULT_BASE_PATH = "";
 /**
  * Normalize a user-supplied `basePath` to canonical form.
  *
@@ -33,7 +45,7 @@ export const DEFAULT_BASE_PATH = "/docs";
  *   non-empty prefix.
  *
  * Examples:
- * - `undefined` → `"/docs"` (default)
+ * - `undefined` → `""` (default in v0.3+; was `"/docs"` previously)
  * - `""` → `""`
  * - `"/"` → `""`
  * - `"docs"` → `"/docs"`
@@ -86,6 +98,123 @@ export function joinBaseUrl(basePath, section, slug) {
         parts.push(slug);
     return parts.length === 0 ? "/" : `/${parts.join("/")}/`;
 }
+/**
+ * Prepend the normalized `basePath` onto a raw config-supplied
+ * `indexPath` (e.g. `/tags` from `taxonomies.tags.indexPath`),
+ * producing the URL prefix that components use to compose hrefs.
+ *
+ * Different from `joinBaseUrl` because it preserves absolute paths
+ * with internal `/` segments and does NOT add a trailing slash —
+ * downstream consumers do `${out}/<term>/` themselves.
+ *
+ * - `withBasePath("/docs", "/tags")` → `"/docs/tags"`
+ * - `withBasePath("/docs", "tags")`  → `"/docs/tags"`
+ * - `withBasePath("",      "/tags")` → `"/tags"`
+ * - `withBasePath("/docs", "/by-type")` → `"/docs/by-type"`
+ *
+ * Used for the URL-bearing `indexPath` baked into the taxonomy data
+ * file and the `tagsIndexPath` / `taxonomyIndexPaths` Astro props,
+ * so components like `<TagList>`, `<TaxonomyIndex>`, `<TaxonomyTerm>`,
+ * and `<TypeBadge>` produce hrefs that resolve under the configured
+ * site base. Without this prefix, taxonomy navigation 404s on any
+ * site with `site.basePath` set.
+ */
+export function withBasePath(basePath, indexPath) {
+    const cleanIndex = indexPath.startsWith("/") ? indexPath : `/${indexPath}`;
+    return basePath ? `${basePath}${cleanIndex}` : cleanIndex;
+}
+/**
+ * Parse `site.url` into its origin and path-component parts. The
+ * path component (if any) becomes the **urlBase** — the prefix the
+ * host serves dist/ at, distinct from `basePath` (which is the
+ * filesystem position of content within that served space).
+ *
+ * Used by emitters that need to (a) emit Astro's `base` config
+ * (= urlBase), (b) produce absolute URLs in sitemap / canonical /
+ * llms.txt (= origin + combined prefix + slug), or (c) build the
+ * combined prefix that internal hrefs need (`combinePrefix` below).
+ *
+ * Returns `origin` undefined when `siteUrl` is missing or unparseable
+ * — the caller then degrades to relative URLs (existing behavior).
+ *
+ * - `undefined` → `{ origin: undefined, urlBase: "" }`
+ * - `"https://example.com"` → `{ origin: "https://example.com", urlBase: "" }`
+ * - `"https://example.com/"` → `{ origin: "https://example.com", urlBase: "" }`
+ * - `"https://example.com/docs"` → `{ origin: "https://example.com", urlBase: "/docs" }`
+ * - `"https://example.com/docs/"` → `{ origin: "https://example.com", urlBase: "/docs" }`
+ * - `"https://user.github.io/dogsbay-docs"` → `{ origin: "https://user.github.io", urlBase: "/dogsbay-docs" }`
+ * - `"/relative-path"` → `{ origin: undefined, urlBase: "" }` (not a full URL)
+ *
+ * See plans/astro-base-from-site-url.md.
+ */
+export function parseSiteUrl(siteUrl) {
+    if (!siteUrl)
+        return { origin: undefined, urlBase: "" };
+    // Only accept absolute http(s) URLs as full site URLs. Anything else
+    // (relative paths, mailto:, tel:, …) yields no origin — emitters
+    // fall back to whatever they do today when site.url is missing.
+    if (!/^https?:\/\//i.test(siteUrl)) {
+        return { origin: undefined, urlBase: "" };
+    }
+    let parsed;
+    try {
+        parsed = new URL(siteUrl);
+    }
+    catch {
+        return { origin: undefined, urlBase: "" };
+    }
+    const origin = `${parsed.protocol}//${parsed.host}`;
+    const urlBase = normalizeBasePath(parsed.pathname);
+    return { origin, urlBase };
+}
+/**
+ * Combine a urlBase (host subpath, from `site.url`) with a
+ * basePath (filesystem layout prefix, from `site.basePath`) into the
+ * single prefix that nav hrefs, sitemap URLs, llms.txt, and the
+ * link rewriter all need.
+ *
+ * Both inputs MUST already be normalized (output of `normalizeBasePath`
+ * or `parseSiteUrl`): empty string OR a single leading slash with no
+ * trailing slash. The output respects the same shape.
+ *
+ * - `combinePrefix("", "")` → `""`
+ * - `combinePrefix("", "/docs")` → `"/docs"`
+ * - `combinePrefix("/repo", "")` → `"/repo"`
+ * - `combinePrefix("/repo", "/docs")` → `"/repo/docs"`
+ * - `combinePrefix("/handbook", "/team-docs")` → `"/handbook/team-docs"`
+ *
+ * See plans/astro-base-from-site-url.md.
+ */
+export function combinePrefix(urlBase, basePath) {
+    // Both already normalized — concatenation is safe; no double slashes
+    // appear because each is empty OR starts with `/` and has no trailing.
+    if (!urlBase)
+        return basePath;
+    if (!basePath)
+        return urlBase;
+    return `${urlBase}${basePath}`;
+}
+/**
+ * One-shot resolver: given the user's `site.url` + `site.basePath`,
+ * return everything emitters need. Convenience wrapper around
+ * `parseSiteUrl` + `normalizeBasePath` + `combinePrefix` so callers
+ * only do the math once.
+ *
+ * Used at the boundary in cli/site-build and cli/site-init to compute
+ * the effective prefixes before threading them into the emit tier.
+ *
+ * See plans/astro-base-from-site-url.md.
+ */
+export function resolvePrefixes(siteUrl, basePath) {
+    const { origin, urlBase } = parseSiteUrl(siteUrl);
+    const normalizedBasePath = normalizeBasePath(basePath);
+    return {
+        origin,
+        urlBase,
+        basePath: normalizedBasePath,
+        combined: combinePrefix(urlBase, normalizedBasePath),
+    };
+}
 /**
  * Build the `currentPath` value embedded in generated `.astro` pages
  * for `getPagination` lookups. No trailing slash so it matches the
@@ -96,6 +225,16 @@ export function joinBaseUrl(basePath, section, slug) {
  * - default basePath, empty slug → `"/docs"`
  * - empty basePath, slug "auth" → `"/auth"`
  * - empty basePath, empty slug → `"/"`
+ * - empty basePath, slug "index" → `"/"` (root home)
+ *
+ * A bare `index` slug means the directory root: `content/index.md` is
+ * deliberately loaded with slug `"index"` (so the root-home and `.md`-mirror
+ * special cases fire — see plans/dir-index-slug-nav-drop.md), but the page is
+ * served at the directory URL and its nav href drops `index` (via
+ * `fileToHref`'s `/index` strip). `currentPath` must match that nav href for
+ * `getPagination` to find the home page, so we drop a whole-slug `index` here
+ * too. Without this the home page's `currentPath` (`/base/index`) never matches
+ * its nav entry (`/base`), so prev/next silently falls back to the first item.
  */
 export function buildCurrentPath(basePath, section, slug) {
     const parts = [];
@@ -103,7 +242,7 @@ export function buildCurrentPath(basePath, section, slug) {
         parts.push(seg);
     if (section)
         parts.push(section);
-    if (slug)
+    if (slug && slug !== "index")
         parts.push(slug);
     return parts.length === 0 ? "/" : `/${parts.join("/")}`;
 }

package/dist/base-path.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-path.js","sourceRoot":"","sources":["../src/base-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,uDAAuD;AACvD,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAyB;IACzD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,iBAAiB,CAAC;IAClD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC9D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,OAAO,IAAI,OAAO,EAAE,CAAC;AACvB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CACzB,QAAgB,EAChB,OAA2B,EAC3B,IAAY;IAEZ,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,gBAAgB,CAAC,QAAQ,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9D,IAAI,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,IAAI,IAAI,IAAI,KAAK,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAgB,EAChB,OAA2B,EAC3B,IAAY;IAEZ,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,gBAAgB,CAAC,QAAQ,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9D,IAAI,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"base-path.js","sourceRoot":"","sources":["../src/base-path.ts"],"names":[],"mappings":"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"}

package/dist/blog.d.ts

@@ -0,0 +1,134 @@
+import type { ExportPage } from "@dogsbay/types";
+/** Resolved `blog:` config (defaults filled). */
+export interface BlogEmitConfig {
+    /**
+     * Where the reverse-chronological index lives, relative to the site.
+     * `"/"` (the default) means the site root IS the blog index — the
+     * shape a blog-only site wants.
+     */
+    indexPath: string;
+    /** Posts per index page. */
+    postsPerPage: number;
+    /** Emit an RSS feed route. Phase 4; accepted and ignored for now. */
+    rss: boolean;
+    /** Which `PageMeta` date orders the list. */
+    dateField: "created" | "updated";
+}
+/** Defaults for a `blog:` block that omits fields. */
+export declare const BLOG_DEFAULTS: BlogEmitConfig;
+/** One post in the emitted data file. */
+export interface BlogPostRef {
+    slug: string;
+    title: string;
+    url: string;
+    description?: string;
+    /** ISO date from `meta[dateField]`. Absent when the post carries none. */
+    date?: string;
+    /** Only when it differs from `date` — the layout shows it as "updated". */
+    updated?: string;
+    author?: string[];
+    tags?: string[];
+    heroImage?: string;
+    /** Whole minutes, minimum 1. */
+    readingMinutes: number;
+}
+/** `src/data/blog.json`. */
+export interface BlogData {
+    /** URL-form index path, prefixed with the COMBINED serving prefix. */
+    indexPath: string;
+    /**
+     * Filesystem-layout prefix (`site.basePath`), used to place route
+     * files under `src/pages/`. Deliberately NOT the same field as the URL
+     * prefix: Astro's `base` adds `urlBase` at request time, so baking it
+     * into file paths too would double it. Same split `taxonomy.ts` takes
+     * as `basePath` + `urlPrefix`.
+     */
+    basePath: string;
+    /**
+     * The COMBINED serving prefix (urlBase + basePath). What DocsLayout's
+     * `basePath` prop wants — it composes the llms.txt link, switcher
+     * hrefs and the alternate link from it, all of which are URLs. Kept
+     * separate from `basePath` above, which is a filesystem path.
+     */
+    urlPrefix: string;
+    /** `content.section`, when the build has one. Part of route placement. */
+    section?: string;
+    postsPerPage: number;
+    /** Newest first. */
+    posts: BlogPostRef[];
+    postCount: number;
+}
+/** Prev/next for one post, in date order. */
+export interface BlogAdjacency {
+    /** The OLDER neighbour — back along the timeline, rendered on the left. */
+    prev?: {
+        title: string;
+        href: string;
+    };
+    /** The NEWER neighbour — forward, rendered on the right. */
+    next?: {
+        title: string;
+        href: string;
+    };
+}
+/**
+ * Count words in a page's body.
+ *
+ * Deliberately crude: whitespace-split on the extracted plain text.
+ * Reading time is a reading CUE, not a measurement, and a more precise
+ * count would not change the rendered minutes.
+ */
+export declare function countWords(page: ExportPage): number;
+/** Whole minutes at {@link WORDS_PER_MINUTE}, never less than 1. */
+export declare function readingMinutes(page: ExportPage): number;
+/**
+ * Build the post list from the page set.
+ *
+ * EVERY page is a post except the one that would occupy the index
+ * route itself. A site that declares `blog:` IS a blog; there is no
+ * second "is this a post?" axis to configure, and inventing one would
+ * mean a post silently vanishing because a field was missing.
+ *
+ * Undated posts sort last, in title order, rather than being dropped —
+ * a post with no date is an authoring mistake worth SEEING, not
+ * hiding.
+ */
+export declare function buildBlogData(pages: ExportPage[], opts: {
+    basePath: string;
+    urlPrefix?: string;
+    /** `content.section`, threaded exactly as taxonomy.ts threads it. */
+    section?: string;
+    /** `excludeFromRoutes` predicate — see makeSlugExcluder. */
+    excludeSlug?: (slug: string) => boolean;
+    config: BlogEmitConfig;
+}): BlogData;
+/**
+ * Prev/next per post slug, in TIME order — `prev` older, `next` newer.
+ *
+ * The footer renders prev on the left and next on the right, so this is
+ * the direction a timeline runs: older behind you, newer ahead. It also
+ * matches how a series is read. `data.posts` is newest-first for the
+ * index listing, so the neighbours are deliberately taken the other way
+ * round from the array order.
+ *
+ * The first version had `prev` as the NEWER neighbour, reasoning that a
+ * blog archive is browsed backwards. That made the right-hand link walk
+ * a reader BACKWARDS through a series — part 1's "next" was nothing, and
+ * its left-hand link was part 2.
+ */
+export declare function blogAdjacency(data: BlogData): Map<string, BlogAdjacency>;
+/** Number of index pages at the configured page size. */
+export declare function indexPageCount(data: BlogData): number;
+/**
+ * Emit `src/data/blog.json` plus the index route(s).
+ *
+ * Page 1 lives at the index path; subsequent pages at
+ * `<indexPath>/page/<n>`. Data JSON is overwritten unconditionally —
+ * it is pure derived data — while route files respect the marker.
+ */
+export declare function emitBlogFiles(outputDir: string, data: BlogData, config: BlogEmitConfig): {
+    routes: string[];
+    skipped: string[];
+    pruned: string[];
+};
+//# sourceMappingURL=blog.d.ts.map

package/dist/blog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blog.d.ts","sourceRoot":"","sources":["../src/blog.ts"],"names":[],"mappings":"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"}