create-zudo-doc 0.1.0

package/templates/base/src/plugins/remark-admonitions.ts

@@ -0,0 +1,99 @@
+import type { Root, Node as MdastNode } from "mdast";
+import { visit, SKIP } from "unist-util-visit";
+
+/**
+ * Remark plugin that transforms container directives (`:::note`, `:::info`,
+ * etc., parsed by remark-directive) into JSX component nodes (`<Note>`,
+ * `<Info>`, etc.) that Astro MDX resolves via the `components` prop.
+ *
+ * Requires remark-directive to run before this plugin.
+ *
+ * Usage in MDX:
+ *   :::note[Custom Title]
+ *   Content here.
+ *   :::
+ *
+ *   :::note
+ *   Content without custom title.
+ *   :::
+ */
+
+/** A container directive node produced by remark-directive */
+interface ContainerDirective extends MdastNode {
+  type: "containerDirective";
+  name: string;
+  children: DirectiveChild[];
+  data?: Record<string, unknown>;
+  attributes?: MdxJsxAttribute[];
+}
+
+interface DirectiveChild {
+  type: string;
+  value?: string;
+  children?: DirectiveChild[];
+  data?: { directiveLabel?: boolean; [key: string]: unknown };
+}
+
+interface MdxJsxAttribute {
+  type: "mdxJsxAttribute";
+  name: string;
+  value: string;
+}
+
+const ADMONITION_TYPES = new Set(["note", "tip", "info", "warning", "danger"]);
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/** Recursively extract plain text from an mdast node tree. */
+function extractText(node: DirectiveChild): string {
+  if (typeof node.value === "string") return node.value;
+  if (Array.isArray(node.children)) {
+    return node.children.map(extractText).join("");
+  }
+  return "";
+}
+
+export function remarkAdmonitions() {
+  return (tree: Root) => {
+    visit(tree, (node: MdastNode) => {
+      if (
+        node.type === "containerDirective" &&
+        "name" in node &&
+        ADMONITION_TYPES.has((node as ContainerDirective).name)
+      ) {
+        const directive = node as ContainerDirective;
+        const componentName = capitalize(directive.name);
+
+        // Extract title from the directive label
+        const label = directive.children?.[0];
+        const isLabel = label?.data?.directiveLabel === true;
+        const title = isLabel ? extractText(label) : "";
+
+        // Build JSX attributes
+        const attributes: MdxJsxAttribute[] = [];
+        if (title) {
+          attributes.push({
+            type: "mdxJsxAttribute",
+            name: "title",
+            value: title,
+          });
+        }
+
+        // Replace the node in-place with an mdxJsxFlowElement
+        (directive as unknown as Record<string, unknown>).type = "mdxJsxFlowElement";
+        (directive as unknown as Record<string, unknown>).name = componentName;
+        directive.attributes = attributes;
+        delete directive.data;
+
+        // Remove the label paragraph from children if consumed as title
+        if (isLabel) {
+          directive.children = directive.children.slice(1);
+        }
+
+        return SKIP;
+      }
+    });
+  };
+}

package/templates/base/src/plugins/remark-resolve-markdown-links.ts

