Configuration#

FlyDocs is configured via flydocs.toml in the project root. All fields are optional except [project] name. If no config file is found, flydocs uses sensible defaults.

For backward compatibility, flydocs also reads docs.toml if flydocs.toml is not present.

[project]#

Core project settings.

[project]
name = "My Project"
url = "https://example.github.io/my-project/"
description = "Project documentation."
docs_dir = "docs"
site_dir = "public"
base_path = "/my-project"

[theme]#

Visual appearance settings. FlyDocs follows PatternFly design standards — colors are not user-configurable. The theme section controls mode, branding, and optional UI elements.

[theme]
mode = "auto"
palette = "flydocs-dark"
variant = "felt"
logo = "docs/assets/logo.svg"
favicon = "docs/assets/favicon.svg"
tagline = "Your project tagline"
google_fonts = true

[theme.banner]#

Optional announcement banner displayed at the top of every page. Uses the PatternFly Banner component.

[theme.banner]
text = "Beta — APIs may change without notice."
color = "blue"
url = "https://github.com/example/releases"

[readme]#

docs/index.md is the OKF homepage. README.md is a separate entrypoint for the repository home page. It carries the project title, description, and badges, plus a link to the documentation. It does not copy the index, and it does not use a symlink.

GitHub reads README.md from the repository root. Links there use paths from that root, such as docs/index.md. The docs pages keep their own docs-relative links. The two files are allowed to differ.

[readme]
enabled = true
output = "README.md"

When enabled, flydocs build writes that entrypoint. flydocs readme does the same at any time. The title and description come from the index frontmatter, then from [project]. When url is set, the README links to the published site and to {docs_dir}/index.md. Frontmatter stays in the index. The README does not include it.

A README.md that is already a symlink to {docs_dir}/index.md is left unchanged. A symlink loop, a symlink that leaves the repository, or a symlink to any other file is an error. That layout is not recommended: GitHub shows the OKF frontmatter as a table and resolves links from the repository root, so docs-relative links miss docs/.

[[badges]]#

Badges are defined as an array of tables. Each badge appears in the site header and can be referenced inline in markdown content.

[[badges]]
id = "version"
label = "v0.1.0"
url = "https://github.com/example/releases"
img = "https://img.shields.io/badge/version-v0.1.0-orange"

[[badges]]
id = "docs"
label = "Docs"
url = "https://example.github.io/my-project/"
img = "https://img.shields.io/badge/docs-online-blue"

Inline Badge References#

Use badges anywhere in your markdown content:

Current version: {{badge:version}}

All project badges: [![docs](https://img.shields.io/badge/docs-online-blue)](https://aknochow.github.io/flydocs/) [![aknochow/flydocs](https://img.shields.io/github/actions/workflow/status/aknochow/flydocs/test.yml?label=aknochow%2Fflydocs)](https://github.com/aknochow/flydocs) [![OKF](https://img.shields.io/badge/OKF-v0.2-blueviolet)](https://aknochow.github.io/flydocs/okf/) [![PatternFly](https://img.shields.io/badge/PatternFly-v6-EE0000)](https://www.patternfly.org/)

• {{badge:id}} expands to a single badge as a linked image.
• [![docs](https://img.shields.io/badge/docs-online-blue)](https://aknochow.github.io/flydocs/) [![aknochow/flydocs](https://img.shields.io/github/actions/workflow/status/aknochow/flydocs/test.yml?label=aknochow%2Fflydocs)](https://github.com/aknochow/flydocs) [![OKF](https://img.shields.io/badge/OKF-v0.2-blueviolet)](https://aknochow.github.io/flydocs/okf/) [![PatternFly](https://img.shields.io/badge/PatternFly-v6-EE0000)](https://www.patternfly.org/) expands to the full badge bar.

README Badge Markdown#

Generate copy-pasteable badge markdown for your README:

flydocs badges

[sidebar]#

Controls the sidebar navigation behavior. By default, all sections are expanded.

[sidebar]
expanded = true

Per-Section Overrides#

Override the default expand state for individual sections using [sidebar.overrides]. The key is the section title from [[nav]], and the value is a boolean.

[sidebar]
expanded = true

[sidebar.overrides]
"Reference" = false
"Help" = false

In this example, all sections start expanded except "Reference" and "Help", which start collapsed. Users can still click to expand them.

The active section (containing the current page) is always expanded regardless of the override setting.

Examples#

Expand everything (default):

[sidebar]
expanded = true

Collapse everything except the active section:

[sidebar]
expanded = false

Expand everything but collapse specific sections:

[sidebar]
expanded = true

[sidebar.overrides]
"API Reference" = false
"Changelog" = false

Collapse everything but expand specific sections:

[sidebar]
expanded = false

[sidebar.overrides]
"Getting Started" = true
"Guides" = true

[[nav]]#

Explicit navigation structure. When present, the sidebar follows this order exactly. When absent, flydocs auto-generates navigation from the directory structure and OKF frontmatter.

[[nav]]
"Getting Started" = [
    { "Introduction" = "index.md" },
    { "Quick Start" = "quickstart.md" },
]

[[nav]]
"Guides" = [
    { "Installation" = "guides/installation.md" },
    { "Configuration" = "guides/configuration.md" },
]

[[nav]]
"Reference" = [
    { "API" = "reference/api.md" },
    { "CLI" = "reference/cli.md" },
]

Each [[nav]] entry defines a collapsible section in the sidebar. The key is the section title. The value is an array of page entries, where each entry maps a display label to a markdown file path relative to docs_dir.

Auto-Generated Navigation#

When [[nav]] is omitted, flydocs generates navigation from the file system:

1. Top-level directories become sections (capitalized).
2. Files within each directory become entries.
3. Display labels are derived from OKF title frontmatter, falling back to the filename.
4. Entries are sorted by OKF weight (ascending), then alphabetically.
5. index.md files become the first entry in their section.

Complete Example#

[project]
name = "OGO"
url = "https://aknochow.github.io/ogo/"
docs_dir = "docs"
site_dir = "public"

[theme]
mode = "auto"
variant = "felt"
tagline = "OpenShell Gateway Operator"
google_fonts = true

[theme.banner]
text = "Alpha — APIs may change without notice."
color = "gold"

[sidebar]
expanded = true

[sidebar.overrides]
"Reference" = false

[[badges]]
id = "version"
label = "Version"
url = "https://github.com/aknochow/ogo/releases"
img = "https://img.shields.io/badge/version-v0.1.0-orange"

[[badges]]
id = "docs"
label = "Docs"
url = "https://aknochow.github.io/ogo/"
img = "https://img.shields.io/badge/docs-online-blue?logo=readthedocs&logoColor=white"

[[nav]]
"Overview" = [
    { "Introduction" = "index.md" },
]

[[nav]]
"Concepts" = [
    { "Overview" = "concepts/index.md" },
    { "Gateway" = "concepts/gateway.md" },
    { "Sandbox" = "concepts/sandbox.md" },
]

[[nav]]
"Guides" = [
    { "Quickstart" = "guides/quickstart.md" },
]

[[nav]]
"Reference" = [
    { "OpenShellGateway" = "reference/openshellgateway.md" },
]

Environment Variables#