Workspace configuration

A diplodocus.yaml file uses YAML to declare the repositories, packages, and authored content that belong in one site. Diplodocus does not discover nearby packages or documents. Start from the working examples/monorepo/diplodocus.yaml configuration and adapt its paths and names. The root diplodocus.yaml shows an authored documentation site without API packages. See the quick start for commands to build either site.

The top-level lists are repositories, packages, content, concepts, and relationships. Field names use kebab-case. Diplodocus rejects unknown fields, duplicate keys, and configurations containing more than one YAML document. Use --config PATH to select another filename, including one ending in .yml. TOML configurations and singular top-level collection keys are no longer supported.

Repositories and packages

Each repository path is relative to the configuration directory; it may point to a sibling checkout. A package names its repository and gives a path within it. Package metadata and extraction targets are relative to the package. Declare targets: [] for a package with no API extraction.

Python extraction reads source and package metadata. R reads source, package metadata, and checked-in Rd files. Julia reads Project.toml, an explicit .jl entry file, and its literal includes, with native completion when needed. Rust reads Cargo metadata and compiler-produced rustdoc JSON for an explicit library entry file. Native runtimes verify executable API examples. The extraction guide describes the supported inputs and limits.

Repository links

Automatically discovered package pages use repository links for existing local targets that are not site pages or accepted downloads. For GitHub, set the repository's url to https://github.com/OWNER/REPO. Diplodocus constructs blob links for files and tree links for directories, using the declared revision or the observed Git commit. It does not guess a default branch. An optional .git suffix and trailing slash are accepted.

For other hosts, supply source-link-template. The template must contain {revision} and {path}. Diplodocus encodes the revision as one URL segment and encodes each component of the canonical repository-relative path. An optional {kind} expands to blob for files or tree for directories; directory links require it in a custom template. Unknown placeholders are errors when the fallback is needed. Templates with {line} use 1, but the template's fragment is replaced with the authored fragment or removed for a whole-file link. The resulting URL must use HTTP or HTTPS without credentials. For example:

repositories:
  - id: "core"
    path: ".."
    revision: "v1.2.0"
    source-link-template: "https://forge.example/team/core/{kind}/{revision}/{path}"

Repository links retain their canonical target and repository identity in the snapshot. Generation derives the URL from that snapshot without accessing the checkout or fetching the destination.

Package overviews

Every declared package has a landing page with a compact metadata block. Set the optional overview package field to select a .md file relative to that package's root. An authored package index takes precedence; otherwise, Diplodocus uses overview, the package-root README.md, or the package description, in that order. Selected files remain display-only. See package landing pages for examples.

Authored content

Each collection in content names a repository, source directory or file, mount, format, and owner. The project owner puts pages in project navigation; a package ID puts them under /packages/<slug>/. GFM collections read .md files. QMD collections read .qmd files and can include executable cells. Checked-in assets can live beside the pages that use them.

To publish an existing file such as CHANGELOG.md or CONTRIBUTING.md, set path to that file relative to its repository:

content:
  - id: changelog
    owner: project
    repository: core
    path: CHANGELOG.md
    mount: project
    format: gfm
  - id: contributing
    owner: project
    repository: core
    path: CONTRIBUTING.md
    mount: project
    format: gfm

These collections produce /project/CHANGELOG.html and /project/CONTRIBUTING.html. The mount remains a URL directory prefix; an empty mount puts the pages at the owner's documentation root. The source filename's case is preserved. A single-file collection reads only that page. Its links and images resolve from the original file's directory, which also provides the boundary for local assets. Links to other declared pages resolve to their generated URLs, including across collections. Preview watches the original file and its referenced assets, and snapshots retain the content for generation without the checkout.

Single files must match their collection's format: .md for gfm, .qmd for qmd, and .Rmd or .rmd for rmd. Execution and navigation settings work as they do for directory collections.

The monorepo example has one shared GFM guide and four extracted packages, including a compiler-backed Rust library. The root configuration mounts this GFM guide at /guide/ and keeps its QMD example under /examples/. See authored pages for supported syntax, links, and assets.

Collections include every page in the sidebar by default. For a generated catalog whose index already links to its entries, show only the collection's root index:

content:
  - id: datasets
    owner: project
    repository: docs
    path: generated/datasets
    mount: datasets
    format: gfm
    navigation: index

navigation accepts all (the default), index (only index.md, index.qmd, or index.Rmd at the collection root), and none (no sidebar links). The setting applies to project and package collections. It does not change page routes, rendered content, links, search entries, or sitemap inclusion. If the collection has no root index, index adds no sidebar links. The setting is stored in the snapshot, so generate retains it without the source checkout.

To give a project collection its own navbar tab and sidebar, declare a section:

presentation:
  sections:
    - label: "Reference"
      path: "reference/index.html"

The path names a generated, visible project index.html page. All project pages under that directory belong to the section and leave the Guide sidebar. Section directories must be distinct and cannot contain the Guide landing page. Tabs appear after Guide in declaration order, before package tabs.

