Configuration

UptoDocs is configured using a single file:

.github/uptodocs.yml

All configuration changes go through pull requests and are fully reviewable.

Full Example Configuration

# ================================
# UpToDocs Configuration File
# ================================
# This file controls how UpToDocs detects code changes
# and generates documentation updates.
#
# All changes proposed by UpToDocs are made via
# pull requests — nothing is auto-merged.
#
# Location: .github/uptodocs.yml
# ================================

docs:
  # --------------------------------
  # 1. Documentation Location
  # --------------------------------
  # Path inside the repository where documentation lives.
  # Common values: "docs", "content/docs", "website/docs"

  path: "docs"

  # --------------------------------
  # 2. Ignore Rules (optional)
  # --------------------------------
  # Files or folders that should never be documented.
  # Useful for internal utilities or scripts.

  ignore:
    - "src/internal/**"
    - "scripts/**"
    - "**/*.test.ts"
    - "**/*.spec.ts"

  # --------------------------------
  # 3. External Documentation Repo (Optional)
  # --------------------------------
  # Use this if your docs live in a separate repository.
  #
  # external:
  #   owner: "${owner}"
  #   repo: "my-docs-repo"
  #   path: "content/docs"

  # --------------------------------
  # 4. Organization-wide Aggregation (Enterprise)
  # --------------------------------
  # Aggregate documentation from multiple repositories
  # into a single documentation source.
  #
  # aggregate:
  #   - owner: "my-org"
  #     repo: "auth-service"
  #     path: "docs/api"
  #   - owner: "my-org"
  #     repo: "billing-service"
  #     path: "docs/api"

  # --------------------------------
  # 5. Documentation Framework
  # --------------------------------
  # Auto-detected by default.
  # Override only if detection is incorrect.
  #
  # Supported:
  # - nextra
  # - fumadocs
  # - docusaurus
  # - mintlify
  # - vitepress
  # - starlight
  # - gitbook
  # - plain-markdown

  framework: "fumadocs"

  # --------------------------------
  # 6. Diagram Generation
  # --------------------------------
  # Automatically generate Mermaid.js diagrams
  # for complex logic when applicable.
  #
  # Recommended: true (Beta feature)
  diagrams: true

  # --------------------------------
  # 7. Update Scope (Optional)
  # --------------------------------
  # Only update documentation for changes
  # occurring in these folders.
  #
  # update_scope:
  #   - "components"
  #   - "api"

  # --------------------------------
  # 8. Safety Limits (Pro / Enterprise)
  # --------------------------------
  # Prevent overly large or risky pull requests.
  #
  limits:
    # Maximum number of documentation files
    # allowed per PR.
    max_files: 3

    # Maximum total lines changed across all files.
    max_lines: 1000

  # --------------------------------
  # 9. Changelog Integration (Pro / Enterprise)
  # --------------------------------
  # Automatically update changelog entries
  # when documentation-relevant changes occur.
  #
  changelog:
    enabled: true
    path: "CHANGELOG.md"

  # --------------------------------
  # 10. Preview / Dry Run Mode (Pro / Enterprise)
  # --------------------------------
  # If enabled, UpToDocs will NOT open pull requests.
  # Instead, it will post preview comments only.
  #
  # Useful for testing configuration changes safely.
  #
  dry_run: false

  # --------------------------------
  # 11. Code Monitoring Scope (Pro / Enterprise)
  # --------------------------------
  # Only monitor code changes in these paths.
  #
  scope:
    path:
      - "src/**"

  # --------------------------------
  # 12. Monorepo Support (Pro / Enterprise)
  # --------------------------------
  # Map individual packages to their
  # respective documentation directories.
  #
  packages:
    "packages/ui":
      docs: "docs/design-system"

    "packages/backend":
      docs: "docs/api"
# ================================
# End of Configuration
# ================================

`docs.path`

docs:
  path: docs

Controls where documentation lives in the repository.

