repodocs

Convert GitHub repositories into Docus 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

# Generate docs for any GitHub repo
npx repodocs init nuxt/nuxt

# Preview the generated site
npx repodocs preview

Installation

# 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.

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.

repodocs build [options]

| Flag | Default | Description | |------|---------|-------------| | --dir | ./docs | Documentation directory to build |

repodocs preview

Start the Nuxt dev server for local preview.

repodocs preview [options]

| Flag | Default | Description | |------|---------|-------------| | --dir | ./docs | Documentation directory to serve |

repodocs serve

Alias for repodocs preview.

Examples

# GitHub URL
repodocs init https://github.com/unjs/h3

# owner/repo shorthand
repodocs init nuxt/nuxt

# SSH URL
repodocs init [email protected]: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

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

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