Sidebar groups and nesting

Without an explicit sidebar, Diplodocus groups authored pages by their generated URL directories. The first directory level creates headings, and deeper pages appear in the same group. A directory's index page supplies the heading and appears first as Overview; otherwise, the directory name supplies the heading. Other pages follow in route order.

For explicit ordering, nested groups, and collapsible headings, set presentation.sidebar. Its item structure follows VitePress's sidebar configuration:

presentation:
  sidebar:
    - text: Introduction
      collapsed: false
      items:
        - text: What is Diplodocus?
          link: guide/index.html
        - text: Quick start
          link: guide/quick-start.html
    - text: Reference
      items:
        - text: Configuration
          link: guide/configuration.html
        - text: Authoring
          items:
            - text: Overview
              link: guide/authoring.html
            - text: Executable examples
              link: guide/execution.html

Every item needs text and either a link, nonempty items, or both. A group with a link has a clickable heading. Links name generated HTML routes relative to the site root, without a leading slash, even when the site uses clean URLs or a hosting prefix. They must identify existing, visible pages. External URLs, fragments, and source paths such as guide/index.md are not accepted.

Top-level groups appear beneath headings. Nested groups indent their children and add a vertical guide line. Items retain declaration order and may nest up to six levels, including the top level. Deeper trees fail validation.

Omitting collapsed creates an always-expanded group. Set collapsed: false to add a toggle that starts open, or collapsed: true to start closed. The current page's ancestor groups open automatically. Toggles work without JavaScript. During client-side navigation, Diplodocus remembers expanded and collapsed groups within each sidebar until the page is reloaded.

Different sidebars by directory

A sidebar list applies to every page. To configure only particular directories, use a map instead:

presentation:
  sidebar:
    /guide/:
      - text: Introduction
        collapsed: false
        items:
          - text: Overview
            link: guide/index.html
          - text: Quick start
            link: guide/quick-start.html
    /reference/:
      - text: Reference
        items:
          - text: Overview
            link: reference/index.html

Map keys start and end with / and refer to generated URL directories, independent of any hosting prefix. The longest matching directory wins. / provides a site-wide fallback; pages without a matching key keep automatic navigation. An empty list explicitly removes authored navigation for that sidebar. Package directories such as /packages/python/ also work.

An explicit sidebar replaces automatic authored groups and the automatic shared concepts group for matching pages. Package API trees still appear below it. Explicit links may include pages omitted by a collection's navigation setting; that setting controls automatic inclusion. Pages left out of the sidebar still render and remain searchable. Sidebar settings are stored in the snapshot, so generate can reproduce them without source checkouts.

Execution

Execution defaults to never. To allow it, set the collection to QMD and declare a Jupyter engine and kernel explicitly:

content:
  - id: "examples"
    owner: "project"
    repository: "diplodocus"
    path: "docs/examples"
    mount: "examples"
    format: "qmd"
    execution:
      mode: "execute"
      engine: "jupyter"
      kernel: "python3"
      declared-environment-inputs:
        - "devenv.lock"

Declared environment inputs are individual files relative to the repository. They contribute to provenance and execution cache keys; Diplodocus does not install or interpret them. Document metadata can restrict execution but cannot enable it when the collection forbids it. check never runs cells. extract, build, and serve may run authorized cells with your user permissions.

Presentation

An optional presentation mapping controls the site name, logo, link preview image, HTML description, public URL, and footer:

presentation:
  title: "Foo documentation"
  description: "Guides and API documentation for Foo."
  site-url: "https://example.com/docs/"
  canonical-url-style: "file"
  footer:
    docs-version: "v1.0.0"
    copyright: "© 2026 Foo contributors"
    licenses:
      - label: "MIT"
        url: "https://github.com/example/foo/blob/main/LICENSE"
    links:
      - label: "GitHub"
        url: "https://github.com/example/foo"
      - label: "Report an issue"
        url: "https://github.com/example/foo/issues"
    built-with: true

The title defaults to project.name. Diplodocus uses its built-in theme, which follows the visitor's system color preference. Visitors can choose System, Light, or Dark in the header's Theme selector, or in the navigation menu on phones. The browser remembers explicit choices across visits. With JavaScript disabled, the theme follows the system preference. Generated sites and portable snapshots keep the presentation metadata, so generate does not need the original configuration. Read about portable snapshots before separating extraction and generation.

Landing page

Add presentation.home to give the site root a full-width landing page. It shows the logo and title at the top left, beside the section links, search, and repository links. Documentation pages keep the branding in the same position at the top of the gray sidebar. Navigation keeps the header and sidebar mounted while page content updates. Navbar links keep the same positions when moving between the landing page and documentation.

