@forwardimpact/libdoc 0.2.0 → 0.2.2

package/bin/fit-doc.js

@@ -22,11 +22,11 @@ Options:
   -h, --help     Show this help message
 
 Build options:
-  --src=<dir>    Source directory (default: docs)
+  --src=<dir>    Source directory (default: website)
   --out=<dir>    Output directory (default: dist)
 
 Serve options:
-  --src=<dir>    Source directory (default: docs)
+  --src=<dir>    Source directory (default: website)
   --out=<dir>    Output directory (default: dist)
   -p, --port     Port to serve on (default: 3000)
   -w, --watch    Watch for changes and rebuild
@@ -93,7 +93,7 @@ async function main() {
   const { values } = parseArgs({
     args: commandArgs,
     options: {
-      src: { type: "string", default: "docs" },
+      src: { type: "string", default: "website" },
       out: { type: "string", default: "dist" },
       port: { type: "string", short: "p", default: "3000" },
       watch: { type: "boolean", short: "w", default: false },

package/builder.js

@@ -55,6 +55,33 @@ export class DocsBuilder {
     );
   }
 
+  /**
+   * Transform .md links to match the HTML output structure
+   * - index.md → ./
+   * - file.md → file/
+   * - dir/index.md → dir/
+   * - dir/file.md → dir/file/
+   * @param {string} html - HTML content to transform
+   * @returns {string} HTML with transformed links
+   */
+  #transformMarkdownLinks(html) {
+    return html.replace(
+      /href="([^"]*?)\.md(#[^"]*)?"/g,
+      (_match, path, hash) => {
+        const fragment = hash || "";
+        // Handle index.md links
+        if (path === "index" || path === "./index") {
+          return `href="./${fragment}"`;
+        }
+        if (path.endsWith("/index")) {
+          return `href="${path.slice(0, -5)}${fragment}"`;
+        }
+        // Non-index files become directories
+        return `href="${path}/${fragment}"`;
+      },
+    );
+  }
+
   /**
    * Generate table of contents from h2 headings
    * @param {string} html - HTML content to extract headings from
@@ -122,6 +149,46 @@ export class DocsBuilder {
       });
   }
 
+  /**
+   * Compute URL path from a markdown file's relative path
+   * @param {string} mdFile - Relative path to markdown file
+   * @returns {string} URL path (e.g. "/docs/pathway/")
+   */
+  #urlPathFromMdFile(mdFile) {
+    const baseName = mdFile.replace(".md", "");
+    const isIndex = baseName === "index" || baseName.endsWith("/index");
+    if (isIndex) {
+      return baseName === "index"
+        ? "/"
+        : "/" + baseName.replace(/\/index$/, "") + "/";
+    }
+    return "/" + baseName + "/";
+  }
+
+  /**
+   * Build breadcrumb HTML for pages two or more levels deep
+   * @param {string} urlPath - URL path of the current page
+   * @param {Map<string, string>} pageTitles - Map of URL paths to page titles
+   * @returns {string} Breadcrumb HTML or empty string
+   */
+  #buildBreadcrumbs(urlPath, pageTitles) {
+    const segments = urlPath.split("/").filter(Boolean);
+    if (segments.length < 2) return "";
+
+    const parts = [];
+    for (let i = 0; i < segments.length - 1; i++) {
+      const ancestorPath = "/" + segments.slice(0, i + 1).join("/") + "/";
+      const title = pageTitles.get(ancestorPath) || segments[i];
+      parts.push(`<a href="${ancestorPath}">${title}</a>`);
+    }
+
+    const currentTitle =
+      pageTitles.get(urlPath) || segments[segments.length - 1];
+    parts.push(`<span>${currentTitle}</span>`);
+
+    return parts.join(" / ");
+  }
+
   /**
    * Recursively find all Markdown files in a directory
    * @param {string} dir - Directory to search
@@ -134,6 +201,7 @@ export class DocsBuilder {
 
     for (const entryName of entries) {
       if (["assets", "public"].includes(entryName)) continue;
+      if (["CLAUDE.md", "SKILL.md"].includes(entryName)) continue;
       const fullPath = this.#path.join(dir, entryName);
 
       // Use statSync to check if it's a directory or file
@@ -175,7 +243,7 @@ export class DocsBuilder {
     // Read and validate template
     const templatePath = this.#path.join(docsDir, "index.template.html");
     if (!this.#fs.existsSync(templatePath)) {
-      throw new Error("index.template.html not found in docs directory");
+      throw new Error(`index.template.html not found in ${docsDir}`);
     }
     const template = this.#fs.readFileSync(templatePath, "utf-8");
 
@@ -183,7 +251,18 @@ export class DocsBuilder {
     const mdFiles = this.#findMarkdownFiles(docsDir);
 
     if (mdFiles.length === 0) {
-      console.warn("Warning: No Markdown files found in docs/");
+      console.warn(`Warning: No Markdown files found in ${docsDir}`);
+    }
+
+    // First pass: collect page titles by URL path for breadcrumbs
+    const pageTitles = new Map();
+    for (const mdFile of mdFiles) {
+      const { data } = this.#matter(
+        this.#fs.readFileSync(this.#path.join(docsDir, mdFile), "utf-8"),
+      );
+      if (data.title) {
+        pageTitles.set(this.#urlPathFromMdFile(mdFile), data.title);
+      }
     }
 
     for (const mdFile of mdFiles) {
@@ -196,10 +275,23 @@ export class DocsBuilder {
         continue;
       }
 
-      // Convert Markdown to HTML
-      const html = this.#marked(markdown);
+      // Convert Markdown to HTML and transform .md links
+      const rawHtml = this.#marked(markdown);
+      const html = this.#transformMarkdownLinks(rawHtml);
       const toc = frontMatter.toc !== false ? this.#generateToc(html) : "";
 
+      // Extract hero and layout data from front matter
+      const hero = frontMatter.hero;
+      const heroCta =
+        hero?.cta?.map((item) => ({
+          ...item,
+          btnClass: item.secondary ? "btn-secondary" : "btn-primary",
+        })) || [];
+
+      // Generate breadcrumbs for pages two or more levels deep
+      const urlPath = this.#urlPathFromMdFile(mdFile);
+      const breadcrumbs = this.#buildBreadcrumbs(urlPath, pageTitles);
+
       // Render template with context
       const outputHtml = this.#mustacheRender(template, {
         title: frontMatter.title,
@@ -207,6 +299,16 @@ export class DocsBuilder {
         content: html,
         toc,
         hasToc: !!toc,
+        layout: frontMatter.layout || "",
+        hasHero: !!hero,
+        heroImage: hero?.image || "",
+        heroAlt: hero?.alt || "",
+        heroTitle: hero?.title || frontMatter.title,
+        heroSubtitle: hero?.subtitle || frontMatter.description || "",
+        heroCta,
+        hasHeroCta: heroCta.length > 0,
+        hasBreadcrumbs: !!breadcrumbs,
+        breadcrumbs,
       });
 
       // Format HTML with prettier

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@forwardimpact/libdoc",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Documentation build and serve tools for static site generation from Markdown",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/forwardimpact/monorepo",
-    "directory": "libs/libdoc"
+    "directory": "libraries/libdoc"
   },
   "homepage": "https://www.forwardimpact.team",
   "type": "module",
@@ -39,5 +39,8 @@
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/server.js

@@ -33,7 +33,7 @@ export class DocsServer {
    * @returns {void}
    */
   watch(docsDir, distDir) {
-    console.log("Watching for changes in docs/...");
+    console.log(`Watching for changes in ${docsDir}...`);
 
     this.#watcher = this.#fs.watch(
       docsDir,

package/README.md

@@ -1,41 +0,0 @@
-# libdoc
-
-Documentation build and serve tools for the Forward Impact documentation site.
-Generates static sites from Markdown files with Mustache templating support.
-
-## Usage
-
-```javascript
-import {
-  DocsBuilder,
-  DocsServer,
-  parseFrontMatter,
-} from "@forwardimpact/libdoc";
-
-const builder = new DocsBuilder({ srcDir: "docs", outDir: "public" });
-await builder.build();
-
-const server = new DocsServer({ port: 3000 });
-await server.start();
-```
-
-## CLI
-
-```sh
-# Build documentation site
-npx fit-doc build --src=docs --out=dist
-
-# Serve documentation locally
-npx fit-doc serve --port=3000
-
-# Serve with watch mode for development
-npx fit-doc serve --watch
-```
-
-## API
-
-| Export             | Description                                  |
-| ------------------ | -------------------------------------------- |
-| `DocsBuilder`      | Build static documentation sites             |
-| `DocsServer`       | Serve documentation locally with live reload |
-| `parseFrontMatter` | Parse YAML front matter from markdown files  |