Custom Documentation Sites in 2026: Building a Distinctive Dark-Themed Developer Reference on MkDocs Material Without Forking

Documentation is the public API surface of an open-source project; the difference between the default Material theme and a bespoke palette is the difference between "reads like every other project" and "reads like this specific project".

Sebastien Rousseau · Published 5 Jul 2026 · 11 min read

Why Documentation Aesthetics Matter in 2026

An open-source project's documentation site is the first surface an evaluator touches — before the README, before the release notes, before the code. In 2026, the density of developer-tool competition means that visual differentiation carries measurable weight: does the site feel like a curated product, or does it feel like a Jekyll-Cayman default from 2019? The felt distinction shapes adoption decisions before the reader has read a single sentence.

The reference standard for "distinctive open-source documentation" is docs.n8n.io — dark, polished, opinionated, immediately identifiable as n8n's. n8n runs on GitBook, a commercial SaaS. Most open-source projects, .dotfiles included, cannot justify GitBook's licensing but can invest in MkDocs Material customisation to achieve equivalent visual distinction on an open-source stack.

This article documents the migration of doc.dotfiles.io from Jekyll's Cayman theme (the default when GitHub Pages serves markdown without a MkDocs configuration) to a fully customised MkDocs Material theme with a terminal-green-on-near-black palette, custom typography, and a hero + card-grid landing page.

The Custom Docs Theme 2026 Architecture Lens

MkDocs Material's customisation surface has four distinct layers, each with different capabilities and constraints:

Key Documentation-UX Signals

Diagnosis: What "Default MkDocs Material" Leaves on the Table

An out-of-the-box MkDocs Material site with primary: teal, accent: teal and no extra_css is visually acceptable — but it is one of many thousand acceptable sites that look identically acceptable. The named presets are constrained to Google's Material Design palette; the sidebar, header, and content surface all read as "Material default".

For a project positioning itself as "an opinionated developer platform, not a library", the visual signal that the docs are the product's docs — not somebody else's — is a marketing surface, not a decoration. The lift is contained to three files:

• mkdocs.yml — palette selector configuration
• docs/stylesheets/extra.css — the actual palette + typography + component overrides
• docs/index.md — hero + card grid replacing the default index

No template overrides (custom_dir), no plugin authoring, no JavaScript. All the customisation lives in files MkDocs Material is explicitly designed to consume.

Remediation: The Three-File Custom Theme

mkdocs.yml Palette Configuration

The magic value that unlocks CSS-driven colours is primary: custom (and accent: custom). Under [data-md-color-scheme="slate"], MkDocs Material's dark variant, every component reads its colours from CSS custom properties that we get to define.

theme:
  name: material
  font:
    text: Inter
    code: JetBrains Mono
  palette:
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: custom
      accent: custom
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: custom
      accent: custom
  features:
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.footer
    - content.code.copy

extra_css:
  - stylesheets/extra.css

The navigation.tabs.sticky feature keeps the top-level navigation visible on scroll, which pairs with the hero + card grid to keep the site feeling like a product page rather than a scrolling article.

docs/stylesheets/extra.css — Palette + Component Overrides

The stylesheet is organised in five zones: CSS custom properties for the palette, typography, dark-scheme palette overrides, per-component restyling, and the custom hero + grid-card styles.

:root {
  --dot-green: #7ee787;         /* terminal green — primary */
  --dot-green-bright: #b0f5b7;  /* hover / focused */
  --dot-green-dim: #4a9153;     /* muted */
  --dot-bg: #0b0e14;            /* near-black base */
  --dot-bg-elev: #111621;       /* elevated card */
  --dot-fg: #e4e7ec;
  --dot-fg-muted: #94a3b8;
  --dot-border: #1f2937;
}

[data-md-color-scheme="slate"] {
  --md-default-bg-color: var(--dot-bg);
  --md-default-fg-color: var(--dot-fg);
  --md-primary-fg-color: var(--dot-green);
  --md-accent-fg-color: var(--dot-green-bright);
  --md-typeset-a-color: var(--dot-green);
  --md-code-bg-color: #161b26;
}