presentation:
  home:
    tagline: "Four languages.\nOne home for docs."
    description: "Guides and API references for all your packages."
    guide: "guide/index.html"
    actions:
      - label: "Get started"
        path: "guide/quick-start.html"
      - label: "Read the guide"
        path: "guide/index.html"
        icon: "book-open"
    features:
      - title: "Shared documentation"
        description: "Link across your packages."
        path: "guide/authoring.html"

Mount your guide collection at guide to keep it separate from the homepage. guide sets the navbar's Guide destination. Action and feature paths name visible generated HTML pages, including .html, even when the site uses clean URLs. Diplodocus checks these destinations and renders links using the site's URL settings. The first action receives the primary button style.

Actions accept an optional icon: arrow-right, book-open, code, download, or terminal. The built-in SVG appears before the label and inherits the button's text color. Icons are decorative, so the label still supplies the accessible link name. All actions retain their trailing arrow. Omitting icon keeps the text-and-arrow appearance. Unknown icon names are rejected.

The hero uses the site title and optional logo. All text is plain text, and newlines in tagline separate heading lines. Actions and features can be omitted. If an authored page already occupies the site root, its body appears below the landing content, with its initial title supplied by the hero. Without presentation.home, the root retains the documentation layout.

Branding

To add a logo before the title in the leftmost navbar link, declare an image in one of your repositories:

presentation:
  logo:
    repository: "docs"
    path: "assets/logo.svg"

repository must match a declared repositories ID. path is relative to that repository's root and must name an SVG, PNG, or JPEG file. The image can live outside a content collection. Use forward slashes without leading slashes or . or .. components. Symlinks must stay inside the repository.

Diplodocus validates and embeds the image in the snapshot, so generation needs no source checkout. The logo keeps its proportions within the navbar and shares the title's link to the homepage. The title supplies the accessible link name. Omitting presentation.logo leaves the navbar with the title alone. serve watches the logo file and rebuilds when it changes.

To use a shared image when people post links to your documentation, set site-url and declare an Open Graph image:

presentation:
  open-graph:
    repository: "docs"
    path: "assets/og.png"
    alt: "Foo documentation, with the project mascot beside an open book."

The image must be a PNG or JPEG inside the declared repository. alt describes what the image contains and must not be empty. A 1200 by 630 pixel image works well for a wide preview. The image can live outside content collections and follows the same path and symlink rules as the navbar logo.

Every generated HTML page receives Open Graph metadata and a large-image Twitter card. The preview uses that page's title and canonical URL, the site name and description, and the shared image with its dimensions and alt text. Image URLs are absolute and include any hosting prefix from site-url. Diplodocus validates and stores the image in the snapshot, so generate needs no source checkout. serve watches the image for changes. Omitting the mapping omits social preview metadata.

The footer appears at the bottom of every page. All its fields are optional, and omitting the mapping produces no footer. docs-version is a free-form label such as v1.0.0, dev, or main; it identifies the documentation release or branch independently of individual package versions. Diplodocus does not infer the label or copyright notice from package metadata or the build date.

copyright supplies the complete notice, including the symbol, years, and holder. licenses links to alternative licenses for the site's content and joins them with "or". Package-specific licenses remain on their package pages. links supplies project links in display order. Each license or project link requires a text label and an absolute HTTP or HTTPS url without credentials or whitespace. Footer text is escaped rather than parsed as Markdown or HTML. built-with defaults to false; setting it to true adds a linked "Built with Diplodocus" credit.

Set site-url to generate sitemap.xml, robots.txt, and canonical links in HTML pages. It must be an absolute HTTP or HTTPS URL without credentials, query parameters, fragments, or whitespace. Include the hosting prefix when deploying under a subdirectory. Diplodocus treats the URL as a directory root, whether or not you include its trailing slash. Omitting site-url omits all three forms of crawler metadata.

The sitemap lists the homepage, authored pages, package overviews, API pages, and concepts. It follows search visibility: public and internal package pages appear, and hidden package pages do not. Assets do not appear. Entries contain URLs only; Diplodocus does not infer modification dates from build times.

canonical-url-style defaults to file, which retains generated filenames such as /docs/index.html and /docs/installation.html. Use clean when your host serves index pages at directory URLs and other HTML pages without their extension. For example, those URLs become /docs/ and /docs/installation. The Diplodocus documentation uses clean to match Cloudflare's default static asset routing. This setting changes page links, search results, sitemap URLs, canonical links, and Open Graph page URLs. Output filenames retain their file paths, and the local preview serves both clean URLs and generated file paths. Clean URLs require matching support from your host. Ambiguous routes, such as foo.html alongside foo/index.html, fail generation before site publication.

The generated robots.txt allows crawling and advertises the sitemap's full URL. Crawlers read this file from the host's root /robots.txt. For a site deployed under /docs/, add the generated Sitemap directive to the host's root robots file. A file at /docs/robots.txt does not provide crawler discovery. The first implementation writes one sitemap and rejects sites that exceed the sitemap protocol's URL count, file size, or URL length limits.

Return to the quick start or see the commands.