@tayacrystals/lore 0.1.3 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 tayacrystals
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# Lore
+
+Zero-setup documentation static site generator.
+
+## Quick Start
+
+Run lore in your docs directory:
+
+```bash
+bunx @tayacrystals/lore
+```
+
+This builds your documentation to `./build`. To start a dev server:
+
+```bash
+bunx @tayacrystals/lore dev
+```
+
+## Documentation
+
+For full documentation, visit [https://tayacrystals.github.io/lore/](https://tayacrystals.github.io/lore/)
+
+## Features
+
+- Zero setup docs
+- MDX support with custom components
+- Versioning
+- Internationalization
+- Dark/Light mode with system preference detection
+- Full-text search

package/package.json

@@ -1,51 +1,61 @@
 {
   "name": "@tayacrystals/lore",
-  "version": "0.1.3",
+  "version": "1.0.1",
+  "description": "Simple documentation site generator with versioning and internationalization support",
   "type": "module",
+  "bin": {
+    "lore": "src/index.ts"
+  },
   "exports": {
-    ".": "./index.ts",
-    "./schema": "./schema.ts",
-    "./loaders": "./loaders.ts",
-    "./components": "./components.ts",
-    "./styles/*": "./styles/*"
+    ".": "./src/index.ts"
   },
   "files": [
-    "*.ts",
-    "*.d.ts",
-    "components/",
-    "layouts/",
-    "routes/",
-    "styles/",
-    "utils/",
-    "!**/*.test.ts"
+    "src"
+  ],
+  "scripts": {
+    "build": "bun run src/index.ts build",
+    "dev": "bun run src/index.ts dev",
+    "serve": "bun run src/index.ts serve"
+  },
+  "keywords": [
+    "documentation",
+    "static-site-generator",
+    "docs",
+    "markdown",
+    "mdx",
+    "cli"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tayacrystals/lore.git"
+  },
+  "homepage": "https://github.com/tayacrystals/lore#readme",
+  "bugs": {
+    "url": "https://github.com/tayacrystals/lore/issues"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
   },
   "peerDependencies": {
-    "astro": "^5.0.0"
+    "typescript": "^5"
   },
   "dependencies": {
-    "@astrojs/mdx": "^4.3.13",
-    "@astrojs/sitemap": "^3.7.0",
-    "@fontsource-variable/inter": "^5.2.8",
-    "@fontsource/geist-mono": "^5.2.7",
-    "@iconify-json/lucide": "^1.2.89",
-    "@tailwindcss/vite": "^4.1.18",
-    "astro-expressive-code": "^0.41.6",
-    "astro-icon": "^1.1.5",
-    "astro-pagefind": "^1.8.5",
-    "hast-util-to-html": "^9.0.5",
-    "hastscript": "^9.0.1",
-    "rehype": "^13.0.2",
-    "tailwindcss": "^4.1.18",
-    "unist-util-visit": "^5.1.0",
-    "zod": "^3.24.0"
+    "lucide": "^0.577.0",
+    "rehype-autolink-headings": "^7.1.0",
+    "rehype-slug": "^6.0.0",
+    "rehype-stringify": "^10.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "shiki": "^4.0.2",
+    "unified": "^11.0.5"
   },
-  "devDependencies": {
-    "@astrojs/check": "^0.9.6",
-    "@types/hast": "^3.0.4",
-    "typescript": "^5.9.3",
-    "vite": "6"
+  "engines": {
+    "bun": ">=1.0.0"
   }
 }

package/src/build.ts

@@ -0,0 +1,149 @@
+import { mkdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { renderMdx } from "./mdx.ts";
+import { loadConfig } from "./config.ts";
+import { buildDocTree } from "./files.ts";
+import { renderPage } from "./template.ts";
+import { detectVersions, getDefaultVersion } from "./version.ts";
+import { detectLocales, getDefaultLocale } from "./i18n.ts";
+
+async function findLogo(docsDir: string, outDir: string, baseUrl?: string): Promise<string | undefined> {
+  for (const name of ["logo.svg", "logo.png"]) {
+    const src = Bun.file(`${docsDir}/${name}`);
+    if (await src.exists()) {
+      await Bun.write(`${outDir}/${name}`, src);
+      return `${baseUrl || ''}/${name}`.replace(/\/+/g, '/');
+    }
+  }
+}
+
+export async function build(
+  docsDir: string,
+  outDir: string,
+  opts: { devMode?: boolean } = {}
+): Promise<void> {
+  console.log(`Building docs from ${docsDir} → ${outDir}`);
+
+  // Clear build directory first to avoid merging old and new artifacts
+  try {
+    await rm(outDir, { recursive: true, force: true });
+  } catch {
+    // Directory doesn't exist, which is fine
+  }
+
+  const config = await loadConfig(docsDir);
+  const logoSrc = await findLogo(docsDir, outDir, config.baseUrl);
+
+  const hasVersioning = config.versioning;
+  const hasI18n = config.internationalization;
+
+  const builds: Array<{ version?: string; locale?: string }> = [];
+
+  if (hasI18n) {
+    const locales = await detectLocales(docsDir);
+    for (const locale of locales) {
+      if (hasVersioning) {
+        const localeDir = path.join(docsDir, locale.code);
+        const versions = await detectVersions(localeDir);
+        for (const version of versions) {
+          builds.push({ locale: locale.code, version: version.name });
+        }
+      } else {
+        builds.push({ locale: locale.code });
+      }
+    }
+  } else if (hasVersioning) {
+    const versions = await detectVersions(docsDir);
+    for (const version of versions) {
+      builds.push({ version: version.name });
+    }
+  }
+
+  if (builds.length === 0) {
+    builds.push({});
+  }
+
+  let totalPages = 0;
+
+  for (const buildOpts of builds) {
+    const { pages, sidebar, versions, locales, currentVersion, currentLocale } =
+      await buildDocTree(docsDir, buildOpts);
+
+    const buildLabel = [
+      currentLocale,
+      currentVersion,
+    ].filter(Boolean).join("/") || "default";
+
+    console.log(`Building for ${buildLabel}: found ${pages.length} pages`);
+
+    for (const page of pages) {
+      const contentHtml = await renderMdx(page.content, {
+        locale: currentLocale,
+        version: currentVersion,
+      });
+
+      const html = renderPage({
+        config,
+        title: page.title,
+        description: page.description,
+        contentHtml,
+        sidebar,
+        currentUrl: page.url,
+        logoSrc,
+        devMode: opts.devMode,
+        versions,
+        locales,
+        currentVersion,
+        currentLocale,
+        translationOf: page.context.translationOf,
+        baseUrl: config.baseUrl,
+      });
+
+      const urlParts: string[] = [];
+      if (currentLocale) urlParts.push(currentLocale);
+      if (currentVersion) urlParts.push(currentVersion);
+
+      const urlSegments = page.url.split("/").filter(Boolean);
+
+      let outputPath: string;
+      if (urlSegments.length === 0) {
+        outputPath = path.join(outDir, ...urlParts, "index.html");
+      } else {
+        outputPath = path.join(outDir, ...urlParts, ...urlSegments, "index.html");
+      }
+
+      await mkdir(path.dirname(outputPath), { recursive: true });
+      await Bun.write(outputPath, html);
+      console.log(`  ${page.url} → ${path.relative(process.cwd(), outputPath)}`);
+      totalPages++;
+    }
+  }
+
+  const defaultLocale = config.internationalization
+    ? config.defaultLocale ?? "en"
+    : undefined;
+  const defaultVersion = config.versioning
+    ? config.defaultVersion ?? "latest"
+    : undefined;
+
+  const redirectPathParts: string[] = [];
+  if (defaultLocale) redirectPathParts.push(defaultLocale);
+  if (defaultVersion) redirectPathParts.push(defaultVersion);
+
+  if (redirectPathParts.length > 0 && totalPages > 0) {
+    const redirectPath = "/" + redirectPathParts.join("/") + "/";
+    const redirectHtml = `<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="refresh" content="0; url=${config.baseUrl || ''}${redirectPath}">
+  <script>window.location.href = "${config.baseUrl || ''}${redirectPath}";</script>
+</head>
+<body></body>
+</html>`;
+    const outputPath = path.join(outDir, "index.html");
+    await Bun.write(outputPath, redirectHtml);
+    console.log(`  / → ${path.relative(process.cwd(), outputPath)} (redirect to ${config.baseUrl || ''}${redirectPath})`);
+  }
+
+  console.log(`\nDone! Built ${totalPages} pages to ${outDir}`);
+}

package/src/config.ts

@@ -0,0 +1,25 @@
+import type { Config } from "./types.ts";
+
+export async function loadConfig(docsDir: string): Promise<Config> {
+  const file = Bun.file(`${docsDir}/lore.yml`);
+  if (!(await file.exists())) return {};
+  const text = await file.text();
+  return (Bun.YAML.parse(text) as Config) ?? {};
+}
+
+// WCAG AA compliant colors (≥4.5:1 contrast on white)
+const NAMED_COLORS: Record<string, string> = {
+  red: "#b91c1c",
+  orange: "#c2410c",
+  yellow: "#a16207",
+  green: "#15803d",
+  blue: "#1d4ed8",
+  purple: "#6d28d9",
+  pink: "#be185d",
+  gray: "#374151",
+};
+
+export function resolveColor(color?: string): string {
+  if (!color) return "#1d4ed8";
+  return NAMED_COLORS[color] ?? color;
+}

package/src/dev.ts

@@ -0,0 +1,112 @@
+import path from "node:path";
+import { watch } from "node:fs";
+import { stat } from "node:fs/promises";
+import { build } from "./build.ts";
+import { loadConfig } from "./config.ts";
+import { getDefaultVersion } from "./version.ts";
+import { getDefaultLocale } from "./i18n.ts";
+
+export async function dev(docsDir: string, outDir: string): Promise<void> {
+  const port = 3000;
+
+  // Load config for redirect logic
+  const config = await loadConfig(docsDir);
+
+  // Initial build
+  await build(docsDir, outDir, { devMode: true });
+
+  // SSE clients waiting for reload signals
+  const sseClients = new Set<ReadableStreamDefaultController<string>>();
+
+  function notifyReload() {
+    for (const ctrl of sseClients) {
+      try {
+        ctrl.enqueue("data: reload\n\n");
+      } catch {
+        sseClients.delete(ctrl);
+      }
+    }
+  }
+
+  // Watch docs dir and rebuild on changes
+  let rebuildTimer: ReturnType<typeof setTimeout> | null = null;
+  watch(docsDir, { recursive: true }, (_event, filename) => {
+    if (rebuildTimer) clearTimeout(rebuildTimer);
+    rebuildTimer = setTimeout(async () => {
+      console.log(`\n${filename} changed — rebuilding...`);
+      try {
+        await build(docsDir, outDir, { devMode: true });
+        notifyReload();
+      } catch (err) {
+        console.error("Build error:", err);
+      }
+    }, 100);
+  });
+
+  Bun.serve({
+    port,
+    idleTimeout: 0,
+    async fetch(req) {
+      const url = new URL(req.url);
+
+      // Redirect from root to default version/locale
+      if (url.pathname === "/") {
+        const defaultLocale = config.internationalization
+          ? getDefaultLocale(config)
+          : undefined;
+        const defaultVersion = config.versioning
+          ? getDefaultVersion(config)
+          : undefined;
+
+        const redirectPathParts: string[] = [];
+        if (defaultLocale) redirectPathParts.push(defaultLocale);
+        if (defaultVersion) redirectPathParts.push(defaultVersion);
+
+        if (redirectPathParts.length > 0) {
+          const redirectPath = "/" + redirectPathParts.join("/") + "/";
+          return Response.redirect(url.origin + redirectPath, 302);
+        }
+      }
+
+      // SSE endpoint for live reload
+      if (url.pathname === "/_lore/reload") {
+        let ctrl!: ReadableStreamDefaultController<string>;
+        const stream = new ReadableStream<string>({
+          start(c) {
+            ctrl = c;
+            sseClients.add(ctrl);
+            ctrl.enqueue(": connected\n\n");
+          },
+          cancel() {
+            sseClients.delete(ctrl);
+          },
+        });
+        return new Response(stream, {
+          headers: {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+          },
+        });
+      }
+
+      // Serve files from outDir
+      let filePath = path.join(outDir, url.pathname);
+      try {
+        const s = await stat(filePath);
+        if (s.isDirectory()) filePath = path.join(filePath, "index.html");
+      } catch {
+        filePath = path.join(outDir, url.pathname, "index.html");
+      }
+
+      const file = Bun.file(filePath);
+      if (await file.exists()) return new Response(file);
+
+      return new Response("Not found", { status: 404 });
+    },
+  });
+
+  console.log(`\nDev server running at http://localhost:${port}`);
+  console.log("Watching for changes...\n");
+}

package/src/files.ts

@@ -0,0 +1,193 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { parsePage, filenameToTitle } from "./parse.ts";
+import type { PageInfo, SidebarItem, VersionInfo, LocaleInfo } from "./types.ts";
+import { loadConfig } from "./config.ts";
+import { detectVersions, getDefaultVersion } from "./version.ts";
+import { detectLocales, getDefaultLocale } from "./i18n.ts";
+
+export interface DocTree {
+  pages: PageInfo[];
+  sidebar: SidebarItem[];
+  versions?: VersionInfo[];
+  locales?: LocaleInfo[];
+  currentVersion?: string;
+  currentLocale?: string;
+}
+
+/** Strip numeric prefix: "01-configuration" → "configuration" */
+function stripPrefix(name: string): string {
+  return name.replace(/^\d+-/, "");
+}
+
+/** Convert a filename (with .mdx) to a URL slug */
+function toSlug(filename: string): string {
+  return stripPrefix(filename.replace(/\.mdx$/, ""));
+}
+
+/** Build the URL from a list of path parts relative to docs dir */
+function buildUrl(parts: string[]): string {
+  const segments = parts.map((p) => toSlug(p));
+  const filtered = segments.filter((s) => s !== "index");
+  if (filtered.length === 0) return "/";
+  return "/" + filtered.join("/");
+}
+
+function generateListing(title: string, url: string, items: SidebarItem[]): PageInfo {
+  const lines = [`# ${title}`, ""];
+  for (const item of items) {
+    const href = item.type === "page" ? item.url : (item.url ?? "#");
+    lines.push(`- [${item.title}](${href})`);
+  }
+  return { filePath: url, url, title, content: lines.join("\n"), context: {} };
+}
+
+/** Sort entries: index.mdx first, then alphabetically */
+function sortEntries(entries: string[]): string[] {
+  return entries.sort((a, b) => {
+    const aIsIndex = a === "index.mdx";
+    const bIsIndex = b === "index.mdx";
+    if (aIsIndex && !bIsIndex) return -1;
+    if (!aIsIndex && bIsIndex) return 1;
+    return a.localeCompare(b);
+  });
+}
+
+export async function buildDocTree(
+  docsDir: string,
+  opts: {
+    version?: string;
+    locale?: string;
+  } = {}
+): Promise<DocTree> {
+  const config = await loadConfig(docsDir);
+  const hasVersioning = config.versioning;
+  const hasI18n = config.internationalization;
+
+  let versions: VersionInfo[] = [];
+  let locales: LocaleInfo[] = [];
+
+  if (hasI18n) {
+    locales = await detectLocales(docsDir);
+  }
+
+  if (hasVersioning) {
+    if (hasI18n && locales.length > 0) {
+      const locale = opts.locale ?? getDefaultLocale(config);
+      const localeDir = path.join(docsDir, locale);
+      versions = await detectVersions(localeDir);
+    } else {
+      versions = await detectVersions(docsDir);
+    }
+  }
+
+  let contentDir = docsDir;
+  let currentVersion: string | undefined;
+  let currentLocale: string | undefined;
+
+  if (hasI18n) {
+    currentLocale = opts.locale ?? getDefaultLocale(config);
+    contentDir = path.join(contentDir, currentLocale);
+  }
+
+  if (hasVersioning) {
+    currentVersion = opts.version ?? getDefaultVersion(config);
+    contentDir = path.join(contentDir, currentVersion);
+  }
+
+  const pages: PageInfo[] = [];
+  const sidebar: SidebarItem[] = [];
+
+  await walkDir(
+    docsDir,
+    contentDir,
+    [],
+    pages,
+    sidebar,
+    true,
+    currentLocale,
+    currentVersion
+  );
+
+  return {
+    pages,
+    sidebar,
+    versions: versions.length > 0 ? versions : undefined,
+    locales: locales.length > 0 ? locales : undefined,
+    currentVersion,
+    currentLocale,
+  };
+}
+
+async function walkDir(
+  docsDir: string,
+  dir: string,
+  pathParts: string[],
+  pages: PageInfo[],
+  sidebar: SidebarItem[],
+  isRoot: boolean,
+  currentLocale?: string,
+  currentVersion?: string
+): Promise<void> {
+  const entries = sortEntries(await readdir(dir));
+
+  for (const entry of entries) {
+    if (entry === "lore.yml" || entry.startsWith(".")) continue;
+
+    const fullPath = path.join(dir, entry);
+    const s = await stat(fullPath);
+
+    if (s.isDirectory()) {
+      const sectionTitle = filenameToTitle(entry);
+      const sectionItems: SidebarItem[] = [];
+      const sectionPages: PageInfo[] = [];
+
+      await walkDir(docsDir, fullPath, [...pathParts, entry], sectionPages, sectionItems, false, currentLocale, currentVersion);
+
+      const sectionUrl = buildUrl([...pathParts, entry]);
+      const hasIndex = sectionPages.some((p) => p.url === sectionUrl);
+
+      // Auto-generate a directory listing page if there's no explicit index.mdx
+      if (!hasIndex) {
+        sectionPages.push(generateListing(sectionTitle, sectionUrl, sectionItems));
+      }
+
+      pages.push(...sectionPages);
+
+      sidebar.push({
+        type: "section",
+        title: sectionTitle,
+        url: sectionUrl,
+        items: sectionItems,
+      });
+    } else if (entry.endsWith(".mdx")) {
+      const url = buildUrl([...pathParts, entry]);
+      const raw = await Bun.file(fullPath).text();
+      const parsed = parsePage(raw);
+      const baseName = entry.replace(/\.mdx$/, "");
+      const title = parsed.h1Title ?? filenameToTitle(baseName);
+
+      const page: PageInfo = {
+        filePath: fullPath,
+        url,
+        title,
+        description: parsed.description,
+        content: parsed.content,
+        context: {
+          version: currentVersion,
+          locale: currentLocale,
+          translationOf: parsed.frontmatter["translation-of"] as string | undefined,
+        },
+      };
+      pages.push(page);
+
+      const isIndex = toSlug(entry) === "index";
+      // Root index.mdx goes into sidebar; subdirectory index.mdx is shown
+      // via the section header link and not as a separate sidebar item.
+      if (!isIndex || isRoot) {
+        const sidebarTitle = isRoot && isIndex ? "Home" : title;
+        sidebar.push({ type: "page", title: sidebarTitle, url });
+      }
+    }
+  }
+}

package/src/i18n.ts

@@ -0,0 +1,49 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import type { LocaleInfo } from "./types.ts";
+import type { Config } from "./types.ts";
+
+export async function detectLocales(docsDir: string): Promise<LocaleInfo[]> {
+  const entries = await readdir(docsDir);
+  const locales: LocaleInfo[] = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(docsDir, entry);
+    const s = await stat(fullPath);
+
+    if (s.isDirectory() && /^[a-z]{2}(-[a-z]{2})?$/.test(entry)) {
+      locales.push({ code: entry });
+    }
+  }
+
+  return locales.sort((a, b) => a.code.localeCompare(b.code));
+}
+
+export function getDefaultLocale(config: Config): string {
+  return config.defaultLocale ?? "en";
+}
+
+export function getLocaleLabel(code: string): string {
+  const labels: Record<string, string> = {
+    en: "English",
+    es: "Español",
+    fr: "Français",
+    de: "Deutsch",
+    ja: "日本語",
+    zh: "中文",
+    ko: "한국어",
+    pt: "Português",
+    ru: "Русский",
+    it: "Italiano",
+    nl: "Nederlands",
+    pl: "Polski",
+    tr: "Türkçe",
+    ar: "العربية",
+    hi: "हिन्दी",
+    vi: "Tiếng Việt",
+    th: "ไทย",
+    id: "Bahasa Indonesia",
+    ms: "Bahasa Melayu",
+  };
+  return labels[code] ?? code.toUpperCase();
+}