bmad-method 6.0.0-alpha.9 → 6.0.1

package/website/src/rehype-base-paths.js

@@ -0,0 +1,112 @@
+/**
+ * Rehype plugin to prepend base path to absolute URLs
+ *
+ * Transforms:
+ *   /img/foo.png → /BMAD-METHOD/img/foo.png (when base is /BMAD-METHOD/)
+ *   /llms.txt → /BMAD-METHOD/llms.txt
+ *
+ * Supported elements:
+ *   - img[src], iframe[src], video[src], source[src], audio[src]
+ *   - a[href], link[href]
+ *
+ * Only affects absolute paths (/) - relative paths and external URLs are unchanged.
+ * Does NOT process .md links (those are handled by rehype-markdown-links).
+ */
+
+import { visit } from 'unist-util-visit';
+
+/**
+ * Create a rehype plugin that prepends the base path to absolute URLs.
+ *
+ * @param {Object} options - Plugin options
+ * @param {string} options.base - The base path to prepend (e.g., '/BMAD-METHOD/')
+ * @returns {function} A HAST tree transformer
+ */
+export default function rehypeBasePaths(options = {}) {
+  const base = options.base || '/';
+
+  // Normalize base: ensure trailing slash so concatenation with path.slice(1) (no leading /)
+  // produces correct paths like /BMAD-METHOD/img/foo.png.
+  // Note: rehype-markdown-links uses the opposite convention (strips trailing slash) because
+  // it concatenates with paths that start with /.
+  const normalizedBase = base === '/' ? '/' : base.endsWith('/') ? base : base + '/';
+
+  /**
+   * Prepend base path to an absolute URL attribute if needed.
+   * Skips protocol-relative URLs (//) and paths that already include the base.
+   *
+   * @param {object} node - HAST element node
+   * @param {string} attr - Attribute name ('src' or 'href')
+   */
+  function prependBase(node, attr) {
+    const value = node.properties?.[attr];
+    if (typeof value !== 'string' || !value.startsWith('/') || value.startsWith('//')) {
+      return;
+    }
+    if (normalizedBase !== '/' && !value.startsWith(normalizedBase)) {
+      node.properties[attr] = normalizedBase + value.slice(1);
+    }
+  }
+
+  return (tree) => {
+    // Handle raw HTML blocks (inline HTML in markdown that isn't parsed into HAST elements)
+    if (normalizedBase !== '/') {
+      visit(tree, 'raw', (node) => {
+        // Replace absolute src="/..." and href="/..." attributes, skipping protocol-relative
+        // and paths that already have the base prefix
+        node.value = node.value.replace(/(?<attr>\b(?:src|href))="(?<path>\/(?!\/)[^"]*)"/g, (match, attr, pathValue) => {
+          if (pathValue.startsWith(normalizedBase)) return match;
+          return `${attr}="${normalizedBase}${pathValue.slice(1)}"`;
+        });
+      });
+    }
+
+    visit(tree, 'element', (node) => {
+      const tag = node.tagName;
+
+      // Tags with src attribute
+      if (['img', 'iframe', 'video', 'source', 'audio'].includes(tag)) {
+        prependBase(node, 'src');
+      }
+
+      // Link tags with href attribute (stylesheets, preloads, etc.)
+      if (tag === 'link') {
+        prependBase(node, 'href');
+      }
+
+      // Anchor tags need special handling - skip .md links
+      if (tag === 'a' && node.properties?.href) {
+        const href = node.properties.href;
+
+        if (typeof href !== 'string') {
+          return;
+        }
+
+        // Only transform absolute paths starting with / (but not //)
+        if (!href.startsWith('/') || href.startsWith('//')) {
+          return;
+        }
+
+        // Skip if already has the base path
+        if (normalizedBase !== '/' && href.startsWith(normalizedBase)) {
+          return;
+        }
+
+        // Skip .md links - those are handled by rehype-markdown-links
+        // Extract path portion (before ? and #)
+        const firstDelimiter = Math.min(
+          href.indexOf('?') === -1 ? Infinity : href.indexOf('?'),
+          href.indexOf('#') === -1 ? Infinity : href.indexOf('#'),
+        );
+        const pathPortion = firstDelimiter === Infinity ? href : href.substring(0, firstDelimiter);
+
+        if (pathPortion.endsWith('.md')) {
+          return; // Let rehype-markdown-links handle this
+        }
+
+        // Prepend base path
+        node.properties.href = normalizedBase + href.slice(1);
+      }
+    });
+  };
+}

package/website/src/rehype-markdown-links.js