Default: docs/
Used to determine where new files are created
Existing structure is respected

External Documentation Repository

docs:
  external:
    owner: my-org
    repo: api-docs
    path: docs/api

Use this when:

Code lives in one repo
Documentation lives in another

UptoDocs will:

Read code from the source repo
Open documentation PRs in the external repo

This is useful for mono-org setups and shared documentation.

Advanced: Documentation Aggregation (Org Feature)

docs:
  external:
    aggregate:
      - owner: my-org
        repo: auth-service
        path: docs/api
      - owner: my-org
        repo: billing-service
        path: docs/api

For organizations with multiple services that contribute to a central documentation repository, the aggregate feature allows UptoDocs to:

Monitor changes across multiple repositories
Consolidate documentation updates into a single docs repo
Maintain service-specific documentation sections

`framework` Override

docs:
  framework: fumadocs

UptoDocs attempts to auto-detect your docs framework.

You can override detection if needed.

Supported frameworks:

fumadocs
nextra
docusaurus
mintlify
markdown
gitbook
vitepress

If your framework isn't listed, use markdown as a fallback. The tool will still generate valid MDX files.

`diagrams` Flag

docs:
  diagrams: true

When enabled, UptoDocs may generate simple visual diagrams (e.g. Mermaid) for complex logic.

Default: true
Pro Feature
Can be disabled for stricter documentation styles

Example use cases:

Flowcharts for complex business logic
Sequence diagrams for API interactions
State diagrams for lifecycle management
Architecture overviews for system components

Diagrams are only generated when the code complexity warrants visual explanation.

`ignore` Patterns

docs:
  ignore:
    - src/internal/**
    - scripts/**
    - "**/*.test.ts"
    - "**/*.spec.js"

Ignored paths are:

Never documented
Never scanned for drift
Never included in PRs

Patterns use glob-style matching.

Common patterns:

Test files: **/*.test.*, **/*.spec.*
Build tooling: *.config.js, *.config.ts
Internal utilities: src/internal/**, lib/utils/**
Scripts: scripts/**, bin/**
Generated code: dist/**, build/**

`scope` (Inclusion Patterns)

docs:
  scope:
    path:
      - "handlers/**"
      - "lib/**"
      - "app/api/**"

While ignore defines what to exclude, scope defines exactly what to include.

Default: If omitted, the entire repository is scanned (except ignored files)
Usage: Use this to restrict UptoDocs to specific directories (e.g., only document your src/core or lib folders)
Format: Supports glob patterns or specific directory paths

When to use scope:

Monorepos with multiple projects
Repositories where only certain folders contain public APIs
Large codebases where you want to focus documentation efforts
Gradual rollout of UptoDocs to specific areas first

Example: API-only documentation

docs:
  scope:
    path:
      - "src/api/**"
      - "src/routes/**"
  ignore:
    - "**/*.test.ts"

This configuration tells UptoDocs to:

Only document files in src/api/ and src/routes/
Ignore test files within those directories

`update_scope` (Change Types)

docs:
  update_scope:
    - components
    - api
    - config
    - hooks

Limit which types of code changes trigger documentation updates.

Available options:

components - React/Vue/Svelte components
api - REST/GraphQL endpoints
config - Configuration files and options
hooks - React hooks or composables
utilities - Utility functions and helpers
types - TypeScript types and interfaces

Default: All types are enabled if not specified.

This is useful when you want to document only specific aspects of your codebase, such as public APIs but not internal utilities.

Monorepo Support (`packages`)

docs:
  packages:
    "packages/ui":
      docs_path: "docs/design-system"
    "packages/backend":
      docs_path: "docs/api"
    "packages/shared":
      docs_path: "docs/shared"

Pro / Enterprise Feature

Designed for monorepos (Turborepo, Nx, Yarn/pnpm workspaces). This allows you to map specific source folders to distinct documentation destinations.

Configuration:

