docia 0.0.1

package/README.md

@@ -0,0 +1,71 @@
+# docia
+
+SEO-first static docs generator in Bun, inspired by mdBook.
+
+## Install
+
+```bash
+bun install
+```
+
+## CLI
+
+```bash
+bun run src/cli.ts --help
+```
+
+## Documentation
+
+Project usage docs are written with `docia` itself in `docs/book`.
+
+Run the docs locally:
+
+```bash
+bun run src/cli.ts dev --config docs/docia.config.ts
+```
+
+Build docs output:
+
+```bash
+bun run src/cli.ts build --config docs/docia.config.ts
+```
+
+### Commands
+
+- `bun run src/cli.ts init`
+- `bun run src/cli.ts build`
+- `bun run src/cli.ts dev`
+- `bun run src/cli.ts serve`
+- `bun run src/cli.ts check`
+- `bun run src/cli.ts new <chapter-name>`
+
+`dev` runs an initial build, serves `dist/`, and rebuilds on file changes.
+
+## Example Project
+
+See `examples/team-handbook` for a complete docs sample.
+
+```bash
+bun run src/cli.ts build --config examples/team-handbook/docia.config.ts
+bun run src/cli.ts serve --config examples/team-handbook/docia.config.ts --build
+```
+
+## Status
+
+Foundation is in progress:
+
+- CLI command skeleton
+- Config loading and validation (`docia.config.ts`)
+- Project scaffolding via `init`
+- `SUMMARY.md` parser + chapter graph (nesting, prev/next)
+- Bun-native Markdown rendering (`Bun.markdown.html/render`)
+- Client assets bundled with `Bun.build` (JS + CSS loaders)
+- Static HTML build output with sidebar, TOC, and pagination
+- SPA-style client routing after first page load
+- Shiki build-time syntax highlighting for code blocks
+- Build-time JSX page rendering (Preact SSR, no hydration required)
+- Basic SEO output (`canonical`, meta description, JSON-LD, `robots.txt`, `llms.txt`)
+- LLM-friendly page actions (copy markdown, view markdown, open in ChatGPT/Claude)
+- Sidebar socials, "Powered by docsia", and optional GitHub edit links
+- `dev` and `serve` on `Bun.serve()`
+- `check` validations for missing files, duplicate routes/output paths, broken markdown links, and orphan markdown files

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "docia",
+  "version": "0.0.1",
+  "module": "src/cli.ts",
+  "type": "module",
+  "bin": {
+    "docia": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "docia": "bun run src/cli.ts",
+    "build": "bun run src/cli.ts build",
+    "dev": "bun run src/cli.ts dev",
+    "serve": "bun run src/cli.ts serve",
+    "check": "bun run src/cli.ts check",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.2.13",
+    "@types/react-dom": "^19.2.3"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "picocolors": "^1.1.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "shiki": "^3.22.0"
+  }
+}

package/src/book/index.ts

@@ -0,0 +1,11 @@
+export { loadSummaryGraph } from "./summary";
+
+export type {
+  SummaryBaseEntry,
+  SummaryChapterEntry,
+  SummaryEntry,
+  SummaryEntryKind,
+  SummaryGraph,
+  SummaryLinkEntry,
+  SummarySectionEntry,
+} from "./types";

package/src/book/summary.ts

