Configuration #

undox is configured via a undox.yaml file in your project root.

Full Example #

site:
  name: "My Documentation"
  url: "https://docs.example.com"
  output: "_site"

theme:
  name: default

sources:
  - name: docs
    title: Docs
    url_prefix: /
    local:
      path: ./content

Site Configuration #

The site section defines global settings for your documentation site.

site:
  name: "My Documentation"   # Site title (appears in header)
  url: "https://docs.co.com" # Base URL for your site
  output: "_site"            # Output directory (default: _site)

Theme Configuration #

Specify the location to the theme you want to use; this can be a git repository or a local path.

theme:
  location:
    git: https://github.com/undox-rs/theme-default#main

or

theme:
  location:
    path: ./path/to/theme

You can specify a theme name instead of a location, and undox will look for that theme at https://github.com/undox-rs/theme-<name>:

theme:
  name: default # aka https://github.com/undox-rs/theme-default

If the theme takes any settings, you can specify them in a settings key:

theme:
  location: # ...
  settings:
    logo:
      light: ./assets/logo/wordmark_light.png
      dark: ./assets/logo/wordmark_dark.png

Sources #

Sources define where your documentation content comes from. This is the key to undox's multi-repo support.

sources:
  - name: docs
    title: Docs
    url_prefix: /
    local:
      path: ./content

Local Source #

Pull content from a local directory:

sources:
  - name: docs
    url_prefix: /
    local:
      path: ./docs/content

Remote Source #

Pull content from a remote repository, or another path on your filesystem:

sources:
  - name: api
    title: API
    url_prefix: /api
    remote:
      path: ../local-api-repo/docs
  - name: theme
    title: Default Theme
    url_prefix: /theme
    remote:
      git: https://github.com/undox-rs/theme-default#main

Using a path is similar to using a local source, but treats the source as remote, just like a Git URL.

Remote Git Sources #

You can specify Git sources via either a string, or a full Git configuration object. If you need to specify a subpath, use the configuration object form:

sources:
  - name: api
    remote:
      git: https://github.com/example/api-repo#main
    url_prefix: /api 
  - name: cli
    remote:
      git:
        url: https://github.com/example/cli-repo
        ref: main           # Branch, tag, or commit
        path: docs/      # Path within the repo
    url_prefix: /cli

undox clones the repository to .undox/cache/git/ and uses the specified path as the content source. The cache is reused between builds - run with a fresh clone by deleting the cache directory or running undox clean.

SSH Authentication: For private repositories, ensure your SSH keys are configured. undox uses your system's SSH agent.

Multiple Sources #

Combine documentation from multiple locations:

sources:
  - name: main
    url_prefix: /
    local:
      path: ./content

  - name: cli
    url_prefix: /cli
    remote:
      path: ../cli-repo/docs

  - name: api
    url_prefix: /api
    remote:
      git: https://github.com/undox-rs/undox-api#main

Each source becomes a section in your navigation. See the multi-repo guide for more details.

Custom Navigation #

By default, navigation is auto-generated from your file structure, sorted alphabetically. To customize the order or grouping, use the nav field:

sources:
  - name: docs
    local:
      path: ./content
    nav:
      - section: Getting Started
        items:
          - quickstart.md
          - installation.md
      - section: Guide
        items:
          - configuration.md
          - advanced/
      - about.md

Nav items can be:

• Filenames: installation.md - link to a specific page
• Directories: advanced/ - auto-expand all pages in that directory
• Sections: Group items under a heading

Auto-generated navigation also automatically merges files with matching directories. For example, if you have both configuration.md and a configuration/ directory, the directory contents become children of the configuration.md link rather than a separate section.

You can also use titled items for custom link text:

nav:
  - Welcome: index.md
  - section: Guides
    items:
      - Getting Started: quickstart.md
      - Config Reference: configuration.md

Child sources can specify their own navigation configuration in their local config file.

Links with Children #

When a page has related sub-pages, you can nest them as children of the parent link. This creates a hierarchical navigation where the children appear indented under the parent:

nav:
  - section: Guide
    items:
      - path: configuration.md
        title: Configuration  # optional
        children:
          - configuration/root.md
          - configuration/child.md
      - other-guide.md

This renders as:

• Guide (section heading)
  • Configuration (clickable link to configuration.md)
    • Root Config (child link, indented)
    • Child Config (child link, indented)
  • Other Guide

Children can be any nav item type, including sections or other links with children, allowing for deeply nested navigation structures.

Dev Server Configuration #

Configure the development server behavior:

dev:
  live_reload: true    # Enable/disable browser auto-refresh (default: true)
  watch:
    poll: false        # Use polling instead of native FS events
    poll_interval_ms: 500   # Poll interval when polling is enabled
    debounce_ms: 100   # Debounce delay for file changes

Live Reload #

When running undox serve --watch (the default), the browser automatically refreshes when files change. Disable this with:

dev:
  live_reload: false

File Watching #

By default, undox uses native filesystem events for efficient change detection. On some systems (Docker volumes, network filesystems, WSL), native events may be unreliable. Switch to polling mode:

dev:
  watch:
    poll: true
    poll_interval_ms: 1000  # Check every second

Environment Variables #

You can use environment variables in your config:

site:
  url: ${SITE_URL}