npm package: @leighdinaya/repodocs
Description: Convert GitHub repositories into Docus documentation sites
Author: leighayanid
Latest version: 0.1.0

# 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