@@ -0,0 +1,327 @@
+import { posix, resolve } from "node:path";
+import type { ResolvedConfig } from "../config/types";
+import { CliError } from "../errors";
+import type {
+  SummaryChapterEntry,
+  SummaryEntry,
+  SummaryGraph,
+  SummaryLinkEntry,
+  SummarySectionEntry,
+} from "./types";
+
+const MARKDOWN_PATH_PATTERN = /\.(md|markdown|mdown)$/i;
+const LIST_ITEM_PATTERN = /^(\s*)[-*+]\s+(.+)$/;
+const MARKDOWN_LINK_PATTERN = /^\[([^\]]+)\]\((.+)\)\s*$/;
+const EXTERNAL_LINK_PATTERN = /^(?:[a-zA-Z][a-zA-Z0-9+.-]*:|#|\/\/)/;
+
+interface ParsedSummaryItem {
+  depth: number;
+  line: number;
+  title: string;
+  href?: string;
+}
+
+interface EntryStackItem {
+  depth: number;
+  entry: SummaryEntry;
+}
+
+function toLeadingSpaces(input: string): string {
+  return input.replaceAll("\t", "  ");
+}
+
+function parseSummaryItems(text: string): ParsedSummaryItem[] {
+  const lines = text.split(/\r?\n/);
+  const items: ParsedSummaryItem[] = [];
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const match = LIST_ITEM_PATTERN.exec(line ?? "");
+    if (!match) {
+      continue;
+    }
+
+    const indent = toLeadingSpaces(match[1] ?? "");
+    const raw = (match[2] ?? "").trim();
+    if (raw.length === 0) {
+      continue;
+    }
+
+    const depth = Math.floor(indent.length / 2);
+    const linkMatch = MARKDOWN_LINK_PATTERN.exec(raw);
+    if (linkMatch) {
+      const title = (linkMatch[1] ?? "").trim();
+      const href = (linkMatch[2] ?? "").trim();
+
+      if (title.length === 0) {
+        throw new CliError(`Invalid SUMMARY entry at line ${index + 1}: missing title.`);
+      }
+      if (href.length === 0) {
+        throw new CliError(`Invalid SUMMARY entry at line ${index + 1}: missing href.`);
+      }
+
+      items.push({
+        depth,
+        line: index + 1,
+        title,
+        href,
+      });
+
+      continue;
+    }
+
+    items.push({
+      depth,
+      line: index + 1,
+      title: raw,
+    });
+  }
+
+  return items;
+}
+
+function normalizeSourcePath(href: string, line: number): string {
+  const trimmed = href.trim();
+  const withoutHash = trimmed.split("#", 1)[0] ?? "";
+  const withoutQuery = withoutHash.split("?", 1)[0] ?? "";
+
+  let normalized = withoutQuery.replaceAll("\\", "/").replace(/^\.?\//, "");
+  if (normalized.startsWith("/")) {
+    normalized = normalized.slice(1);
+  }
+
+  normalized = posix.normalize(normalized);
+
+  if (normalized.length === 0 || normalized === ".") {
+    throw new CliError(`Invalid SUMMARY link at line ${line}: empty file path.`);
+  }
+
+  if (normalized === ".." || normalized.startsWith("../")) {
+    throw new CliError(
+      `Invalid SUMMARY link at line ${line}: path cannot traverse outside source dir.`,
+    );
+  }
+
+  return normalized;
+}
+
+function escapeRegExp(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function stripMarkdownExtension(pathValue: string): string {
+  return pathValue.replace(MARKDOWN_PATH_PATTERN, "");
+}
+
+function trimReadmeSuffix(pathValue: string): string {
+  const readmePattern = new RegExp(`(?:^|/)${escapeRegExp("README")}$`, "i");
+  return pathValue.replace(readmePattern, "");
+}
+
+function toRoutePath(sourcePath: string, prettyUrls: boolean): string {
+  const normalized = stripMarkdownExtension(sourcePath);
+  const withoutReadme = trimReadmeSuffix(normalized);
+  const cleaned = withoutReadme.replace(/^\//, "").replace(/\/$/, "");
+
+  if (prettyUrls) {
+    if (cleaned.length === 0) {
+      return "/";
+    }
+
+    return `/${cleaned}/`;
+  }
+
+  if (cleaned.length === 0) {
+    return "/index.html";
+  }
+
+  return `/${cleaned}.html`;
+}
+
+function toOutputPath(sourcePath: string, prettyUrls: boolean): string {
+  const normalized = stripMarkdownExtension(sourcePath);
+  const withoutReadme = trimReadmeSuffix(normalized);
+  const cleaned = withoutReadme.replace(/^\//, "").replace(/\/$/, "");
+
+  if (prettyUrls) {
+    if (cleaned.length === 0) {
+      return "index.html";
+    }
+
+    return `${cleaned}/index.html`;
+  }
+
+  if (cleaned.length === 0) {
+    return "index.html";
+  }
+
+  return `${cleaned}.html`;
+}
+
+function createEntryId(prefix: string, line: number): string {
+  return `${prefix}-${line}`;
+}
+
+function isExternalLink(href: string): boolean {
+  return EXTERNAL_LINK_PATTERN.test(href.trim());
+}
+
+function isMarkdownHref(href: string): boolean {
+  const pathPart = href.split("#", 1)[0]?.split("?", 1)[0] ?? "";
+  return MARKDOWN_PATH_PATTERN.test(pathPart);
+}
+
+function flattenChapters(entries: SummaryEntry[]): SummaryChapterEntry[] {
+  const chapters: SummaryChapterEntry[] = [];
+
+  const visit = (entryList: SummaryEntry[]): void => {
+    for (const entry of entryList) {
+      if (entry.kind === "chapter") {
+        chapters.push(entry);
+      }
+
+      if (entry.children.length > 0) {
+        visit(entry.children);
+      }
+    }
+  };
+
+  visit(entries);
+  return chapters;
+}
+
+export async function loadSummaryGraph(config: ResolvedConfig): Promise<SummaryGraph> {
+  const summaryPath = resolve(config.srcDirAbsolute, "SUMMARY.md");
+  const summaryFile = Bun.file(summaryPath);
+
+  if (!(await summaryFile.exists())) {
+    throw new CliError(
+      `Could not find SUMMARY.md in source directory: ${config.srcDirAbsolute}`,
+    );
+  }
+
+  const summaryText = await summaryFile.text();
+  const items = parseSummaryItems(summaryText);
+
+  if (items.length === 0) {
+    throw new CliError(`SUMMARY.md does not include any chapter entries: ${summaryPath}`);
+  }
+
+  const rootEntries: SummaryEntry[] = [];
+  const stack: EntryStackItem[] = [];
+  const entryById = new Map<string, SummaryEntry>();
+  const chapterBySourcePath = new Map<string, SummaryChapterEntry>();
+
+  for (const item of items) {
+    while (stack.length > 0) {
+      const top = stack[stack.length - 1];
+      if (top && top.depth >= item.depth) {
+        stack.pop();
+        continue;
+      }
+
+      break;
+    }
+
+    const parent = stack[stack.length - 1]?.entry;
+    if (!parent && item.depth > 0) {
+      throw new CliError(
+        `Invalid SUMMARY nesting at line ${item.line}: indentation starts before a parent entry.`,
+      );
+    }
+
+    if (parent && item.depth > parent.depth + 1) {
+      throw new CliError(
+        `Invalid SUMMARY nesting at line ${item.line}: indentation jumps more than one level.`,
+      );
+    }
+
+    let entry: SummaryEntry;
+
+    if (item.href === undefined) {
+      const sectionEntry: SummarySectionEntry = {
+        id: createEntryId("section", item.line),
+        kind: "section",
+        title: item.title,
+        depth: item.depth,
+        line: item.line,
+        parentId: parent?.id ?? null,
+        children: [],
+      };
+      entry = sectionEntry;
+    } else if (isExternalLink(item.href) || !isMarkdownHref(item.href)) {
+      const linkEntry: SummaryLinkEntry = {
+        id: createEntryId("link", item.line),
+        kind: "link",
+        title: item.title,
+        href: item.href,
+        external: isExternalLink(item.href),
+        depth: item.depth,
+        line: item.line,
+        parentId: parent?.id ?? null,
+        children: [],
+      };
+      entry = linkEntry;
+    } else {
+      const sourcePath = normalizeSourcePath(item.href, item.line);
+      const sourceAbsolutePath = resolve(config.srcDirAbsolute, sourcePath);
+
+      if (chapterBySourcePath.has(sourcePath)) {
+        const existing = chapterBySourcePath.get(sourcePath);
+        throw new CliError(
+          `Duplicate SUMMARY chapter path \`${sourcePath}\` at line ${item.line}. First defined at line ${existing?.line}.`,
+        );
+      }
+
+      const chapterEntry: SummaryChapterEntry = {
+        id: createEntryId("chapter", item.line),
+        kind: "chapter",
+        title: item.title,
+        href: item.href,
+        sourcePath,
+        sourceAbsolutePath,
+        routePath: toRoutePath(sourcePath, config.prettyUrls),
+        outputPath: toOutputPath(sourcePath, config.prettyUrls),
+        depth: item.depth,
+        line: item.line,
+        parentId: parent?.id ?? null,
+        children: [],
+        order: -1,
+        previousChapterId: null,
+        nextChapterId: null,
+      };
+
+      chapterBySourcePath.set(sourcePath, chapterEntry);
+      entry = chapterEntry;
+    }
+
+    if (parent) {
+      parent.children.push(entry);
+    } else {
+      rootEntries.push(entry);
+    }
+
+    entryById.set(entry.id, entry);
+    stack.push({ depth: item.depth, entry });
+  }
+
+  const chapters = flattenChapters(rootEntries);
+  chapters.forEach((chapter, index) => {
+    const previous = chapters[index - 1];
+    const next = chapters[index + 1];
+
+    chapter.order = index;
+    chapter.previousChapterId = previous?.id ?? null;
+    chapter.nextChapterId = next?.id ?? null;
+  });
+
+  return {
+    summaryPath,
+    entries: rootEntries,
+    chapters,
+    chapterBySourcePath,
+    entryById,
+    firstChapterId: chapters[0]?.id ?? null,
+    lastChapterId: chapters[chapters.length - 1]?.id ?? null,
+  };
+}

package/src/book/types.ts

@@ -0,0 +1,48 @@
+export type SummaryEntryKind = "section" | "chapter" | "link";
+
+export interface SummaryBaseEntry {
+  id: string;
+  kind: SummaryEntryKind;
+  title: string;
+  depth: number;
+  line: number;
+  parentId: string | null;
+  children: SummaryEntry[];
+}
+
+export interface SummarySectionEntry extends SummaryBaseEntry {
+  kind: "section";
+}
+
+export interface SummaryLinkEntry extends SummaryBaseEntry {
+  kind: "link";
+  href: string;
+  external: boolean;
+}
+
+export interface SummaryChapterEntry extends SummaryBaseEntry {
+  kind: "chapter";
+  href: string;
+  sourcePath: string;
+  sourceAbsolutePath: string;
+  routePath: string;
+  outputPath: string;
+  order: number;
+  previousChapterId: string | null;
+  nextChapterId: string | null;
+}
+
+export type SummaryEntry =
+  | SummarySectionEntry
+  | SummaryLinkEntry
+  | SummaryChapterEntry;
+
+export interface SummaryGraph {
+  summaryPath: string;
+  entries: SummaryEntry[];
+  chapters: SummaryChapterEntry[];
+  chapterBySourcePath: Map<string, SummaryChapterEntry>;
+  entryById: Map<string, SummaryEntry>;
+  firstChapterId: string | null;
+  lastChapterId: string | null;
+}