doxla 0.2.0 → 0.3.0

package/README.md

@@ -2,6 +2,16 @@
 
 Improve documentation discoverability within repos. Doxla discovers all `.md` files in your repository, builds a beautiful docs viewer, and deploys it to GitHub Pages.
 
+## Why?
+
+Documentation is most valuable when it lives next to the code it describes — but in-repo markdown has a discoverability problem. Files get buried in directory trees, raw markdown is hard to read in editors, and preview plugins vary by IDE.
+
+Meanwhile, AI coding assistants (Claude Code, Copilot, Cursor) work with what's in the repository. Docs in Notion or Google Docs are invisible to them. In-repo markdown is context they can read and act on.
+
+Doxla bridges the gap: keep your docs as `.md` files in your repo (where both humans and AI agents can find them), and Doxla turns them into a readable, searchable site.
+
+Read the full rationale: [Why Doxla?](RATIONALE.md)
+
 ## Quick Start
 
 ### Deploy to GitHub Pages

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doxla",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Improve documentation discoverability within repos",
   "type": "module",
   "bin": {

package/src/app/src/components/DocPage.tsx

@@ -37,7 +37,7 @@ export function DocPage({ doc, theme }: DocPageProps) {
 
       <Separator className="mb-6" />
 
-      <MarkdownRenderer content={doc.content} theme={theme} />
+      <MarkdownRenderer content={doc.content} theme={theme} docPath={doc.path} />
     </div>
   );
 }

package/src/app/src/components/MarkdownRenderer.tsx

@@ -9,9 +9,33 @@ import type { Theme } from "../App";
 interface MarkdownRendererProps {
   content: string;
   theme: Theme;
+  docPath?: string;
 }
 
-export function MarkdownRenderer({ content, theme }: MarkdownRendererProps) {
+function resolveDocLink(href: string, docPath: string): string | null {
+  if (!href.match(/\.md(#.*)?$/i)) return null;
+  if (/^https?:\/\//.test(href)) return null;
+
+  const [filePart, anchor] = href.split("#");
+  const docDir = docPath.includes("/") ? docPath.replace(/\/[^/]+$/, "") : "";
+  const parts = (docDir ? `${docDir}/${filePart}` : filePart).split("/");
+
+  const resolved: string[] = [];
+  for (const part of parts) {
+    if (part === "..") resolved.pop();
+    else if (part !== ".") resolved.push(part);
+  }
+
+  const slug = resolved
+    .join("/")
+    .replace(/\.md$/i, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9/.-]/g, "-");
+
+  return `#/doc/${slug}${anchor ? `#${anchor}` : ""}`;
+}
+
+export function MarkdownRenderer({ content, theme, docPath }: MarkdownRendererProps) {
   const syntaxStyle = theme === "dark" ? oneDark : oneLight;
 
   const components: Components = useMemo(
@@ -43,8 +67,18 @@ export function MarkdownRenderer({ content, theme }: MarkdownRendererProps) {
           </SyntaxHighlighter>
         );
       },
+      a(props) {
+        const { href, children, ...rest } = props;
+        if (href && docPath) {
+          const resolved = resolveDocLink(href, docPath);
+          if (resolved) {
+            return <a href={resolved} {...rest}>{children}</a>;
+          }
+        }
+        return <a href={href} {...rest}>{children}</a>;
+      },
     }),
-    [syntaxStyle],
+    [syntaxStyle, docPath],
   );
 
   return (