@davaux/docs-gen

A CLI tool (davaux-gen) that generates a complete, deployable Davaux docs site from your project's source artifacts — package READMEs, extra Markdown files, and project metadata. The output is a ready-to-run Davaux project with a generated layout, nav, and MDX pages.

Installation

npm install --save-dev @davaux/docs-gen

Setup

Create a docs-gen.config.ts at your project or monorepo root:

// docs-gen.config.ts
import { defineConfig } from '@davaux/docs-gen'

export default defineConfig({
  name: 'My Framework',
  description: 'Developer documentation',
  outDir: './docs',
  packages: ['packages/*'],          // glob: all immediate subdirectories
  pages: [
    {
      src: 'ROADMAP.md',
      out: 'roadmap',
      title: 'Roadmap',
    },
  ],
})

Then run:

npx davaux-gen

What gets generated

For the config above, davaux-gen produces a complete Davaux project:

docs/
├── package.json            ← davaux + @davaux/mdx deps, dev/build/start scripts
├── davaux.config.ts        ← mdx plugin, ssg config
├── tsconfig.json
└── src/
    └── routes/
        ├── _layout.tsx     ← sidebar nav auto-built from discovered packages
        ├── index.page.mdx  ← from root README.md (or a default welcome page)
        ├── roadmap.page.mdx
        └── packages/
            ├── session.page.mdx
            ├── cors.page.mdx
            └── ...

After generation, install and run:

cd docs
npm install
npm run dev       # dev server
npm run build     # static site → docs/out/

How content is sourced

Each package page is generated from the package's README.md. The frontmatter title is extracted from the first # Heading; description from the first paragraph. Both can be overridden in config.

Packages without a README.md still get a page — it uses the description field from package.json as a placeholder.

The root index.page.mdx is generated from the project's top-level README.md if one exists.

Re-running

Scaffold files (package.json, davaux.config.ts, tsconfig.json) are written once and never overwritten, so manual edits survive re-runs. Route files (_layout.tsx, .page.mdx) are always regenerated fresh.

Configuration reference

`DocsGenConfig`

Field	Type	Description
`name`	`string`	Site display name — used in the layout and page `<title>`
`description`	`string?`	Optional site tagline
`outDir`	`string`	Where to generate the site, relative to the config file
`packages`	`(string \| PackageSource)[]`	Package directories to document
`pages`	`ExtraPage[]?`	Extra Markdown pages (ROADMAP, CHANGELOG, etc.)
`basePath`	`string?`	Base path prefix for subdirectory deployments

`PackageSource`

Field	Type	Description
`path`	`string`	Path to the package directory, relative to the config file
`name`	`string?`	Override the display name (defaults to `name` in `package.json`)

`ExtraPage`

Field	Type	Description
`src`	`string`	Path to the `.md` source file, relative to the config file
`out`	`string`	Output path without extension, relative to `src/routes/`
`title`	`string?`	Override the auto-extracted frontmatter title
`description`	`string?`	Override the auto-extracted frontmatter description

Package glob expansion

The packages field supports a single-level * glob:

packages: ['packages/*']          // all immediate subdirectories of packages/
packages: ['packages/session']    // explicit single package
packages: [
  { path: 'packages/session', name: '@my-org/session' }  // with name override
]

pka integration

@davaux/docs-gen and @davaux/pka are complementary, not dependent:

davaux-gen → generates a human-readable docs site from source artifacts
davaux-pka → generates CLAUDE.md files for AI assistant context

Run them independently. A typical monorepo workflow:

npx davaux-pka     # regenerate CLAUDE.md files
npx davaux-gen     # regenerate the docs site

@davaux/pka is not listed as a dependency of @davaux/docs-gen.