Runir Docs

Detailed installation and deployment guide for Runir.

Installation

This guide covers installation, building for production, and deployment options.

System requirements

Requirement Minimum
Node.js 18.0+
npm 9.0+

Install via npm

Install Runir globally
npm install -g @fezcode/runir

Or use npx to run without installing:

npx @fezcode/runir init
Initialize your docs
runir init

This creates runir.config.js and a docs/ directory with starter templates.

Start developing
runir dev

Your docs site is now running at http://localhost:3000.

Production build

Generate a fully static site:

runir build

This does two things:

  1. Generates the search index — scans all markdown files and creates the search data
  2. Builds the static site — compiles pages and optimizes assets into the out/ directory

Always use runir build, not next build directly. The search index must be generated before the site build.

Deployment

The out/ directory is a fully static site. Deploy it anywhere:

GitHub Pages
Push to GitHub and use the included workflow. Set `basePath` to your repo name (e.g., `"/my-repo"`).
Vercel / Netlify
Set build command to `runir build` and publish directory to `out`.
Any static host
Upload the `out/` directory to any static file server — S3, Cloudflare Pages, etc.

GitHub Pages setup

  1. Set basePath in runir.config.js to your repo name (e.g., "/my-repo")
  2. Add a GitHub Actions workflow (see the included .github/workflows/deploy-docs.yml template)
  3. Enable GitHub Pages in your repo settings, using "GitHub Actions" as the source

Troubleshooting

Assets return 404 (CSS, JS not loading)

If your site deploys but the page is unstyled or blank, and the browser console shows 404 errors for _next/static/ files, your basePath is wrong.

basePath must match the URL root where your hosting platform serves the out/ directory. For GitHub Pages, that's always "/your-repo-name" — nothing more, nothing less.

// Wrong — assets will 404
basePath: "/my-repo/docs"

// Correct — matches where GitHub Pages serves the files
basePath: "/my-repo"

The basePath tells Next.js where to find all assets (JS bundles, CSS, images). If it doesn't match the actual server path, every asset request will fail.

A quick way to verify: after running runir build, check the generated HTML. The <script> tags should have src paths that match your hosting URL. If your site is at example.com/my-repo/, the paths should start with /my-repo/_next/....