Key: The root folder of the package (e.g., packages/ui)
Value (docs_path): The destination folder for generated docs for that specific package
Priority: This setting overrides the global docs.path. If a file matches a package prefix, it goes here; otherwise, it falls back to the global path

Example workflow:

Developer updates packages/ui/src/Button.tsx
UptoDocs detects the change
Documentation PR updates docs/design-system/components/button.mdx
Developer updates packages/backend/src/api/users.ts
UptoDocs opens a separate PR updating docs/api/users.mdx

This keeps documentation organized by package boundary and prevents cross-contamination of concerns.

Smart Changelog

docs:
  changelog:
    enabled: true
    path: "CHANGELOG.md"

Pro Feature

UptoDocs can automatically append human-readable summaries to your changelog file.

Configuration:

enabled: Set to true to activate
path: The location of your changelog file (default: CHANGELOG.md)

When active, PRs created by UptoDocs will include a file update for CHANGELOG.md containing a concise bulleted list of the API changes and documentation updates performed in that run.

Example changelog entry:

## [Unreleased]

### Documentation Updates - 2024-01-15

- Added documentation for new `getUserProfile` API endpoint
- Updated `Button` component props documentation
- Documented breaking change in authentication middleware signature

This feature is particularly useful for:

Keeping stakeholders informed of API changes
Maintaining audit trails for compliance
Automating release note generation
Tracking documentation coverage over time

Safeguards & Limits

docs:
  limits:
    max_files: 5
    max_lines: 300

Control the volume of updates to save costs and reduce noise.

`max_files`

The maximum number of files UptoDocs will attempt to document in a single push event.

Plan limits:

Free Plan: Locked to 3 files
Pro Plan: Configurable (default 20)
Team/Enterprise Plan: Configurable (default 50)

If more files change than the limit allows, UptoDocs uses AI to curate the "Top N" most important files based on:

Complexity and impact
Whether the change is public-facing
Number of affected documentation pages
Historical importance (frequently accessed docs)

`max_lines`

Skip files exceeding this line count to prevent context-window errors on very large legacy files.

Recommended values:

Small projects: 500-1000
Medium projects: 300-500
Large codebases: 200-300

Files exceeding this limit are skipped with a warning comment in the PR.

Dry Run Mode

docs:
  dry_run: true

Useful for testing configuration without creating noise.

Modes:

true: UptoDocs will process the event and log the outcome (or comment on the commit) but will not create a Pull Request or modify any files
false (default): Normal operation. Pull Requests are created

Use dry run mode when:

Testing new ignore patterns
Validating monorepo package mappings
Experimenting with scope settings
Training team members on UptoDocs behavior
Debugging why certain files aren't being documented

Example dry run output:

🔍 DRY RUN MODE ENABLED

Would have created PR with the following changes:
- docs/api/users.mdx (23 lines changed)
- docs/components/button.mdx (12 lines changed)

Skipped files (ignored):
- src/internal/helpers.ts
- tests/api.test.ts

Configuration looks good! Set dry_run: false to enable.

Applying Configuration Changes

When you modify uptodocs.yml:

Commit the change
Push to your repository
Merge the PR (if required by branch protection)
New behavior applies automatically

No restarts. No dashboards. No hidden state.

Configuration changes take effect immediately on the next push event.

Configuration Validation

UptoDocs validates your configuration file on every run and will:

Comment on commits if the configuration is invalid
Provide clear error messages with suggestions
Fall back to safe defaults when possible

Common validation errors:

# ❌ Invalid: path must be a string
docs:
  path: ["docs", "documentation"]

# ✅ Valid: use scope instead
docs:
  path: docs
  scope:
    path:
      - "src/**"

Summary

One config file (.github/uptodocs.yml)
Fully version-controlled
Changes reviewed via PR
No hidden settings
Immediate effect on merge

If you can read YAML, you can control UptoDocs.

Pro tip: Start with minimal configuration and add complexity only as needed. The defaults are designed to work well for most projects.

On this page