title: 'fea-docs'

fea-docs

Zero-config documentation previewer and builder for any repository.

Run npx fea-docs@latest start from any directory and get a live Starlight-powered docs site from your existing Markdown and MDX files — no framework setup, no configuration required.

Features

• Instant preview — discovers all .md and .mdx files under the current directory
• Hierarchical navigation — sidebar mirrors your directory structure; README files become section indexes
• Smart labeling — page titles resolve via frontmatter title → first H1 → filename; missing titles are injected automatically
• No title duplication — when a page has both a frontmatter title and an H1, the redundant H1 is suppressed at render time
• Gitignore-aware — respects .gitignore and common technical directories (node_modules, dist, etc.)
• MDX support — local, relative, and npm component imports work out of the box
• Framework adapters — opt-in React, Vue, Svelte, and Solid integrations
• Strict CI mode — fails on broken links, duplicate slugs, missing labels, and frontmatter errors
• Static build — fea-docs build emits deployable output with copied assets
• Session cache — repeated runs reuse the Starlight runtime; only reinstalls on config change
• No telemetry — fully local and private

Usage

Always use npx fea-docs@latest to ensure you get the newest version. Without @latest, npx may use a previously cached version.

# Start a live preview from the current directory
npx fea-docs@latest start

# Start on a specific port and open the browser
npx fea-docs@latest start --port 3000 --open

# Start with a custom base path (for subpath hosting)
npx fea-docs@latest start --base /my-repo

# Build static output for deployment
npx fea-docs@latest build --out-dir ./dist

# Enable strict validation (default in build mode)
npx fea-docs@latest start --strict

# Enable a framework adapter
npx fea-docs@latest start --framework react

# Share via Tailscale (requires explicit --expose consent)
npx fea-docs@latest start --tailscale-serve --expose

# Prevent macOS sleep during a long session
npx fea-docs@latest start --caffeinate

# Use both together (macOS + Tailscale sharing)
npx fea-docs@latest start --caffeinate --tailscale-serve --expose

Port precedence

--port flag > FEA_DOCS_PORT environment variable > config file port > default 4321

Config file

Pass an explicit config file with --config <path>. No implicit config search is performed.

// fea-docs.config.mjs
export default {
  base: '/my-repo',
  ignore: ['**/drafts/**'],
  port: 3000,
  frameworks: ['react'],
  aliases: {
    '@components': './src/components',
  },
};

Base path deployments

When deploying docs under a subpath (for example GitHub Pages project sites at https://<user>.github.io/<repo>/), set base to /<repo> either in config or via --base on start/build. This ensures redirects, internal links, and static asset URLs are generated correctly for that mount point.

How it works

On first run, fea-docs materializes an ephemeral Starlight project under .fea-docs/app/ inside your working directory, installs its dependencies there, and starts the Astro dev server. Your content is symlinked into the generated project so edits are reflected live.

During the scan phase, any file missing a frontmatter title has one injected automatically (derived from the first H1 or the filename). This mutation is idempotent and required by Starlight's content schema. If a file already has both a title in frontmatter and a matching H1, the H1 is suppressed at render time to avoid visual duplication.

The .fea-docs/ directory should be gitignored. A session cache fingerprints your config so subsequent runs skip the install step.

Example

The example/ directory contains a minimal repository you can use to try fea-docs locally:

cd example
npx fea-docs@latest start

Requirements

• Node.js 18 or later
• npm (used to install the ephemeral Starlight runtime on first run)

Contributing

git clone https://github.com/your-org/fea-docs
cd fea-docs
npm install

# Type-check
npm run typecheck

# Run tests
npm test

# Watch mode
npm run test:watch

# Compile
npm run build

Running locally

After building, link the package globally so you can invoke fea-docs directly:

npm run build
npm link

# Run against any directory on your machine
cd /path/to/your/project
fea-docs start

Alternatively, run without linking using node:

npm run build
node dist/cli.js start

To test changes without rebuilding every time, use watch mode alongside node:

# Terminal 1 — recompile on save
npm run dev

# Terminal 2 — run the CLI
node dist/cli.js start

When you are done, remove the global link:

npm unlink -g fea-docs

Project structure

src/
  cli.ts                     Entry point (bin)
  types.ts                   Shared TypeScript types
  config/resolver.ts         Config merge (CLI > env > file > defaults)
  content-graph/             File discovery and page parsing
  navigation/                NavTree builder
  link-asset/                Link and asset resolver
  strict/                    CI validation rules
  runtime/                   Ephemeral Starlight app lifecycle
  build/                     Static asset export
  cache/                     Session fingerprint cache
  cli/commands/              start, build, setup subcommands

Tests live alongside source in src/__tests__/ and cover all deep modules through their public interfaces.

License

MIT