@@ -0,0 +1,111 @@
+/**
+ * Rehype plugin to transform relative .md links into correct site URLs.
+ *
+ * Uses the source file's disk path (via vfile) to resolve the link target,
+ * then computes the output URL relative to the content root directory.
+ * This correctly handles Starlight's directory-per-page URL structure
+ * where ./sibling.md from reference/testing.md must become /reference/sibling/
+ * (not ./sibling/ which would resolve to /reference/testing/sibling/).
+ *
+ * Supports: ./sibling.md, ../other/page.md, bare.md, /docs/absolute.md
+ * Preserves: query strings, hash anchors
+ * Skips: external URLs, non-.md links
+ */
+
+import { visit } from 'unist-util-visit';
+import path from 'node:path';
+
+/**
+ * @param {Object} options
+ * @param {string} options.base - Site base path (e.g., '/BMAD-METHOD/')
+ * @param {string} [options.contentDir] - Absolute path to content root; auto-detected if omitted
+ */
+export default function rehypeMarkdownLinks(options = {}) {
+  const base = options.base || '/';
+  const normalizedBase = base === '/' ? '' : base.replace(/\/$/, '');
+
+  return (tree, file) => {
+    // The current file's absolute path on disk, set by Astro's markdown pipeline
+    const currentFilePath = file.path;
+    if (!currentFilePath) return;
+
+    // Auto-detect content root: walk up from current file to find src/content/docs
+    const contentDir = options.contentDir || detectContentDir(currentFilePath);
+    if (!contentDir) {
+      throw new Error(`[rehype-markdown-links] Could not detect content directory for: ${currentFilePath}`);
+    }
+
+    visit(tree, 'element', (node) => {
+      if (node.tagName !== 'a' || typeof node.properties?.href !== 'string') {
+        return;
+      }
+
+      const href = node.properties.href;
+
+      // Skip external links (including protocol-relative URLs like //cdn.example.com)
+      if (href.includes('://') || href.startsWith('//') || href.startsWith('mailto:') || href.startsWith('tel:')) {
+        return;
+      }
+
+      // Split href into path vs query+fragment suffix
+      const delimIdx = findFirstDelimiter(href);
+      const linkPath = delimIdx === -1 ? href : href.substring(0, delimIdx);
+      const suffix = delimIdx === -1 ? '' : href.substring(delimIdx);
+
+      // Only process .md links
+      if (!linkPath.endsWith('.md')) return;
+
+      // Resolve the target file's absolute path on disk
+      let targetPath;
+      if (linkPath.startsWith('/docs/')) {
+        // Absolute /docs/ path — resolve from content root
+        targetPath = path.join(contentDir, linkPath.slice(5)); // strip '/docs'
+      } else if (linkPath.startsWith('/')) {
+        // Other absolute paths — resolve from content root
+        targetPath = path.join(contentDir, linkPath);
+      } else {
+        // Relative path (./sibling.md, ../other.md, bare.md) — resolve from current file
+        targetPath = path.resolve(path.dirname(currentFilePath), linkPath);
+      }
+
+      // Compute the target's path relative to content root
+      const relativeToContent = path.relative(contentDir, targetPath);
+
+      // Safety: skip if target resolves outside content root
+      if (relativeToContent.startsWith('..')) return;
+
+      // Convert file path to URL: strip .md, handle index, ensure leading/trailing slashes
+      let urlPath = relativeToContent.replace(/\.md$/, '');
+
+      // index.md becomes the directory root
+      if (urlPath.endsWith('/index') || urlPath === 'index') {
+        urlPath = urlPath.slice(0, -'index'.length);
+      }
+
+      // Build absolute URL with base path, normalizing any double slashes
+      const raw = normalizedBase + '/' + urlPath.replace(/\/?$/, '/') + suffix;
+      node.properties.href = raw.replace(/\/\/+/g, '/');
+    });
+  };
+}
+
+/** Find the index of the first ? or # in a string, or -1 if neither exists. */
+export function findFirstDelimiter(str) {
+  const q = str.indexOf('?');
+  const h = str.indexOf('#');
+  if (q === -1) return h;
+  if (h === -1) return q;
+  return Math.min(q, h);
+}
+
+/** Walk up from a file path to find the content docs directory. */
+export function detectContentDir(filePath) {
+  const segments = filePath.split(path.sep);
+  // Look for src/content/docs in the path
+  for (let i = segments.length - 1; i >= 2; i--) {
+    if (segments[i - 2] === 'src' && segments[i - 1] === 'content' && segments[i] === 'docs') {
+      return segments.slice(0, i + 1).join(path.sep);
+    }
+  }
+  return null;
+}