@leighdinaya/repodocs 0.1.0

package/README.md

@@ -0,0 +1,178 @@
+# repodocs
+
+[![npm version](https://img.shields.io/npm/v/repodocs)](https://www.npmjs.com/package/repodocs)
+[![License](https://img.shields.io/npm/l/repodocs)](./LICENSE)
+
+Convert GitHub repositories into [Docus](https://docus.dev/) documentation sites.
+
+repodocs fetches any GitHub repo (or local directory), analyzes its structure, transforms markdown and source code into documentation pages, and generates a ready-to-run Nuxt 3 + Docus site — all in a single command.
+
+## Quick Start
+
+```bash
+# Generate docs for any GitHub repo
+npx repodocs init nuxt/nuxt
+
+# Preview the generated site
+npx repodocs preview
+```
+
+## Installation
+
+```bash
+# Global install
+npm install -g repodocs
+
+# Or use directly with npx
+npx repodocs <command>
+```
+
+## CLI Commands
+
+### `repodocs init <source>`
+
+Run the full pipeline: fetch → analyze → transform → generate.
+
+```bash
+repodocs init <source> [options]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `source` | GitHub URL, `owner/repo` shorthand, or local path |
+
+**Options:**
+
+| Flag | Alias | Default | Description |
+|------|-------|---------|-------------|
+| `--output` | `-o` | `./docs` | Output directory |
+| `--branch` | `-b` | — | Branch to clone |
+| `--include-code` | — | `true` | Include source code pages |
+| `--install` | — | `false` | Run `npm install` after generation |
+
+### `repodocs build`
+
+Build the generated Docus site to static HTML.
+
+```bash
+repodocs build [options]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--dir` | `./docs` | Documentation directory to build |
+
+### `repodocs preview`
+
+Start the Nuxt dev server for local preview.
+
+```bash
+repodocs preview [options]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--dir` | `./docs` | Documentation directory to serve |
+
+### `repodocs serve`
+
+Alias for `repodocs preview`.
+
+## Examples
+
+```bash
+# GitHub URL
+repodocs init https://github.com/unjs/h3
+
+# owner/repo shorthand
+repodocs init nuxt/nuxt
+
+# SSH URL
+repodocs init git@github.com:unjs/nitro.git
+
+# Local directory
+repodocs init ./my-project
+
+# Custom output directory and branch
+repodocs init nuxt/nuxt --output ./nuxt-docs --branch main
+
+# Without source code pages
+repodocs init unjs/h3 --no-include-code
+
+# Build and preview
+repodocs init nuxt/nuxt --install
+repodocs preview
+```
+
+## How It Works
+
+repodocs runs a four-stage pipeline:
+
+1. **Fetch** — Clones the repository via git (shallow clone), falls back to the GitHub API tarball download, or reads from a local directory.
+2. **Analyze** — Walks all files, categorizes them (markdown, code, config, asset), and builds a navigation tree.
+3. **Transform** — Converts markdown files (parsing frontmatter, rewriting links) and wraps source code in documentation pages. Generates `_dir.yml` navigation files.
+4. **Generate** — Scaffolds a Nuxt 3 + Docus project, writes all content pages, copies image assets, and generates `nuxt.config.ts` and `app.config.ts`.
+
+## Programmatic API
+
+```typescript
+import {
+  fetchRepo,
+  analyzeRepo,
+  transformContent,
+  generateSite,
+} from "repodocs";
+
+// Fetch a repository
+const { localPath, metadata, cleanup } = await fetchRepo("nuxt/nuxt", {
+  branch: "main",
+  token: process.env.GITHUB_TOKEN,
+});
+
+// Analyze the repo structure
+const analysis = await analyzeRepo(localPath);
+
+// Transform content into documentation pages
+const transformed = await transformContent(analysis, localPath, {
+  includeCode: true,
+});
+
+// Generate the Docus site
+await generateSite(transformed, metadata, {
+  outputDir: "./docs",
+  metadata,
+});
+
+// Clean up temporary files (for remote repos)
+await cleanup?.();
+```
+
+### Type Exports
+
+```typescript
+import type {
+  FetchResult,
+  FetchOptions,
+  RepoMetadata,
+  AnalysisResult,
+  AnalyzedFile,
+  NavNode,
+  FileCategory,
+  TransformResult,
+  TransformedPage,
+  GenerateOptions,
+  SiteConfig,
+} from "repodocs";
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_TOKEN` | GitHub personal access token. Used for API-based fetching (higher rate limits). Optional — works unauthenticated with lower rate limits. |
+
+## License
+
+MIT

package/dist/cli.d.mts

@@ -0,0 +1 @@
+

package/dist/cli.d.ts

@@ -0,0 +1 @@
+

package/dist/cli.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+import { defineCommand, runMain } from 'citty';
+import { D as DEFAULT_OUTPUT_DIR, f as fetchRepo, a as analyzeRepo, t as transformContent, g as generateSite, l as logger } from './shared/repodocs.CfJRqUMt.mjs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import fs from 'fs-extra';
+import 'node:os';
+import 'simple-git';
+import '@octokit/rest';
+import 'fast-glob';
+import 'gray-matter';
+import 'consola';
+
+const initCommand = defineCommand({
+  meta: {
+    name: "init",
+    description: "Fetch a repository and generate a Docus documentation site"
+  },
+  args: {
+    source: {
+      type: "positional",
+      description: "GitHub URL, owner/repo shorthand, or local path",
+      required: true
+    },
+    output: {
+      type: "string",
+      alias: "o",
+      description: "Output directory",
+      default: DEFAULT_OUTPUT_DIR
+    },
+    branch: {
+      type: "string",
+      alias: "b",
+      description: "Branch to clone"
+    },
+    "include-code": {
+      type: "boolean",
+      description: "Include source code pages",
+      default: true
+    },
+    install: {
+      type: "boolean",
+      description: "Run npm install after generation",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const { source, output, branch, install } = args;
+    const includeCode = args["include-code"];
+    try {
+      const fetchResult = await fetchRepo(source, { branch });
+      try {
+        const analysis = await analyzeRepo(fetchResult.localPath);
+        const transformed = await transformContent(analysis, fetchResult.localPath, {
+          includeCode
+        });
+        await generateSite(transformed, fetchResult.metadata, {
+          outputDir: output,
+          metadata: fetchResult.metadata,
+          install
+        });
+      } finally {
+        if (fetchResult.cleanup) {
+          await fetchResult.cleanup();
+        }
+      }
+    } catch (error) {
+      logger.error(`Failed to generate documentation: ${error}`);
+      process.exit(1);
+    }
+  }
+});
+
+const buildCommand = defineCommand({
+  meta: {
+    name: "build",
+    description: "Build the documentation site to static HTML"
+  },
+  args: {
+    dir: {
+      type: "string",
+      description: "Documentation directory",
+      default: DEFAULT_OUTPUT_DIR
+    }
+  },
+  async run({ args }) {
+    const dir = path.resolve(args.dir);
+    if (!await fs.pathExists(path.join(dir, "nuxt.config.ts"))) {
+      logger.error(`No Docus project found in ${dir}. Run \`repodocs init\` first.`);
+      process.exit(1);
+    }
+    logger.start("Building documentation site...");
+    try {
+      execSync("npx nuxi generate", { cwd: dir, stdio: "inherit" });
+      logger.success("Build complete! Output in .output/public/");
+    } catch (error) {
+      logger.error("Build failed");
+      process.exit(1);
+    }
+  }
+});
+
+const previewCommand = defineCommand({
+  meta: {
+    name: "preview",
+    description: "Preview the documentation site locally"
+  },
+  args: {
+    dir: {
+      type: "string",
+      description: "Documentation directory",
+      default: DEFAULT_OUTPUT_DIR
+    }
+  },
+  async run({ args }) {
+    const dir = path.resolve(args.dir);
+    if (!await fs.pathExists(path.join(dir, "nuxt.config.ts"))) {
+      logger.error(`No Docus project found in ${dir}. Run \`repodocs init\` first.`);
+      process.exit(1);
+    }
+    logger.start("Starting preview server...");
+    try {
+      execSync("npx nuxi dev", { cwd: dir, stdio: "inherit" });
+    } catch {
+    }
+  }
+});
+
+const main = defineCommand({
+  meta: {
+    name: "repodocs",
+    version: "0.1.0",
+    description: "Convert GitHub repositories into Docus documentation sites"
+  },
+  subCommands: {
+    init: initCommand,
+    build: buildCommand,
+    preview: previewCommand,
+    serve: previewCommand
+  }
+});
+runMain(main);

