PatternFly#
FlyDocs generates static HTML sites styled with PatternFly, Red Hat's open source design system. This document captures which PatternFly features flydocs uses, how, and why.
CSS-Only Approach#
FlyDocs uses PatternFly as pure CSS — no React, no JavaScript
framework. The @patternfly/patternfly npm package provides the
core CSS, which flydocs vendors as patternfly-base.css shipped
with the Python package.
Two CSS files are loaded per page:
| File | Source | Purpose |
|---|---|---|
patternfly-base.css |
Vendored from @patternfly/patternfly |
Reset, tokens, component styles |
flydocs.css |
FlyDocs package | Layout, sidebar, content typography |
Semantic Tokens#
FlyDocs uses PatternFly semantic tokens for all color values. Semantic tokens auto-adapt between light and dark themes — no separate dark stylesheet needed.
Token naming convention:
--pf-t--[scope]--[component]--[property]--[concept]--[variant]--[state]
Key tokens used by flydocs:
| Purpose | Token |
|---|---|
| Body background | --pf-t--global--background--color--primary--default |
| Header background | --pf-t--global--background--color--sticky--default |
| Borders | --pf-t--global--border--color--default |
| Body text | --pf-t--global--text--color--regular |
| Secondary text | --pf-t--global--text--color--subtle |
| Links | --pf-t--global--text--color--link--default |
| Link hover | --pf-t--global--text--color--link--hover |
| Muted text | --pf-t--global--text--color--placeholder |
| Code blocks | --pf-t--global--background--color--secondary--default |
| Brand accent | --pf-t--global--color--brand--default |
Never use tokens ending in a number (palette/base tokens). Only use semantic tokens.
Dark / Light / Auto Mode#
PatternFly dark mode is activated by adding pf-v6-theme-dark to
the <html> element. All semantic tokens resolve to dark values
when this class is present.
FlyDocs supports three modes via [theme] mode in flydocs.toml:
| Mode | Behavior |
|---|---|
dark |
Sets class="pf-v6-theme-dark" on <html>. No toggle. |
light |
No class (PatternFly default is light). No toggle. |
auto |
JavaScript checks prefers-color-scheme media query. Adds a toggle button in the masthead. Persists user preference to localStorage. |
The dark theme CSS is bundled inside patternfly-base.css — no
separate stylesheet is needed.
Palettes#
FlyDocs ships a custom dark palette (flydocs-dark) with deeper
colors than stock PatternFly. This is the default palette.
| Palette | Description |
|---|---|
default |
Stock PatternFly colors |
flydocs-dark |
Deeper dark theme with richer contrast (default) |
Set via [theme] palette in flydocs.toml:
[theme]
palette = "flydocs-dark"
Palettes only affect dark mode — light mode uses stock PatternFly colors regardless of the palette setting.
When [theme] variant = "felt" (the default), the flydocs-dark
palette still deepens dark backgrounds, but it leaves brand and
link tokens alone. Red Felt recolors the accent. It does not
recolor links. flydocs-felt takes Felt's shape and puts the
accent tokens back on PatternFly blue, in light and dark. The
flydocs-dark palette is not required for that blue.
Project Felt#
PatternFly's Project Felt theme is a Red Hat–aligned variant: red brand accents and pill-shaped borders on buttons and controls. It is built on the same design tokens as classic PatternFly, so enabling it does not require markup changes.
Felt is independent of light/dark mode. PatternFly activates the
red theme by adding pf-v6-theme-felt to <html>, alongside
pf-v6-theme-dark when dark mode is on. FlyDocs also adds
flydocs-variant-felt.
Set via [theme] variant in flydocs.toml:
[theme]
variant = "felt"
| Variant | HTML classes | Description |
|---|---|---|
felt |
pf-v6-theme-felt flydocs-variant-felt |
Project Felt. Red accents, pill-shaped controls. This is the default. |
flydocs-felt |
pf-v6-theme-felt flydocs-variant-flydocs-felt |
Same Felt shapes, with PatternFly blue instead of red. |
flydocs-classic |
flydocs-variant-flydocs-classic |
Previous FlyDocs theme. Square controls, blue accents. default is accepted as an alias. |
FlyDocs custom chrome uses PatternFly's control radius, so buttons,
search, and nav chips become pills under Felt. Code blocks, the
theme panel, and the table of contents use the medium radius.
A pill radius on those wide boxes turns them into capsules. The
masthead rule, project name, current nav item, selected
color-scheme button, and page title underline use the accent
color: Red Hat red for felt, PatternFly blue for flydocs-felt.
Body links stay on the link token. flydocs-classic does not use
that accent chrome.
Glass and high-contrast PatternFly modes are vendored in
patternfly-base.css but are not yet exposed as FlyDocs config
options. Glass also needs branded background images that FlyDocs
does not ship.
PatternFly Components Used#
Content (pf-v6-c-content)#
The content wrapper class that provides PatternFly typography defaults for headings, paragraphs, lists, tables, and inline elements. Applied to the main content area.
Navigation (pf-v6-c-nav)#
Sidebar navigation using PatternFly nav classes:
| Class | Purpose |
|---|---|
.pf-v6-c-nav |
Nav container |
.pf-v6-c-nav__list |
Top-level nav list |
.pf-v6-c-nav__item |
Nav item |
.pf-v6-c-nav__link |
Nav link |
.pf-v6-c-nav__subnav |
Expandable sub-navigation |
.pf-m-expandable |
Modifier for expandable sections |
.pf-m-expanded |
Modifier for open sections |
.pf-m-current |
Modifier for active page |
Expandable sections use <details>/<summary> elements for
CSS-only expand/collapse without JavaScript.
Banner (pf-v6-c-banner)#
Optional announcement banner at the top of every page:
<div class="pf-v6-c-banner pf-m-blue pf-m-sticky">
This is alpha software. APIs may change.
</div>
Supports PatternFly banner colors: blue, red, green, gold.
Configured via [theme.banner] in flydocs.toml.
FlyDocs Layout Classes#
FlyDocs uses its own flydocs-* prefixed classes for the page
layout. This avoids collision with PatternFly component classes
while using PatternFly semantic tokens for all color values.
| Class | Purpose |
|---|---|
.flydocs-masthead |
Fixed top header |
.flydocs-brand |
Brand name / logo link |
.flydocs-tagline |
Project tagline in header |
.flydocs-badges |
Badge bar in header |
.flydocs-layout |
Flexbox container for sidebar + main |
.flydocs-sidebar |
Sidebar navigation panel |
.flydocs-main |
Main content area |
.flydocs-content |
Content wrapper (also uses pf-v6-c-content) |
.flydocs-sidebar-toggle |
Sidebar collapse toggle |
What FlyDocs Brings Itself#
PatternFly provides the design system but not everything a docs site needs:
| Feature | PatternFly provides | FlyDocs provides |
|---|---|---|
| Colors and tokens | Yes | — |
| Dark/light themes | Toggle mechanism | JS for auto mode + toggle button |
| Page layout | CSS classes | HTML structure + responsive JS |
| Navigation | CSS classes + active state | Sidebar builder from config/OKF |
| Code blocks | Container styling only | Syntax highlighting (Pygments) |
| Copy button | — | JS copy-to-clipboard on <pre> blocks |
| Search | Input UI component only | Client-side search engine |
| Banner | Full component | Config-driven rendering |
| Responsive | Breakpoint tokens | Sidebar collapse + hamburger toggle |
Responsive Design#
At viewport widths <= 768px:
- Sidebar is hidden by default
- A hamburger toggle button appears in the masthead
- Tapping the toggle slides the sidebar in as an overlay
- Tapping outside the sidebar or pressing Escape closes it
This requires ~20 lines of JavaScript for the toggle, close-on- backdrop, and close-on-escape behaviors. No PatternFly JavaScript dependency.
Fonts#
PatternFly uses Red Hat Text (body) and Red Hat Mono (code). By
default, flydocs loads these from Google Fonts CDN. Set
google_fonts = false in [theme] for air-gapped deployments —
the font stack falls back to system fonts.