@unterberg/nivel

Deterministic structure engine for documentation systems

@unterberg/nivel owns the docs runtime: Vike integration, MDX setup, docs-graph validation, route code generation, page shell rendering, and reusable docs UI primitives. The consumer stays thin and keeps its content, docs graph, visible Vike shell files, and theme files local.

What It Provides

• typed docs config and docs graph surfaces
• generated Vike docs pages from a single docs graph
• docs shell primitives such as navbar, sidebar, table of contents, pagination, search, and meta head wiring
• MDX support with built-in docs components and code-block tooling
• Tailwind v4 and daisyUI integration helpers
• a small CLI for consumer scaffolding and docs page generation

Install

pnpm add @unterberg/nivel react react-dom vike vike-react
pnpm add -D vite typescript @types/react @types/react-dom

vike and vite are peer dependencies. The package exposes a local nivel binary after install.

Set siteUrl in pages/+docs.ts to enable automatic sitemap.xml and robots.txt generation. Set robots: false to emit noindex, nofollow and a disallow-all robots.txt. V1 includes canonical docs routes from the docs graph plus normal filesystem-routed consumer pages. Consumer routes remapped only through custom +route.ts files are not included automatically.

Quick Start

Scaffold a consumer:

pnpm exec nivel init

Generate docs pages:

pnpm exec nivel prepare

Typical consumer scripts:

{
  "scripts": {
    "generate:docs": "nivel prepare",
    "predev": "pnpm generate:docs",
    "dev": "vike dev",
    "prebuild": "pnpm generate:docs",
    "build": "vike build",
    "pretypecheck": "pnpm generate:docs",
    "typecheck": "tsc --noEmit -p tsconfig.json"
  }
}

Consumer Shape

Keep these files local and visible in the consumer:

• docs/docs.graph.ts
• pages/+docs.ts
• pages/+config.ts
• pages/+Head.tsx
• pages/+Layout.tsx
• pages/+onCreateGlobalContext.ts
• pages/+Wrapper.tsx
• global.d.ts
• docs content, brand assets, and consumer CSS/theme files

Only pages/(nivel-generated) is engine-generated and should not be edited by hand.

docs/docs.graph.ts is the single source of truth for docs structure. Navbar and sidebar behavior come from that graph.

Minimal Setup

docs/docs.graph.ts

import type { DocsGraph } from '@unterberg/nivel'

export const docsGraph = {
  items: [
    {
      kind: 'section',
      id: 'docs',
      title: 'Docs',
      items: [
        {
          kind: 'page',
          id: 'gettingStarted',
          title: 'Getting Started',
          slug: 'getting-started',
          source: 'content/getting-started/content.mdx',
          description: 'Getting started with @unterberg/nivel.',
        },
      ],
    },
  ],
} satisfies DocsGraph

pages/+docs.ts

import type { DocsConfig } from '@unterberg/nivel'
import { docsGraph } from '../docs/docs.graph'

const docsConfig = {
  graph: docsGraph,
  siteTitle: 'My Docs',
  siteDescription: 'Documentation site powered by @unterberg/nivel.',
  siteUrl: 'https://docs.example.com',
  // robots: false,
  // customFonts: false,
  basePath: '/docs',
} satisfies DocsConfig

export default docsConfig

pages/+config.ts

import { createNivelVikeConfig } from '@unterberg/nivel/vike'
import type { Config } from 'vike/types'
import docsConfig from './+docs'

export { config }

const config: Config = {
  ...createNivelVikeConfig(docsConfig),
  prerender: true,
}

vite.config.mts

import { nivelTailwindVite } from '@unterberg/nivel/tailwind'
import vike from 'vike/plugin'

process.env.VIKE_CRAWL ??= JSON.stringify({ git: false })

export default {
  plugins: [nivelTailwindVite(), vike()],
}

pages/+Head.tsx

import { MetaHead } from '@unterberg/nivel/client'

export const Head = () => {
  return <MetaHead />
}

pages/+Layout.tsx

import { AppLayout } from '@unterberg/nivel/client'
import type { ReactNode } from 'react'

const Layout = ({ children }: { children: ReactNode }) => {
  return <AppLayout>{children}</AppLayout>
}

export default Layout

pages/+Wrapper.tsx

import type { ReactNode } from 'react'
import '../styles/global.css'

const Wrapper = ({ children }: { children: ReactNode }) => {
  return <>{children}</>
}

export default Wrapper

styles/global.css

@import '@unterberg/nivel/tailwind.css';
@import './theme.css';

@source '../pages';
@source '../docs';

CLI

nivel init [--root <path>] [--force]
nivel prepare [--root <path>]
nivel --help

• nivel init scaffolds the visible consumer files and patches the standard docs scripts in package.json
• nivel init --force overwrites scaffold-managed files if they already exist
• nivel prepare reads pages/+docs.ts and generates pages/(nivel-generated)

nivel init does not create or overwrite your brand assets or consumer-specific styling decisions beyond the initial scaffold. Theme and palette files stay consumer-owned.

Public Entry Points

| Entry | Purpose | | --- | --- | | @unterberg/nivel | main types, MDX components, shared utilities | | @unterberg/nivel/vike | engine-owned Vike config for the consumer's pages/+config.ts | | @unterberg/nivel/client | AppLayout, MetaHead, UserSettingsSync, DocsPage, and client stores | | @unterberg/nivel/mdx | MDX provider entry | | @unterberg/nivel/mdx/code-blocks | code-block components and transforms | | @unterberg/nivel/tailwind | nivelTailwindVite() helper | | @unterberg/nivel/daisyui-theme | daisyUI theme plugin surface | | @unterberg/nivel/runtime/node | lower-level runtime helpers for loading config, resolving docs, scaffolding, and codegen | | @unterberg/nivel/runtime/client | lower-level client runtime entry |

Notes

• basePath controls the public docs route prefix.
• contentDir is optional and defaults to docs.
• social.editLinkPathPrefix optionally prepends a repository-relative directory to GitHub edit links when the consumer root is nested inside the repository.
• customFonts is optional and defaults to true; set it to false in pages/+docs.ts to stop Nivel from injecting Inter so you can own fonts in consumer CSS.
• If you configure Algolia, apiKey must be a browser-safe search key.
• The repo validates this package through both the first-party docs app at packages/docs and the standalone fixture at tests/npm-consumer.