package/dist/index.d.mts

@@ -0,0 +1,92 @@
+interface FetchOptions {
+    branch?: string;
+    token?: string;
+}
+interface RepoMetadata {
+    name: string;
+    description: string;
+    owner: string;
+    repo: string;
+    branch: string;
+    url: string;
+    defaultBranch: string;
+    isLocal: boolean;
+}
+interface FetchResult {
+    localPath: string;
+    metadata: RepoMetadata;
+    cleanup?: () => Promise<void>;
+}
+
+declare function fetchRepo(input: string, options?: FetchOptions): Promise<FetchResult>;
+
+type FileCategory = "markdown" | "code" | "config" | "asset" | "ignored";
+interface AnalyzedFile {
+    relativePath: string;
+    absolutePath: string;
+    category: FileCategory;
+    language?: string;
+    size: number;
+}
+interface NavNode {
+    label: string;
+    path: string;
+    children: NavNode[];
+    isDirectory: boolean;
+    order: number;
+}
+interface AnalysisResult {
+    files: AnalyzedFile[];
+    navigation: NavNode;
+    markdownFiles: AnalyzedFile[];
+    codeFiles: AnalyzedFile[];
+    configFiles: AnalyzedFile[];
+    assetFiles: AnalyzedFile[];
+}
+
+declare function analyzeRepo(repoPath: string): Promise<AnalysisResult>;
+
+interface TransformedPage {
+    /** Path relative to content/ directory */
+    contentPath: string;
+    /** Full markdown content with frontmatter */
+    content: string;
+    /** Original source file path */
+    sourcePath: string;
+}
+interface TransformResult {
+    pages: TransformedPage[];
+    images: ImageAsset[];
+    navigationFiles: NavigationFile[];
+}
+interface ImageAsset {
+    sourcePath: string;
+    destPath: string;
+}
+interface NavigationFile {
+    dirPath: string;
+    content: string;
+}
+
+interface TransformOptions {
+    includeCode?: boolean;
+}
+declare function transformContent(analysis: AnalysisResult, repoPath: string, options?: TransformOptions): Promise<TransformResult>;
+
+interface GenerateOptions {
+    outputDir: string;
+    metadata: RepoMetadata;
+    install?: boolean;
+}
+interface SiteConfig {
+    siteName: string;
+    description: string;
+    githubUrl: string;
+    githubOwner: string;
+    githubRepo: string;
+}
+
+declare function generateSite(transformResult: TransformResult, metadata: RepoMetadata, options: GenerateOptions): Promise<void>;
+
+export { analyzeRepo, fetchRepo, generateSite, transformContent };
+export type { AnalysisResult, AnalyzedFile, FetchOptions, FetchResult, FileCategory, GenerateOptions, NavNode, RepoMetadata, SiteConfig, TransformResult, TransformedPage };

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+interface FetchOptions {
+    branch?: string;
+    token?: string;
+}
+interface RepoMetadata {
+    name: string;
+    description: string;
+    owner: string;
+    repo: string;
+    branch: string;
+    url: string;
+    defaultBranch: string;
+    isLocal: boolean;
+}
+interface FetchResult {
+    localPath: string;
+    metadata: RepoMetadata;
+    cleanup?: () => Promise<void>;
+}
+
+declare function fetchRepo(input: string, options?: FetchOptions): Promise<FetchResult>;
+
+type FileCategory = "markdown" | "code" | "config" | "asset" | "ignored";
+interface AnalyzedFile {
+    relativePath: string;
+    absolutePath: string;
+    category: FileCategory;
+    language?: string;
+    size: number;
+}
+interface NavNode {
+    label: string;
+    path: string;
+    children: NavNode[];
+    isDirectory: boolean;
+    order: number;
+}
+interface AnalysisResult {
+    files: AnalyzedFile[];
+    navigation: NavNode;
+    markdownFiles: AnalyzedFile[];
+    codeFiles: AnalyzedFile[];
+    configFiles: AnalyzedFile[];
+    assetFiles: AnalyzedFile[];
+}
+
+declare function analyzeRepo(repoPath: string): Promise<AnalysisResult>;
+
+interface TransformedPage {
+    /** Path relative to content/ directory */
+    contentPath: string;
+    /** Full markdown content with frontmatter */
+    content: string;
+    /** Original source file path */
+    sourcePath: string;
+}
+interface TransformResult {
+    pages: TransformedPage[];
+    images: ImageAsset[];
+    navigationFiles: NavigationFile[];
+}
+interface ImageAsset {
+    sourcePath: string;
+    destPath: string;
+}
+interface NavigationFile {
+    dirPath: string;
+    content: string;
+}
+
+interface TransformOptions {
+    includeCode?: boolean;
+}
+declare function transformContent(analysis: AnalysisResult, repoPath: string, options?: TransformOptions): Promise<TransformResult>;
+
+interface GenerateOptions {
+    outputDir: string;
+    metadata: RepoMetadata;
+    install?: boolean;
+}
+interface SiteConfig {
+    siteName: string;
+    description: string;
+    githubUrl: string;
+    githubOwner: string;
+    githubRepo: string;
+}
+
+declare function generateSite(transformResult: TransformResult, metadata: RepoMetadata, options: GenerateOptions): Promise<void>;
+
+export { analyzeRepo, fetchRepo, generateSite, transformContent };
+export type { AnalysisResult, AnalyzedFile, FetchOptions, FetchResult, FileCategory, GenerateOptions, NavNode, RepoMetadata, SiteConfig, TransformResult, TransformedPage };