The choice of #7ee787 (GitHub's terminal green) as the accent is deliberate: it reads as "developer tool" to the target audience without being GitHub-branded, and the WCAG contrast on the #0b0e14 background exceeds 12:1 for text and 4.5:1 for the accent-on-background — comfortably above AA thresholds.

Component overrides are targeted at the highest-impact surfaces:

/* Header: blurred backdrop-saturate for a floating feel */
.md-header {
  background-color: rgba(11, 14, 20, 0.92);
  backdrop-filter: saturate(180%) blur(12px);
  border-bottom: 1px solid var(--dot-border);
}

/* Grid cards on landing page — hover lift + accent glow */
.md-typeset .grid.cards > :is(ul, ol) > li {
  background: var(--dot-bg-elev);
  border: 1px solid var(--dot-border);
  border-radius: 12px;
  transition: transform 180ms ease, border-color 180ms ease;
}
.md-typeset .grid.cards > :is(ul, ol) > li:hover {
  transform: translateY(-2px);
  border-color: rgba(126, 231, 135, 0.35);
  box-shadow: 0 8px 24px -8px rgba(0, 0, 0, 0.5);
}

docs/index.md — Hero + Grid Cards

The landing page is not documentation — it is a product surface. MkDocs Material's md_in_html extension allows Markdown to nest inside a custom HTML section:

---
hide:
  - navigation
  - toc
---

<section class="dot-hero" markdown>

# .dotfiles

<p class="tagline">Cross-platform, signed, local-first dotfiles…</p>

<div class="buttons">
  <a class="primary" href="guides/INSTALL/">Install →</a>
  <a href="https://github.com/sebastienrousseau/dotfiles">GitHub</a>
</div>

</section>

## What's inside

<div class="grid cards" markdown>

- :material-console:{ .lg .middle } **Multi-shell parity**

    ---

    Bash, Zsh, Fish, Nushell — same aliases, functions, prompt, and completions.

    [→ Shell hub](https://doc.dotfiles.io/reference/UTILS/)

</div>

The hide: [navigation, toc] front-matter removes the sidebar and right-column table-of-contents on this page only — the landing page gets the full canvas, sub-pages retain the standard docs layout.

Verification: Build, Deploy, Contrast

The custom theme adds ~12 KB of CSS to the built site. Local mkdocs build --clean completes in ~2 seconds. The Pages workflow uses hash-locked dependencies (pip install --require-hashes -r requirements-docs.txt) to keep the build reproducible across MkDocs Material and its 30+ transitive dependencies.

Accessibility contrast measured on the deployed site:

• Body text (#e4e7ec on #0b0e14) — 15.6:1 (WCAG AAA)
• Accent (#7ee787 on #0b0e14) — 12.4:1 (WCAG AAA)
• Muted text (#94a3b8 on #0b0e14) — 7.2:1 (WCAG AAA)

Cloudflare CDN cache invalidation after Pages deploy: ~10 minutes on max-age=600. Fetching the GitHub Pages origin (sebastienrousseau.github.io/dotfiles/) reflects the new theme immediately; the CDN-fronted custom domain propagates within one cache TTL.

Return on Resilience

Takeaways

1. primary: custom + extra_css beats theme forking. No custom_dir, no Jinja templates, no plugin authoring. All the customisation lives in files MkDocs Material is explicitly designed to consume.

2. CSS custom properties are the maintainable seam. Overriding --md-primary-fg-color scales; overriding .md-header a.md-header__button:not(...) selectors doesn't.

3. Treat the landing page as a product surface, not documentation. Front-matter hide: [navigation, toc] unlocks the full canvas. Hero + card grid + tabbed quick-start reads as a product page.

4. Lock the docs-build supply chain. pip-compile --generate-hashes + pip install --require-hashes closes the Scorecard PinnedDependenciesID alert and prevents transitive-dep drift in Pages deploys.

5. Measure contrast, not just aesthetics. WCAG AAA on body text is achievable with the right palette; it's not a tradeoff against distinctiveness.

The reference implementation landed as PR #960 and is live at doc.dotfiles.io; the theme source lives at docs/stylesheets/extra.css.