@@ -0,0 +1,127 @@
+import type { Root, Link, Definition, Node } from "mdast";
+import { visit } from "unist-util-visit";
+import { resolve, dirname } from "node:path";
+import { buildDocsSourceMap, type DocsSourceMapOptions } from "./docs-source-map";
+import { isExternal } from "./url-utils";
+
+export interface ResolveMarkdownLinksOptions extends DocsSourceMapOptions {
+  /** Behavior on broken links: 'warn' (default), 'error', 'ignore' */
+  onBrokenLinks?: "warn" | "error" | "ignore";
+}
+
+/** Check if pathname has a markdown (.md / .mdx) extension. */
+function hasMarkdownExtension(pathname: string): boolean {
+  return /\.mdx?$/.test(pathname);
+}
+
+/** Parse a URL into pathname, search, and hash parts */
+function parseUrl(url: string): {
+  pathname: string;
+  search: string;
+  hash: string;
+} {
+  const hashIdx = url.indexOf("#");
+  const searchIdx = url.indexOf("?");
+
+  let pathname = url;
+  let search = "";
+  let hash = "";
+
+  if (hashIdx >= 0) {
+    hash = url.slice(hashIdx);
+    pathname = url.slice(0, hashIdx);
+  }
+  if (searchIdx >= 0 && (hashIdx < 0 || searchIdx < hashIdx)) {
+    search = hash ? url.slice(searchIdx, hashIdx) : url.slice(searchIdx);
+    pathname = url.slice(0, searchIdx);
+  }
+
+  return { pathname, search, hash };
+}
+
+/**
+ * Build candidate source-file paths for an extensionless URL.
+ * Tries ".mdx" / ".md" suffixes first, then index pages for
+ * directory-style links such as "./guide/".
+ */
+function extensionlessCandidates(basePath: string): string[] {
+  return [
+    `${basePath}.mdx`,
+    `${basePath}.md`,
+    `${basePath}/index.mdx`,
+    `${basePath}/index.md`,
+  ];
+}
+
+export function remarkResolveMarkdownLinks(
+  options: ResolveMarkdownLinksOptions,
+) {
+  const onBrokenLinks = options.onBrokenLinks ?? "warn";
+
+  return (tree: Root, file: { path?: string }) => {
+    // Rebuild source map on every call so new/removed files are picked up
+    // during dev server. The filesystem scan is fast (~1ms for typical doc sites).
+    const sourceMap = buildDocsSourceMap(options);
+
+    const currentFilePath = file.path;
+    if (!currentFilePath) return;
+
+    const currentDir = dirname(currentFilePath);
+
+    visit(tree, (node: Node) => {
+      if (node.type !== "link" && node.type !== "definition") return;
+      const linkNode = node as Link | Definition;
+      const url = linkNode.url;
+
+      // Skip: no URL, external URLs, pure anchors
+      if (!url || isExternal(url) || url.startsWith("#")) return;
+
+      const { pathname, search, hash } = parseUrl(url);
+
+      // Need a non-empty pathname to attempt resolution
+      if (!pathname) return;
+
+      let resolvedPath: string | null = null;
+      let extensionlessLookup = false;
+
+      if (hasMarkdownExtension(pathname)) {
+        // Explicit .md / .mdx link — existing behavior, may warn on miss.
+        resolvedPath = resolve(currentDir, pathname);
+      } else {
+        // Extensionless URL — probe likely source paths. This handles:
+        //   - "./dark-mode-strategies"   → dark-mode-strategies.mdx / .md
+        //   - "./0.1.0" (dotted slug)    → 0.1.0.mdx / .md
+        //   - "./guide/" (dir style)     → guide/index.mdx / .md
+        // If nothing matches we leave the link alone — it may legitimately
+        // point at a public asset, an absolute route, or a non-doc target.
+        extensionlessLookup = true;
+        const basePath = resolve(currentDir, pathname);
+        for (const candidate of extensionlessCandidates(basePath)) {
+          if (sourceMap.has(candidate)) {
+            resolvedPath = candidate;
+            break;
+          }
+        }
+        if (!resolvedPath) return;
+      }
+
+      const resolvedUrl = sourceMap.get(resolvedPath);
+
+      if (resolvedUrl) {
+        linkNode.url = resolvedUrl + search + hash;
+      } else if (!extensionlessLookup) {
+        // Broken link handling — only reached for explicit .md/.mdx links
+        // that did not match anything in the source map.
+        const fileRelative = file.path ?? "unknown";
+        const message = `Broken markdown link: "${url}" in ${fileRelative} (resolved to ${resolvedPath})`;
+
+        if (onBrokenLinks === "error") {
+          throw new Error(message);
+        } else if (onBrokenLinks === "warn") {
+          console.warn(`[md-plugins] WARNING: ${message}`);
+        }
+        // 'ignore' — do nothing
+      }
+    });
+  };
+}

package/templates/base/src/plugins/url-utils.ts

@@ -0,0 +1,4 @@
+/** Check if a URL is external (has a protocol scheme). */
+export function isExternal(url: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:/i.test(url);
+}