Repository navigation
Resolve Issue #88: Implement GitHub Pages documentation site - #90
Merged
Merged
Conversation
Material-styled MkDocs site containing the markdown documentation (README) and the Doxygen API documentation served under /api/. The "Deploy Documentation (GitHub Pages)" workflow installs Doxygen 1.9.8 and Graphviz via marketplace actions, generates the Doxygen HTML into docs/api/, builds the site with mkdocs-material and deploys it to the gh-pages branch.
EndrII
reviewed
Oct 13, 2026
Member
|
also fix README.md links to site |
The site home page is now generated at build time: the documentation workflow copies the root README.md to docs/index.md before 'mkdocs build'. The README stays the single source of truth and the generated copy is gitignored. The workflow also creates docs/ before running Doxygen, since removing the symlink leaves no tracked file in that directory.
Member
|
and lets try to use latest doxygen version (and fix doxygen generated page style - lets make it more material if it posible) |
…ing, fixed README docs link
Member
Author
|
All three points are addressed in 084f2ca: (1) README link now points to the GitHub Pages site (https://quasarapp.github.io/Heart/ + /api/), (2) the workflow now pins Doxygen 1.18.0 (latest stable, and the version the docs were validated with locally), (3) the generated Doxygen pages get a Material restyle via res/doxygen-material.css (indigo palette + Roboto stack, matching the MkDocs site; dark mode follows the system scheme). SERVER_BASED_SEARCH is off so search works on static GitHub Pages. |
EndrII
approved these changes
Oct 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Resolves #88 — GitHub Pages documentation site.
mkdocs.yml), with palette light/dark toggle, code copy, search highlighting and tasklist rendering for the README.docs/index.mdis generated from the rootREADME.mdat build time by the documentation workflow (gitignored copy), so there is a single source of truth./api/; the Doxygen config is generated in CI fromdoxygen.conf.in(@HEART_VERSION@->1.4.<commit-count>.<short-sha>, same scheme as CMake) withOUTPUT_DIRECTORYredirected todocs/api/.Deploy Documentation (GitHub Pages)workflow (push tomain+ manual dispatch) deploys the builtsite/to thegh-pagesbranch withJamesIves/github-pages-deploy-action@v4.ssciwr/doxygen-install@v2.0.3pinned to 1.9.8 +ts-graphviz/setup-graphviz@v2.0.2for theHAVE_DOT=YESdiagrams (same action set already proven in QuasarApp/easyssl)..gitignorekeeps the generated output (docs/api/,docs/res/,docs/index.md,site/) out of git while tracking the markdown sources.Review feedback (ae04998)
docs/index.mdsymlink -> done. The README is now copied todocs/index.mdat build time instead, and the workflow createsdocs/before the Doxygen run (the symlink was the only tracked file in that directory).Validation (local, same toolchain versions as the runner)
docs/api/, class/collaboration diagram PNGs rendered, version1.4.914.a3e011b.mkdocs build --strict(mkdocs 1.6.1, mkdocs-material 9.7.7): exit 0, no warnings./,/api/,/res/Banner_Web.png,/api/res/Banner_Web.pngall200; Doxygen main page titledHeart: QuasarApp Heart.Notes
gh-pagesbranch; the repo Pages source then has to be set togh-pages(path/) — I can do that via the API once the first deploy lands.Deploy Documentation (GitHub Pages)workflow is intentionally scoped topush: main(same as the proven easyssl workflow), so it will first run when this PR is merged.