This page shows how to run a Docgeni doc site in an existing or new project. See other guides for advanced configuration.

Requirements

Install Node.js (LTS recommended) and npm, ≥ 10:

bash
node -v

Option 1: CLI init (recommended)

In an existing Angular project or empty folder, run one of:

bash
npx @docgeni/cli init

bash
docgeni init

bash
ng add @docgeni/cli

You will typically:

1. Choose site mode: full (home page) or lite (default, docs only)
2. Set the docs folder (default docs)

Then:

bash
npm run start:docs

Open http://127.0.0.1:4600.

Lite mode preview:

Option 2: GitHub template

For a full demo out of the box, use docgeni-template (full mode, sample library alib):

1. Open the template repo
2. Click Use this template
3. Clone, npm install, then npm run start:docs

Option 3: Manual setup

For full control over dependencies and config.

Install

bash
npm i @docgeni/cli @docgeni/template --save-dev

bash
yarn add @docgeni/cli @docgeni/template -D

Add scripts to package.json:

json
{
  "scripts": {
    "start:docs": "docgeni serve --port 4600",
    "build:docs": "docgeni build"
  }
}

Configuration

Create a config file at the project root. Supported names include .docgenirc.js, .docgenirc.ts, .docgenirc.yaml, .docgenirc.yml, .docgenirc.json, and more—use any one format. Example with .docgenirc.js:

ts
/**
 * @type {import('@docgeni/core').DocgeniConfig}
 */
module.exports = {
    mode: 'lite',
    title: 'Docgeni',
    repoUrl: 'https://github.com/docgeni/docgeni',
    navs: [
        null,
        {
            title: 'GitHub',
            path: 'https://github.com/docgeni/docgeni',
            isExternal: true,
        },
    ],
};

Start writing docs

By default, Docgeni watches Markdown files in the docs directory. Create a minimal page first:

bash
mkdir -p docs
echo '# Hello Docgeni' > docs/getting-started.md

Run npm run start:docs and open http://127.0.0.1:4600.

Ignore generated output

Add to .gitignore:

.docgeni/site

Component documentation

If your repo has an Angular library, init will try to wire it in. Components without overview or examples are hidden from the nav.

Minimal example: for a button folder, add button/doc/{locale}.md (match your defaultLocale, e.g. en-us.md):

markdown
---
title: Button
subtitle: Button
---

## When to use

A button triggers an immediate action.

Preview:

See Component documentation for overview, examples, api, and <example />.