Skip to content

Unify docs site visual style: reskin Material to match custom HTML pages#87

Merged
RamyaGuru merged 3 commits into
mainfrom
docs/material-theme-reskin
May 18, 2026
Merged

Unify docs site visual style: reskin Material to match custom HTML pages#87
RamyaGuru merged 3 commits into
mainfrom
docs/material-theme-reskin

Conversation

@RamyaGuru
Copy link
Copy Markdown
Collaborator

Closes #86.

Summary

Brings the MkDocs Material–rendered pages (/api-guide/, /getting-started/, /configuration/, tutorials) visually in line with the hand-written HTML pages at / and /daqiri-api.html, so the docs site reads as one design instead of two. Also reorganizes the loose image assets under docs/ and adds a light/dark mode toggle.

What's in this PR

Material reskin (f0ec838)

  • docs/stylesheets/extra.css expanded from a ~70-line accent override sheet to a full Material override sheet. Maps the custom NVIDIA palette (--nv-bg-dark #0a0a0a, --nv-border #222222, --nv-text-pri #f0f0f0, etc.) onto Material's documented CSS variables (--md-default-bg-color, --md-code-bg-color, --md-default-fg-color, …).
  • Adds rules for typography, inline and block code, tables, navigation, buttons, and the note / warning / info / tip admonition variants.
  • mkdocs.yml: switches theme.font.text to Inter and theme.font.code to JetBrains Mono so Material loads the same fonts the custom pages declare.

Header logo and favicon (587b7f3)

  • Wires the existing docs/logo.svg into theme.logo (replaces Material's default book icon) and docs/logo.png into theme.favicon.
  • Sizes the rendered logo at 36px in extra.css to match the treatment on the custom HTML pages.

Asset reorg, typography polish, palette toggle (5f529ad)

  • Moves docs/logo.{svg,png} and docs/architecture.svg into docs/images/. Updates theme.logo, theme.favicon, README.md, and embedded references in docs/index.html, docs/daqiri-api.html, and the extra.css comment.
  • Shrinks the Material heading scale by ~30% on h1 / h2 and proportionally less on h3 / h4 so the heading hierarchy stays readable. Drops pre > code font-size to 0.72rem to match body text.
  • Adds a light/dark scheme toggle via theme.palette using Material's brightness icons. Slate (dark) remains the default. Light mode currently falls back to plain Material defaults — the extra.css overrides are scoped to [data-md-color-scheme="slate"], so the NVIDIA reskin only applies in dark mode.

Out of scope

  • Migrating docs/index.html and docs/daqiri-api.html to Markdown so URLs unify (.html vs trailing slash) and search indexes them.
  • Generating daqiri-api.html from Doxygen on include/daqiri/daqiri.h to eliminate hand-maintained API drift.
  • A custom Material home.html template to reproduce the landing-page hero/feature-card layout natively in MkDocs.
  • Mirroring the dark-mode overrides for light mode so the NVIDIA branding carries across both schemes.

Test plan

  • mkdocs build --strict (matches the CI gate in .github/workflows/docs.yml)
  • scripts/check_html_links.py site
  • scripts/check_doc_refs.py
  • Visual diff /api-guide/ (Material-rendered) vs /daqiri-api.html (custom) — share palette, typography, code-block styling
  • Visual diff /getting-started/ vs / (landing page) — same
  • /tutorials/system_configuration/ — platform tabs (IGX Orin / DGX Spark) still work
  • Header logo links to home; favicon shows in the browser tab
  • Light/dark toggle in header flips palettes and persists across pages

🤖 Generated with Claude Code

RamyaGuru and others added 3 commits May 18, 2026 13:29
Expand docs/stylesheets/extra.css from a small accent override sheet
to a comprehensive set of Material component overrides that mirror the
palette and typography of the hand-written docs/index.html and
docs/daqiri-api.html. Map the custom NVIDIA dark theme onto Material's
documented CSS variables and add rules for typography, code blocks,
tables, navigation, buttons, and the note/warning/info/tip admonition
variants.

Swap theme.font.text to Inter and theme.font.code to JetBrains Mono in
mkdocs.yml so Material loads the same fonts the custom pages declare.

Closes the visual disconnect between Material-rendered pages and the
custom HTML passthrough pages without migrating the HTML pages to
Markdown.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Ramya Gurunathan <rgurunathan@nvidia.com>
Wire the existing docs/logo.svg into theme.logo so Material renders it
in place of the default book icon, and point theme.favicon at
docs/logo.png so the browser tab matches. Size the rendered logo at
36px tall via extra.css to match the treatment on the custom HTML
pages.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Ramya Gurunathan <rgurunathan@nvidia.com>
Three follow-ups to the initial Material reskin:

- Move docs/logo.{svg,png} and docs/architecture.svg into a new
  docs/images/ subfolder. Update theme.logo, theme.favicon, README.md,
  and the embedded references in docs/index.html, docs/daqiri-api.html,
  and the extra.css comment so docs/ is markdown plus the two
  hand-maintained HTML pages.

- Shrink the Material heading scale by ~30% on h1/h2 and proportionally
  less on h3/h4 to keep the heading hierarchy intact. Drop pre > code
  font-size to 0.72rem so code blocks match the surrounding body text.

- Add a light/dark scheme toggle to theme.palette using Material's
  brightness icons. Slate (dark) stays the default. Light mode falls
  back to plain Material defaults for now — extra.css overrides are
  scoped to [data-md-color-scheme="slate"], so the NVIDIA reskin only
  applies in dark mode.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Ramya Gurunathan <rgurunathan@nvidia.com>
@greptile-apps
Copy link
Copy Markdown

greptile-apps Bot commented May 18, 2026

Greptile Summary

This PR unifies the visual style of the DAQIRI docs site by expanding docs/stylesheets/extra.css into a full Material override sheet that maps the custom NVIDIA dark palette onto Material's CSS variables, and updates mkdocs.yml to use Inter/JetBrains Mono fonts, the DAQIRI logo, and a light/dark toggle. A secondary commit reorganizes docs/logo.{svg,png} and docs/architecture.svg under a new docs/images/ subfolder, updating every consumer (README.md, mkdocs.yml, docs/index.html, docs/daqiri-api.html).

  • All three commits carry the #86 - <Title> prefix and DCO Signed-off-by trailers.
  • Image moves are consistently propagated to every HTML/YAML/Markdown reference; AGENTS.md does not enumerate individual image assets so no update is needed there.
  • The NVIDIA dark-theme overrides are correctly scoped to [data-md-color-scheme="slate"]; light mode deliberately falls back to Material defaults (called out in the PR description as out of scope).

Confidence Score: 5/5

Documentation-only visual restyling with no source-code changes; all image moves are consistently reflected across every consumer.

All three commits are correctly signed off and follow the issue-prefixed title convention. The image asset reorg is complete — every HTML page, the README, and mkdocs.yml have been updated to the new images/ paths and there are no stale references in any markdown file. The CSS overrides are correctly scoped, the MkDocs logo/favicon paths are valid relative to docs_dir, and the light/dark toggle follows the pattern shown in Material's own documentation. Light-mode branding is intentionally deferred and clearly documented in the PR description.

No files require special attention.

Important Files Changed

Filename Overview
docs/stylesheets/extra.css Expanded from a ~70-line accent override to a full Material override sheet. All rules are correctly scoped to [data-md-color-scheme="slate"]; logo sizing rule intentionally applies to both schemes. Selector choices (e.g. :not(pre) > code vs pre > code) are sound.
mkdocs.yml Adds logo/favicon (paths relative to docs_dir are correct), switches fonts to Inter/JetBrains Mono, and converts palette to a two-entry list enabling the brightness toggle. Icon selection (brightness-4 / brightness-7) matches Material's own documentation examples.
docs/index.html All four image references (two logo in nav/footer, one hero logo, one architecture diagram) updated from docs-root to images/ subfolder. No other changes.
docs/daqiri-api.html Single logo reference updated from logo.svg to images/logo.svg to match the asset reorg.
README.md Inline logo reference updated from docs/logo.svg to docs/images/logo.svg. Documentation table is unchanged (no image entries, only markdown links).

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Browser request"] --> B{"Color scheme?"}
    B -- "slate (default)" --> C["Material + NVIDIA overrides\nextra.css [data-md-color-scheme=slate]"]
    B -- "default (light)" --> D["Plain Material defaults\n(NVIDIA overrides not applied)"]
    C --> E["NVIDIA palette\n#0a0a0a bg, #76b900 green\nInter / JetBrains Mono"]
    D --> F["Material defaults\nblack primary, light-green accent\nInter / JetBrains Mono"]
    G["mkdocs.yml\ntheme.logo: images/logo.svg\ntheme.favicon: images/logo.png"] --> H["MkDocs Material build"]
    H --> B
    I["docs/images/\nlogo.svg · logo.png\narchitecture.svg"] --> G
    I --> J["docs/index.html\ndocs/daqiri-api.html\nREADME.md"]
Loading

Reviews (1): Last reviewed commit: "#86 - Reorganize image assets, tighten t..." | Re-trigger Greptile

@RamyaGuru RamyaGuru merged commit ff3c15a into main May 18, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Unify docs site visual style: reskin MkDocs Material to match custom HTML pages

1 participant