doxyYoda — HTML 文档模板

SHA-256: c9ac18cf6451faf7592d34cc30c3ff9d1d5dd4869233b88c66a82fd351c46cf9

2026-10-02T08:30:59.976Z

* doxyYoda
#+DOWNLOADED: screenshot @ 2021-03-02 01:34:09
[[file:images/doxyYoda/2021-03-02_01-34-09_screenshot.png]]

A theme for [[http://doxygen.nl/][Doxygen]]. The *only* theme to use [[https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout][CSS Grid]] and [[https://sass-lang.com/guide][Sass]]. Also uses MathJax 3. Part of my ~yoda~ series of tools.

** Why?
Have you seen ~doxygen~ HTML? To go from:
#+DOWNLOADED: screenshot @ 2021-03-02 00:51:00
[[file:images/why/2021-03-02_00-51-00_screenshot.png]]
To:
#+DOWNLOADED: screenshot @ 2026-08-17 13:20:00
[[file:images/why/2026-08-17_fog-over-fen-members.png]]
*** 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* [[https://foonathan.net/2019/11/standardese-post-mortem/][Standardese]]). This is it.
- m.css :: is actually very good; used it for [[https://dseams.info][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: [[https://fonts.google.com/specimen/Source+Serif+4][Source Serif 4]]
- Headings: [[https://fonts.google.com/specimen/Fraunces][Fraunces]]
- UI: [[https://fonts.google.com/specimen/Source+Sans+3][Source Sans 3]]
- Code: [[https://sourcefoundry.org/hack/][Hack]]

** Quick Start

*** With pixi (recommended)
#+begin_src bash
git clone https://github.com/HaoZeke/doxyYoda
cd doxyYoda
pixi run demo      # Build the demo site
pixi run serve     # Serve on localhost:8000
#+end_src

*** Manual
#+begin_src bash
# Compile SCSS
sass src/styles/scss/main.scss src/styles/doxyYoda.css
#+end_src

** Usage
Clone the project into the directory with your ~Doxyfile~.
Inside your ~Doxyfile~:
#+begin_src conf
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"
#+end_src
Or with the release, simply download the ~.tar.gz~ into the directory with the ~Doxyfile~ and:
#+begin_src conf
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"
#+end_src

*** GitHub Action
The easiest way to use doxyYoda in CI is with the bundled action:
#+begin_src yaml
- uses: HaoZeke/[email protected]
  with:
    cppreference-tag: true   # optional: download cppreference tag file
#+end_src
This downloads the release tarball into =doxyYoda/= and (optionally) fetches the [[https://en.cppreference.com/w/][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
#+begin_src yaml
name: Build API Docs
on: [push, pull_request]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: HaoZeke/[email protected]
        with:
          cppreference-tag: true
      - run: sudo apt-get install -y doxygen graphviz
      - run: doxygen Doxyfile
#+end_src

** Pixi Tasks
All build and development tasks are managed via [[https://pixi.sh][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
#+begin_example
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
#+end_example

** 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.

#+DOWNLOADED: screenshot @ 2026-08-17 13:20:00
[[file:images/why/2026-08-17_fog-over-fen-index-dark.png]]

** How?
- [[https://sass-lang.com/documentation/cli/dart-sass][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 [[https://mcss.mosra.cz/][m.css]] and [[https://shibuya.lepture.com/][Shibuya]]

*** Development Workflow
#+begin_src bash
pixi run watch     # Auto-recompile SCSS on changes
pixi run demo      # Rebuild demo docs
pixi run serve     # Serve and preview
#+end_src

Or the manual way with [[https://github.com/filewatcher/filewatcher-cli][filewatcher-cli]] and [[https://wiki.alpinelinux.org/wiki/Darkhttpd][darkhttpd]]:
#+begin_src bash
filewatcher -s '**/*.scss' "sass src/styles/scss/main.scss:src/styles/doxyYoda.css"
#+end_src

** 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:
#+begin_src bash
pixi run demo && pixi run serve
# Open http://localhost:8000
#+end_src

Live: [[https://doxyyoda.rgoswami.me/][doxyyoda.rgoswami.me]]

#+DOWNLOADED: screenshot @ 2026-08-17 13:20:00
[[file:images/why/2026-08-17_fog-over-fen-index-light.png]]

** 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):

- [[https://doxyyoda.rgoswami.me/][doxyYoda demo]] (this theme, =v0.2.2=)
- [[https://eondocs.org/api-cpp/][eOn C++ API]] (sibling of the Sphinx book, =v0.2.2=)
- [[https://symengine.org/symengine][SymEngine C++ API documentation]]
- [[https://haozeke.github.io/eigen/][Eigen v3.4.0 (git) unofficial API documentation]]
- [[https://atomic-solvers.github.io/featom/][featom API documentation]]
- [[https://haozeke.github.io/GaussJacobiQuad/][GaussJacobiQuad API documentation]]

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

* Acknowledgments
This project was conceived as part of SymEngine's Google Season of Docs 2020. Inspired by [[https://mcss.mosra.cz/][m.css]] by Vladimír Vondruš and [[https://shibuya.lepture.com/][Shibuya]] by Hsiaoming Yang.

* License
[[https://www.apache.org/licenses/LICENSE-2.0.html][Apache version 2]]