package/dist/index.mjs

@@ -0,0 +1,10 @@
+export { a as analyzeRepo, f as fetchRepo, g as generateSite, t as transformContent } from './shared/repodocs.CfJRqUMt.mjs';
+import 'node:path';
+import 'fs-extra';
+import 'node:os';
+import 'simple-git';
+import 'node:child_process';
+import '@octokit/rest';
+import 'fast-glob';
+import 'gray-matter';
+import 'consola';

package/dist/shared/repodocs.CfJRqUMt.mjs

@@ -0,0 +1,828 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import os from 'node:os';
+import simpleGit from 'simple-git';
+import { execSync } from 'node:child_process';
+import { Octokit } from '@octokit/rest';
+import fg from 'fast-glob';
+import matter from 'gray-matter';
+import { createConsola } from 'consola';
+
+function parseGitHubURL(input) {
+  const sshMatch = input.match(/^git@github\.com:([^/]+)\/([^/.]+?)(?:\.git)?$/);
+  if (sshMatch) {
+    return { owner: sshMatch[1], repo: sshMatch[2] };
+  }
+  let cleaned = input.replace(/^https?:\/\//, "").replace(/^github\.com\//, "").replace(/\.git$/, "").replace(/\/$/, "");
+  cleaned = cleaned.replace(/^github\.com\//, "");
+  const match = cleaned.match(/^([^/]+)\/([^/]+?)(?:\/tree\/(.+))?$/);
+  if (!match) return null;
+  return {
+    owner: match[1],
+    repo: match[2],
+    branch: match[3] || void 0
+  };
+}
+function isGitHubURL(input) {
+  return input.includes("github.com") || input.startsWith("git@github.com:") || /^[a-zA-Z0-9_-]+\/[a-zA-Z0-9._-]+$/.test(input);
+}
+function buildCloneURL(owner, repo) {
+  return `https://github.com/${owner}/${repo}.git`;
+}
+
+const logger = createConsola({
+  fancy: true,
+  formatOptions: {
+    date: false
+  }
+});
+
+async function fetchLocal(localPath) {
+  const resolved = path.resolve(localPath);
+  if (!await fs.pathExists(resolved)) {
+    throw new Error(`Local path does not exist: ${resolved}`);
+  }
+  const stat = await fs.stat(resolved);
+  if (!stat.isDirectory()) {
+    throw new Error(`Path is not a directory: ${resolved}`);
+  }
+  logger.info(`Reading local repository at ${resolved}`);
+  let name = path.basename(resolved);
+  let description = "";
+  const pkgPath = path.join(resolved, "package.json");
+  if (await fs.pathExists(pkgPath)) {
+    try {
+      const pkg = await fs.readJSON(pkgPath);
+      name = pkg.name || name;
+      description = pkg.description || "";
+    } catch {
+    }
+  }
+  return {
+    localPath: resolved,
+    metadata: {
+      name,
+      description,
+      owner: "",
+      repo: name,
+      branch: "main",
+      url: "",
+      defaultBranch: "main",
+      isLocal: true
+    }
+  };
+}
+
+async function fetchViaGit(owner, repo, options = {}) {
+  const cloneUrl = buildCloneURL(owner, repo);
+  const tempDir = path.join(os.tmpdir(), `repodocs-${owner}-${repo}-${Date.now()}`);
+  await fs.ensureDir(tempDir);
+  logger.start(`Cloning ${owner}/${repo} via git...`);
+  const git = simpleGit();
+  const cloneArgs = ["--depth", "1"];
+  if (options.branch) {
+    cloneArgs.push("--branch", options.branch);
+  }
+  try {
+    await git.clone(cloneUrl, tempDir, cloneArgs);
+  } catch (error) {
+    await fs.remove(tempDir).catch(() => {
+    });
+    throw error;
+  }
+  logger.success(`Cloned ${owner}/${repo}`);
+  const repoGit = simpleGit(tempDir);
+  const branch = (await repoGit.branch()).current || options.branch || "main";
+  let name = repo;
+  let description = "";
+  const pkgPath = path.join(tempDir, "package.json");
+  if (await fs.pathExists(pkgPath)) {
+    try {
+      const pkg = await fs.readJSON(pkgPath);
+      name = pkg.name || name;
+      description = pkg.description || "";
+    } catch {
+    }
+  }
+  const metadata = {
+    name,
+    description,
+    owner,
+    repo,
+    branch,
+    url: `https://github.com/${owner}/${repo}`,
+    defaultBranch: branch,
+    isLocal: false
+  };
+  return {
+    localPath: tempDir,
+    metadata,
+    cleanup: async () => {
+      await fs.remove(tempDir).catch(() => {
+      });
+    }
+  };
+}
+
+async function fetchViaGitHubAPI(owner, repo, options = {}) {
+  const token = options.token || process.env.GITHUB_TOKEN;
+  const octokit = new Octokit({ auth: token || void 0 });
+  logger.start(`Fetching ${owner}/${repo} via GitHub API...`);
+  const { data: repoData } = await octokit.repos.get({ owner, repo });
+  const branch = options.branch || repoData.default_branch;
+  const { data: tarball } = await octokit.repos.downloadTarballArchive({
+    owner,
+    repo,
+    ref: branch
+  });
+  const tempDir = path.join(os.tmpdir(), `repodocs-${owner}-${repo}-${Date.now()}`);
+  const tarPath = path.join(os.tmpdir(), `repodocs-${owner}-${repo}-${Date.now()}.tar.gz`);
+  await fs.ensureDir(tempDir);
+  await fs.writeFile(tarPath, Buffer.from(tarball));
+  try {
+    execSync(`tar xzf "${tarPath}" -C "${tempDir}" --strip-components=1`, {
+      stdio: "pipe"
+    });
+  } finally {
+    await fs.remove(tarPath).catch(() => {
+    });
+  }
+  logger.success(`Downloaded ${owner}/${repo}`);
+  const metadata = {
+    name: repoData.name,
+    description: repoData.description || "",
+    owner,
+    repo,
+    branch,
+    url: repoData.html_url,
+    defaultBranch: repoData.default_branch,
+    isLocal: false
+  };
+  return {
+    localPath: tempDir,
+    metadata,
+    cleanup: async () => {
+      await fs.remove(tempDir).catch(() => {
+      });
+    }
+  };
+}
+
+async function fetchRepo(input, options = {}) {
+  const resolved = path.resolve(input);
+  if (await fs.pathExists(resolved)) {
+    const stat = await fs.stat(resolved);
+    if (stat.isDirectory()) {
+      return fetchLocal(resolved);
+    }
+  }
+  if (!isGitHubURL(input)) {
+    throw new Error(
+      `Invalid input: "${input}". Provide a GitHub URL or a local directory path.`
+    );
+  }
+  const parsed = parseGitHubURL(input);
+  if (!parsed) {
+    throw new Error(`Could not parse GitHub URL: "${input}"`);
+  }
+  const { owner, repo } = parsed;
+  const branch = options.branch || parsed.branch;
+  try {
+    return await fetchViaGit(owner, repo, { ...options, branch });
+  } catch (error) {
+    logger.warn("Git clone failed, trying GitHub API fallback...");
+    logger.debug(String(error));
+    return await fetchViaGitHubAPI(owner, repo, { ...options, branch });
+  }
+}
+
+const IGNORE_PATTERNS = [
+  "node_modules/**",
+  ".git/**",
+  "dist/**",
+  "build/**",
+  ".output/**",
+  ".nuxt/**",
+  ".next/**",
+  ".cache/**",
+  "coverage/**",
+  ".DS_Store",
+  "*.lock",
+  "package-lock.json",
+  "yarn.lock",
+  "pnpm-lock.yaml",
+  "bun.lockb",
+  "*.min.js",
+  "*.min.css",
+  "*.map",
+  "*.wasm",
+  "*.ico",
+  "*.ttf",
+  "*.woff",
+  "*.woff2",
+  "*.eot",
+  "*.mp4",
+  "*.webm",
+  "*.mov",
+  "*.zip",
+  "*.tar",
+  "*.gz",
+  "*.exe",
+  "*.dll",
+  "*.so",
+  "*.dylib"
+];
+const MAX_FILE_SIZE = 512 * 1024;
+const MARKDOWN_EXTENSIONS = [".md", ".mdx"];
+const CODE_EXTENSIONS = {
+  ".ts": "typescript",
+  ".tsx": "tsx",
+  ".js": "javascript",
+  ".jsx": "jsx",
+  ".vue": "vue",
+  ".svelte": "svelte",
+  ".py": "python",
+  ".rb": "ruby",
+  ".go": "go",
+  ".rs": "rust",
+  ".java": "java",
+  ".kt": "kotlin",
+  ".swift": "swift",
+  ".c": "c",
+  ".cpp": "cpp",
+  ".h": "c",
+  ".hpp": "cpp",
+  ".cs": "csharp",
+  ".php": "php",
+  ".sh": "bash",
+  ".bash": "bash",
+  ".zsh": "bash",
+  ".fish": "fish",
+  ".sql": "sql",
+  ".graphql": "graphql",
+  ".gql": "graphql",
+  ".yaml": "yaml",
+  ".yml": "yaml",
+  ".toml": "toml",
+  ".json": "json",
+  ".xml": "xml",
+  ".html": "html",
+  ".css": "css",
+  ".scss": "scss",
+  ".sass": "sass",
+  ".less": "less",
+  ".dockerfile": "dockerfile",
+  ".tf": "hcl",
+  ".lua": "lua",
+  ".r": "r",
+  ".dart": "dart",
+  ".ex": "elixir",
+  ".exs": "elixir",
+  ".erl": "erlang",
+  ".zig": "zig",
+  ".nim": "nim",
+  ".ml": "ocaml",
+  ".hs": "haskell",
+  ".clj": "clojure",
+  ".scala": "scala"
+};
+const CONFIG_FILES = [
+  "package.json",
+  "tsconfig.json",
+  "nuxt.config.ts",
+  "nuxt.config.js",
+  "vite.config.ts",
+  "vite.config.js",
+  "webpack.config.js",
+  "rollup.config.js",
+  ".eslintrc",
+  ".eslintrc.js",
+  ".eslintrc.json",
+  ".prettierrc",
+  ".prettierrc.js",
+  ".prettierrc.json",
+  "Dockerfile",
+  "docker-compose.yml",
+  "Makefile",
+  ".env.example"
+];
+const IMAGE_EXTENSIONS = [".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".avif"];
+const DEFAULT_OUTPUT_DIR = "./docs";
+
+async function walkFiles(repoPath) {
+  const entries = await fg("**/*", {
+    cwd: repoPath,
+    dot: false,
+    ignore: IGNORE_PATTERNS,
+    onlyFiles: true,
+    stats: true
+  });
+  const files = [];
+  for (const entry of entries) {
+    const absolutePath = path.join(repoPath, entry.path);
+    const size = entry.stats?.size ?? 0;
+    if (size > MAX_FILE_SIZE) continue;
+    files.push({
+      relativePath: entry.path,
+      absolutePath,
+      size
+    });
+  }
+  return files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+
+function getLanguageFromExtension(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return CODE_EXTENSIONS[ext] || "text";
+}
+function getLanguageDisplayName(lang) {
+  const names = {
+    typescript: "TypeScript",
+    javascript: "JavaScript",
+    python: "Python",
+    ruby: "Ruby",
+    go: "Go",
+    rust: "Rust",
+    java: "Java",
+    kotlin: "Kotlin",
+    swift: "Swift",
+    csharp: "C#",
+    cpp: "C++",
+    c: "C",
+    php: "PHP",
+    bash: "Shell",
+    sql: "SQL",
+    yaml: "YAML",
+    json: "JSON",
+    html: "HTML",
+    css: "CSS",
+    vue: "Vue",
+    tsx: "TSX",
+    jsx: "JSX",
+    svelte: "Svelte",
+    dockerfile: "Dockerfile",
+    graphql: "GraphQL",
+    hcl: "HCL",
+    dart: "Dart",
+    elixir: "Elixir",
+    scala: "Scala",
+    haskell: "Haskell",
+    clojure: "Clojure",
+    ocaml: "OCaml",
+    text: "Text"
+  };
+  return names[lang] || lang;
+}
+
+function categorizeFile(file) {
+  const ext = path.extname(file.relativePath).toLowerCase();
+  const basename = path.basename(file.relativePath);
+  let category;
+  let language;
+  if (MARKDOWN_EXTENSIONS.includes(ext)) {
+    category = "markdown";
+  } else if (CONFIG_FILES.includes(basename)) {
+    category = "config";
+    language = getLanguageFromExtension(file.relativePath);
+  } else if (ext in CODE_EXTENSIONS) {
+    category = "code";
+    language = getLanguageFromExtension(file.relativePath);
+  } else if (IMAGE_EXTENSIONS.includes(ext)) {
+    category = "asset";
+  } else {
+    category = "ignored";
+  }
+  return {
+    relativePath: file.relativePath,
+    absolutePath: file.absolutePath,
+    category,
+    language,
+    size: file.size
+  };
+}
+function categorizeFiles(files) {
+  return files.map(categorizeFile);
+}
+
+function toContentPath(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  const parts = normalized.split("/");
+  const last = parts[parts.length - 1];
+  if (/^readme\.md$/i.test(last)) {
+    parts[parts.length - 1] = "index.md";
+  }
+  return parts.join("/");
+}
+function toCodeContentPath(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  return `code/${normalized}.md`;
+}
+function mdLinkToRoute(linkPath, fromFile) {
+  const [pathPart, anchor] = linkPath.split("#");
+  if (!pathPart) {
+    return anchor ? `#${anchor}` : "";
+  }
+  const fromDir = path.dirname(fromFile);
+  let resolved = path.join(fromDir, pathPart).replace(/\\/g, "/");
+  resolved = resolved.replace(/\.md$/i, "");
+  resolved = resolved.replace(/\/readme$/i, "").replace(/\/index$/i, "");
+  if (!resolved.startsWith("/")) {
+    resolved = "/" + resolved;
+  }
+  if (resolved === "/") {
+    return anchor ? `/#${anchor}` : "/";
+  }
+  return anchor ? `${resolved}#${anchor}` : resolved;
+}
+function fileNameToTitle(fileName) {
+  const name = path.basename(fileName).replace(path.extname(fileName), "");
+  if (/^readme$/i.test(name)) return "Overview";
+  if (/^index$/i.test(name)) return "Overview";
+  return name.replace(/[-_]/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2").replace(/\b\w/g, (c) => c.toUpperCase()).trim();
+}
+function dirNameToLabel(dirName) {
+  return dirName.replace(/[-_]/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2").replace(/\b\w/g, (c) => c.toUpperCase()).trim();
+}
+
+function buildNavigationTree(files) {
+  const root = {
+    label: "Root",
+    path: "/",
+    children: [],
+    isDirectory: true,
+    order: 0
+  };
+  const markdownFiles = files.filter((f) => f.category === "markdown");
+  for (const file of markdownFiles) {
+    const parts = file.relativePath.split("/");
+    let current = root;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const dirName = parts[i];
+      let child = current.children.find(
+        (c) => c.isDirectory && c.label === dirNameToLabel(dirName)
+      );
+      if (!child) {
+        child = {
+          label: dirNameToLabel(dirName),
+          path: "/" + parts.slice(0, i + 1).join("/"),
+          children: [],
+          isDirectory: true,
+          order: current.children.length
+        };
+        current.children.push(child);
+      }
+      current = child;
+    }
+    const fileName = parts[parts.length - 1];
+    const isReadme = /^readme\.md$/i.test(fileName);
+    current.children.push({
+      label: fileNameToTitle(fileName),
+      path: buildRoutePath(file.relativePath),
+      children: [],
+      isDirectory: false,
+      order: isReadme ? -1 : current.children.length
+    });
+  }
+  sortNavTree(root);
+  return root;
+}
+function buildRoutePath(filePath) {
+  let route = filePath.replace(/\\/g, "/");
+  route = route.replace(/\.md$/i, "");
+  route = route.replace(/\/readme$/i, "").replace(/^readme$/i, "");
+  if (!route.startsWith("/")) route = "/" + route;
+  return route || "/";
+}
+function sortNavTree(node) {
+  node.children.sort((a, b) => {
+    if (a.isDirectory !== b.isDirectory) {
+      return a.isDirectory ? -1 : 1;
+    }
+    if (a.order !== b.order) return a.order - b.order;
+    return a.label.localeCompare(b.label);
+  });
+  for (const child of node.children) {
+    if (child.isDirectory) {
+      sortNavTree(child);
+    }
+  }
+}
+
+async function analyzeRepo(repoPath) {
+  logger.start("Analyzing repository structure...");
+  const walked = await walkFiles(repoPath);
+  const files = categorizeFiles(walked);
+  const markdownFiles = files.filter((f) => f.category === "markdown");
+  const codeFiles = files.filter((f) => f.category === "code");
+  const configFiles = files.filter((f) => f.category === "config");
+  const assetFiles = files.filter((f) => f.category === "asset");
+  const navigation = buildNavigationTree(files);
+  logger.success(
+    `Found ${markdownFiles.length} markdown, ${codeFiles.length} code, ${configFiles.length} config, ${assetFiles.length} asset files`
+  );
+  return {
+    files,
+    navigation,
+    markdownFiles,
+    codeFiles,
+    configFiles,
+    assetFiles
+  };
+}
+
+async function transformMarkdownFile(file, repoPath) {
+  const fullPath = path.join(repoPath, file.relativePath);
+  const raw = await fs.readFile(fullPath, "utf-8");
+  const { data: existingFrontmatter, content: bodyContent } = matter(raw);
+  let title = existingFrontmatter.title;
+  if (!title) {
+    const headingMatch = bodyContent.match(/^#\s+(.+)$/m);
+    title = headingMatch ? headingMatch[1].trim() : fileNameToTitle(file.relativePath);
+  }
+  const frontmatter = {
+    title,
+    ...existingFrontmatter
+  };
+  if (!frontmatter.description && existingFrontmatter.description) {
+    frontmatter.description = existingFrontmatter.description;
+  }
+  const images = [];
+  let processedBody = bodyContent;
+  processedBody = processedBody.replace(
+    /\[([^\]]*)\]\(([^)]+)\)/g,
+    (match, text, href) => {
+      if (href.startsWith("http") || href.startsWith("#") || href.startsWith("mailto:")) {
+        return match;
+      }
+      const ext = path.extname(href.split("#")[0].split("?")[0]).toLowerCase();
+      if (IMAGE_EXTENSIONS.includes(ext)) {
+        const imageSrc = resolveImagePath(href, file.relativePath);
+        images.push({
+          sourcePath: path.join(repoPath, path.dirname(file.relativePath), href),
+          destPath: imageSrc
+        });
+        return `[${text}](${imageSrc})`;
+      }
+      if (href.endsWith(".md") || href.includes(".md#")) {
+        const route = mdLinkToRoute(href, file.relativePath);
+        return `[${text}](${route})`;
+      }
+      return match;
+    }
+  );
+  processedBody = processedBody.replace(
+    /!\[([^\]]*)\]\(([^)]+)\)/g,
+    (match, alt, src) => {
+      if (src.startsWith("http")) return match;
+      const ext = path.extname(src.split("?")[0]).toLowerCase();
+      if (IMAGE_EXTENSIONS.includes(ext)) {
+        const imageDest = resolveImagePath(src, file.relativePath);
+        images.push({
+          sourcePath: path.join(repoPath, path.dirname(file.relativePath), src),
+          destPath: imageDest
+        });
+        return `![${alt}](${imageDest})`;
+      }
+      return match;
+    }
+  );
+  const contentPath = toContentPath(file.relativePath);
+  const finalContent = matter.stringify(processedBody, frontmatter);
+  return {
+    page: {
+      contentPath,
+      content: finalContent,
+      sourcePath: file.relativePath
+    },
+    images
+  };
+}
+function resolveImagePath(href, fromFile) {
+  const fromDir = path.dirname(fromFile);
+  const resolved = path.join(fromDir, href).replace(/\\/g, "/");
+  return `/images/${resolved}`;
+}
+
+async function transformCodeFile(file, repoPath) {
+  const fullPath = path.join(repoPath, file.relativePath);
+  const code = await fs.readFile(fullPath, "utf-8");
+  const language = getLanguageFromExtension(file.relativePath);
+  const displayName = getLanguageDisplayName(language);
+  fileNameToTitle(file.relativePath);
+  const frontmatter = {
+    title: `${path.basename(file.relativePath)}`,
+    description: `Source code: ${file.relativePath}`,
+    navigation: {
+      title: path.basename(file.relativePath)
+    }
+  };
+  const body = `# ${path.basename(file.relativePath)}
+
+> Source: \`${file.relativePath}\` | Language: ${displayName}
+
+\`\`\`${language}
+${code}
+\`\`\`
+`;
+  const content = matter.stringify(body, frontmatter);
+  const contentPath = toCodeContentPath(file.relativePath);
+  return {
+    contentPath,
+    content,
+    sourcePath: file.relativePath
+  };
+}
+
+function generateNavigationFiles(tree) {
+  const files = [];
+  collectDirYml(tree, "", files);
+  return files;
+}
+function collectDirYml(node, currentPath, files) {
+  for (const child of node.children) {
+    if (child.isDirectory) {
+      const dirPath = currentPath ? `${currentPath}/${slugify(child.label)}` : slugify(child.label);
+      const content = `title: "${child.label}"
+navigation:
+  title: "${child.label}"
+`;
+      files.push({
+        dirPath,
+        content
+      });
+      collectDirYml(child, dirPath, files);
+    }
+  }
+}
+function slugify(label) {
+  return label.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "");
+}
+
+async function transformContent(analysis, repoPath, options = {}) {
+  const { includeCode = true } = options;
+  logger.start("Transforming content...");
+  const result = {
+    pages: [],
+    images: [],
+    navigationFiles: []
+  };
+  for (const file of analysis.markdownFiles) {
+    try {
+      const { page, images } = await transformMarkdownFile(file, repoPath);
+      result.pages.push(page);
+      result.images.push(...images);
+    } catch (error) {
+      logger.warn(`Skipping ${file.relativePath}: ${error}`);
+    }
+  }
+  if (includeCode) {
+    for (const file of analysis.codeFiles) {
+      try {
+        const page = await transformCodeFile(file, repoPath);
+        result.pages.push(page);
+      } catch (error) {
+        logger.warn(`Skipping code file ${file.relativePath}: ${error}`);
+      }
+    }
+  }
+  result.navigationFiles = generateNavigationFiles(analysis.navigation);
+  logger.success(
+    `Transformed ${result.pages.length} pages, ${result.images.length} images`
+  );
+  return result;
+}
+
+async function scaffoldDocusProject(outputDir, config) {
+  await fs.ensureDir(outputDir);
+  await fs.ensureDir(path.join(outputDir, "content"));
+  await fs.ensureDir(path.join(outputDir, "public"));
+  const pkg = {
+    name: `${config.githubRepo}-docs`,
+    private: true,
+    scripts: {
+      dev: "nuxi dev",
+      build: "nuxi build",
+      generate: "nuxi generate",
+      preview: "nuxi preview"
+    },
+    devDependencies: {
+      "@nuxt-themes/docus": "^1.15.0",
+      nuxt: "^3.16.0"
+    }
+  };
+  await fs.writeJSON(path.join(outputDir, "package.json"), pkg, { spaces: 2 });
+  const gitignore = `node_modules
+.output
+.nuxt
+.DS_Store
+`;
+  await fs.writeFile(path.join(outputDir, ".gitignore"), gitignore);
+}
+
+async function writeConfigs(outputDir, config) {
+  const nuxtConfig = `export default defineNuxtConfig({
+  extends: ["@nuxt-themes/docus"],
+});
+`;
+  await fs.writeFile(path.join(outputDir, "nuxt.config.ts"), nuxtConfig);
+  const appConfig = `export default defineAppConfig({
+  docus: {
+    title: ${JSON.stringify(config.siteName)},
+    description: ${JSON.stringify(config.description)},
+    socials: {
+      github: ${JSON.stringify(config.githubUrl || "")},
+    },
+    aside: {
+      level: 1,
+      collapsed: false,
+      exclude: [],
+    },
+    header: {
+      title: ${JSON.stringify(config.siteName)},
+      logo: false,
+      showLinkIcon: true,
+    },
+    footer: {
+      credits: {
+        text: "Generated with repodocs",
+        href: "https://github.com/repodocs/repodocs",
+        icon: "IconDocus",
+      },
+    },
+  },
+});
+`;
+  await fs.writeFile(path.join(outputDir, "app.config.ts"), appConfig);
+}
+
+async function writeContent(outputDir, transformResult) {
+  const contentDir = path.join(outputDir, "content");
+  const publicDir = path.join(outputDir, "public");
+  for (const page of transformResult.pages) {
+    const filePath = path.join(contentDir, page.contentPath);
+    await fs.ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, page.content);
+  }
+  for (const navFile of transformResult.navigationFiles) {
+    const filePath = path.join(contentDir, navFile.dirPath, "_dir.yml");
+    await fs.ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, navFile.content);
+  }
+  for (const image of transformResult.images) {
+    try {
+      if (await fs.pathExists(image.sourcePath)) {
+        const destPath = path.join(publicDir, image.destPath);
+        await fs.ensureDir(path.dirname(destPath));
+        await fs.copy(image.sourcePath, destPath);
+      }
+    } catch (error) {
+      logger.warn(`Could not copy image ${image.sourcePath}: ${error}`);
+    }
+  }
+}
+
+async function generateSite(transformResult, metadata, options) {
+  const { outputDir, install } = options;
+  const resolvedOutput = path.resolve(outputDir);
+  logger.start(`Generating Docus site in ${resolvedOutput}...`);
+  const config = {
+    siteName: formatSiteName(metadata.name),
+    description: metadata.description || `Documentation for ${metadata.name}`,
+    githubUrl: metadata.url,
+    githubOwner: metadata.owner,
+    githubRepo: metadata.repo
+  };
+  await scaffoldDocusProject(resolvedOutput, config);
+  await writeConfigs(resolvedOutput, config);
+  await writeContent(resolvedOutput, transformResult);
+  if (install) {
+    logger.start("Installing dependencies...");
+    try {
+      execSync("npm install", { cwd: resolvedOutput, stdio: "pipe" });
+      logger.success("Dependencies installed");
+    } catch (error) {
+      logger.warn("Failed to install dependencies. Run `npm install` manually.");
+    }
+  }
+  const pageCount = transformResult.pages.length;
+  const imageCount = transformResult.images.length;
+  logger.box(
+    [
+      `Documentation site generated!`,
+      ``,
+      `  Pages:  ${pageCount}`,
+      `  Images: ${imageCount}`,
+      `  Output: ${resolvedOutput}`,
+      ``,
+      `Next steps:`,
+      `  cd ${path.relative(process.cwd(), resolvedOutput)}`,
+      `  npm install`,
+      `  npm run dev`
+    ].join("\n")
+  );
+}
+function formatSiteName(name) {
+  return name.replace(/^@[^/]+\//, "").replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+export { DEFAULT_OUTPUT_DIR as D, analyzeRepo as a, fetchRepo as f, generateSite as g, logger as l, transformContent as t };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@leighdinaya/repodocs",
+  "version": "0.1.0",
+  "description": "Convert GitHub repositories into Docus documentation sites",
+  "author": "leighayanid",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leighayanid/repodocs.git"
+  },
+  "homepage": "https://github.com/leighayanid/repodocs#readme",
+  "bugs": {
+    "url": "https://github.com/leighayanid/repodocs/issues"
+  },
+  "keywords": [
+    "documentation",
+    "docus",
+    "github",
+    "docs-generator",
+    "nuxt"
+  ],
+  "type": "module",
+  "bin": {
+    "repodocs": "dist/cli.mjs"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "dev": "jiti src/cli.ts",
+    "stub": "unbuild --stub"
+  },
+  "dependencies": {
+    "@octokit/rest": "^21.1.1",
+    "citty": "^0.1.6",
+    "colorette": "^2.0.20",
+    "consola": "^3.4.2",
+    "fast-glob": "^3.3.3",
+    "fs-extra": "^11.3.0",
+    "gray-matter": "^4.0.3",
+    "simple-git": "^3.27.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "jiti": "^2.4.2",
+    "typescript": "^5.7.3",
+    "unbuild": "^3.5.0"
+  }
+}