doxyYoda

A theme for Doxygen. The only theme to use CSS Grid and Sass. Also uses MathJax 3. Part of my yoda series of tools.

Why?

Have you seen doxygen HTML? To go from:

To:

But… [x] does this

Doxyrest

Does not allow embedding source inline (see above), doxyrest just doesn’t capture the same level of information

Exhale / Breathe

Can’t even display source code, inline or otherwise

Honestly, nothing captures C++ like Doxygen. Nothing. So inspite of the weird JS cruft its best not to fight it (cough Standardese). This is it.

m.css

is actually very good; used it for d-SEAMS; but this is better for me, and will migrate the rest of my projects later

Features

• CSS Grid layout with Sass
• Dark mode — toggle button + prefers-color-scheme support, persisted via localStorage
• Foldable inline code — <details> wrapping with smooth transitions
• Copy to clipboard — one-click code copying on every code block
• MathJax 3 — beautiful math rendering
• Mermaid — Doxygen 1.17+ $mermaidjs client-side diagrams
• Doxygen 1.17 / 1.18 — header tokens match current stock templates
• Frosted glass navbar — sticky, translucent, always visible
• Modern admonitions — color-coded notes, warnings, todos, bugs, and more
• Fog-over-fen palette — sage paper, olive ink, moss, campfire ember
• Antics analytics — same TurtleTech tracker as the other HaoZeke sites
• Pixi-managed build — reproducible builds with pixi run

Typography

• Body: Source Serif 4
• Headings: Fraunces
• UI: Source Sans 3
• Code: Hack

Quick Start

With pixi (recommended)

git clone https://github.com/HaoZeke/doxyYoda
cd doxyYoda
pixi run demo      # Build the demo site
pixi run serve     # Serve on localhost:8000

Manual

# Compile SCSS
sass src/styles/scss/main.scss src/styles/doxyYoda.css

Usage

Clone the project into the directory with your Doxyfile. Inside your Doxyfile:

HTML_HEADER            = "doxyYoda/src/html/header.html"
HTML_FOOTER            = "doxyYoda/src/html/footer.html"
HTML_EXTRA_STYLESHEET  = "doxyYoda/src/styles/doxyYoda.css"
LAYOUT_FILE            = "doxyYoda/src/xml/doxyYoda.xml"

Or with the release, simply download the .tar.gz into the directory with the Doxyfile and:

HTML_HEADER            = "doxyYoda/html/header.html"
HTML_FOOTER            = "doxyYoda/html/footer.html"
HTML_EXTRA_STYLESHEET  = "doxyYoda/css/doxyYoda.min.css"
LAYOUT_FILE            = "doxyYoda/xml/doxyYoda.xml"

GitHub Action

The easiest way to use doxyYoda in CI is with the bundled action:

- uses: HaoZeke/doxyYoda@v0.2.2
  with:
    cppreference-tag: true   # optional: download cppreference tag file

This downloads the release tarball into doxyYoda/ and (optionally) fetches the cppreference Doxygen tag file into tags/.

Inputs

Input	Default	Description
version	0.2.2	doxyYoda version (without v prefix)
path	doxyYoda	Directory to extract into
cppreference-tag	false	Download cppreference Doxygen tag file
tags-path	tags	Directory for tag files

Outputs

Output	Description
path	Path to doxyYoda directory
header	Path to header.html
footer	Path to footer.html
stylesheet	Path to doxyYoda.min.css
layout	Path to doxyYoda.xml
cppreference-tag-file	Path to cppreference tag file

Full example

name: Build API Docs
on: [push, pull_request]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: HaoZeke/doxyYoda@v0.2.2
        with:
          cppreference-tag: true
      - run: sudo apt-get install -y doxygen graphviz
      - run: doxygen Doxyfile

Pixi Tasks

All build and development tasks are managed via pixi:

Task	Command	Description
Compile SCSS	pixi run compile	SCSS → CSS
Contract tests	pixi run test	Run theme contract tests
Watch mode	pixi run watch	Recompile on file changes
Build demo	pixi run demo	Generate demo documentation site
Serve demo	pixi run serve	Serve demo on localhost:8000
Minify CSS	pixi run minify	Minify compiled CSS
Build release	pixi run release	Build release tarball
Bump version	pixi run bump	Bump version via tbump
Clean	pixi run clean	Remove build artifacts

SCSS Architecture

src/styles/scss/
├── main.scss          # Entry point
├── _variables.scss    # CSS custom properties (light + dark mode)
├── _base.scss         # Reset and global styles
├── _fonts.scss        # Font imports (CDN)
├── _colors.scss       # Color application
├── _layout.scss       # CSS Grid layout
├── _typography.scss   # Headings, links, member docs
├── _code.scss         # Code blocks, syntax, copy button
├── _doxynav.scss      # Navbar, sidebar, breadcrumbs
├── _directives.scss   # Admonitions (note, warning, etc.)
└── _tooltip.scss      # PowerTip tooltips

Dark Mode

doxyYoda supports dark mode through two mechanisms:

1. Automatic: respects prefers-color-scheme: dark from your OS settings
2. Manual toggle: click the ☾ button in the navbar — preference persists via localStorage

The entire color system uses CSS custom properties, so the switch is instant with no flash of unstyled content.

How?

• Dart Sass is needed to compile the CSS (managed by pixi)
• The palette is fog-over-fen: sage paper, olive ink, moss, campfire ember
• CSS is minified via sass --style=compressed (no separate minifier needed)
• Inspired by m.css and Shibuya

Development Workflow

pixi run watch     # Auto-recompile SCSS on changes
pixi run demo      # Rebuild demo docs
pixi run serve     # Serve and preview

Or the manual way with filewatcher-cli and darkhttpd:

filewatcher -s '**/*.scss' "sass src/styles/scss/main.scss:src/styles/doxyYoda.css"

Demo

The demo/ directory contains a self-contained example project:

• demo/src/yoda.hpp — C++ header exercising all Doxygen constructs
• demo/src/mainpage.dox — Landing page showcasing every visual element
• demo/Doxyfile — Pre-configured to use doxyYoda

Build and preview:

pixi run demo && pixi run serve
# Open http://localhost:8000

Live: doxyyoda.rgoswami.me

Tree View

Set GENERATE_TREEVIEW = YES. The theme places #side-nav on a dedicated CSS Grid column (--sidebar-width, default 16rem) when that node is a direct child of .grid-contents. Leave FULL_SIDEBAR = NO: that option nests #top inside #side-nav (Doxygen’s contract) and is a poor fit for the title-row grid. Doxygen’s resize.js splitbar is hidden; the grid track owns the sidebar width.

Users

Sites that still ship the doxyYoda HTML theme (most published trees are still on an older tarball; the current release is the demo):

• doxyYoda demo (this theme, v0.2.2)
• eOn C++ API (sibling of the Sphinx book, v0.2.2)
• SymEngine C++ API documentation
• Eigen v3.4.0 (git) unofficial API documentation
• featom API documentation
• GaussJacobiQuad API documentation

d-SEAMS developer docs are Sphinx / Shibuya / doxyrest now (docs.dseams.info), not this theme.

Acknowledgments

This project was conceived as part of SymEngine’s Google Season of Docs 2020. Inspired by m.css by Vladimír Vondruš and Shibuya by Hsiaoming Yang.

License

Apache version 2