Repository navigation
feat(docs-site): orcapod.org logo, favicon, fonts and a blue theme (ITL-1170) - #431
Conversation
…eme (ITL-1170) The documentation site takes orcapod.org's logo (header, inverted in dark mode) and favicon, unmodified, names its fonts (Asap, Lexend Exa) before the system fonts, keeps its background and text colours, and adds a blue accent family for links, the sidebar, the banner and note asides. The content build writes the favicon into site/public/ (SITE_PUBLIC_FILES), fixing the favicon 404. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…hots (ITL-1170) The header name takes the text colour (black, white in dark mode), as orcapod.org's navigation shows it, instead of the accent. docs/dev/specs/2026-11-17-docs-site-theme records what orcapod.org uses, the palette with its contrast ratios, and light and dark screenshots of a local build. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review.
|
| Layer / File(s) | Summary |
|---|---|
Theme and Starlight configuration site/src/styles/orcapod.css, site/astro.config.mjs, site/README.md, site/pnpm-workspace.yaml, docs/dev/specs/2026-11-17-docs-site-theme/README.md, changelog.d/ITL-1170.md |
The stylesheet defines light and dark theme colors and title styling. Starlight configuration selects the logo, favicon path, and stylesheet. The README, specification, and changelog describe the theme and site assets. |
Publish the site favicon scripts/docs_site_content.py, tests/test_docs/test_site_content.py |
The content generator reads configured site-owned files and synchronizes them to the public directory alongside linked documentation assets. A test checks that the published favicon matches its source. |
Estimated code review effort: 2 (Simple) | ~10 minutes
Change: Feature
Possibly related PRs
- metamorphic-labs/orcapod-python#425: Introduces the Starlight site and content generator extended by this change.
Merge Risk: 
Minimal · up to f2d55
-
This change restyles the documentation site and publishes its favicon. It has no identified merge-blocking risk and is safe to merge.
Security architecture risk: 
Minimal · up to f2d55
-
The branding and favicon changes remain within the existing documentation build. No introduced or worsened risk materially affecting security, failure containment, rollback, or ownership guarantees was established.
Pre-merge checks: 
4
-
Full details: Title check
-
Explanation
The title "feat(docs-site): orcapod.org logo, favicon, fonts and a blue theme (ITL-1170)" matches the main change. The changeset restyles the docs site to match orcapod.org, with the logo, favicon, fonts, colors, and a blue accent. The summary confirms this across the Astro config, the orcapod.css theme, the favicon sync in docs_site_content.py, and the README and spec updates. The title is 77 characters, which is slightly long but still readable.
-
Finishing Touches
-
Generate unit tests (beta)
-
- Commit to this branch
- Create a new PR
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues are identified for the documentation branding and favicon updates.
No open issues 🎉
What changed in this PR
Updates the published Astro Starlight documentation site to reflect orcapod.org’s branding, with a distinct blue theme.
Changes:
- Configures the logo, favicon, light/dark colours and brand-font preferences, retaining system-font fallbacks without bundling fonts.
- Adds favicon copying to the generated static files, with a regression test.
- Documents the theme, asset sources and visual evidence.
| File | Description |
|---|---|
tests/test_docs/test_site_content.py |
Tests that the content build copies the favicon unchanged. |
site/src/styles/orcapod.css |
Defines colours, font preferences, title styling and dark-mode logo inversion. |
site/README.md |
Documents theme choices and asset handling. |
site/pnpm-workspace.yaml |
Updates the comment explaining image-optimizer exclusion. |
site/astro.config.mjs |
Configures the logo, favicon and theme stylesheet. |
scripts/docs_site_content.py |
Includes site-owned assets in generated public files. |
docs/dev/specs/2026-11-17-docs-site-theme/README.md |
Records branding sources, palette, contrast ratios and screenshot references. |
changelog.d/ITL-1170.md |
Adds the documentation-site branding update. |
Review effort: Balanced
Codecov Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
The site serves orcapod.org's fonts itself: @fontsource-variable/asap and @fontsource/lexend-exa (weight 700), both OFL-1.1, as customCss entries. No request goes to a font host. scripts/check_site_licenses.py allows OFL-1.1 (SIL Open Font License 1.1, OSI-approved; approved by the developer on 2026-11-17). Screenshots retaken with the real fonts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ITL-1170) The home page uses Starlight's splash template with a hero: the header's logo (inverted in dark mode), the name set as orcapod.org's wordmark, the tagline 'A Python library for building highly reproducible scientific data pipelines.' and the buttons Get started, Tutorial and GitHub. docs/index.md is unchanged: scripts/docs_site_content.py writes the hero into the generated page's front matter (HOME_HERO) and resolves its buttons like any link, so they follow the base path and a button to an unpublished page fails the build. --no-hero builds a plain home page (the tests' pages). Screenshots at desktop and phone width, light and dark. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Relates to ITL-1170 (follow-up to #425 and #429: the site's look).
What
The documentation site takes the look of orcapod.org, the project's home page, with a blue accent of its own.
images/iconOutlined.png, unmodified, in the header (site/src/assets/orcapod-icon.png). orcapod.org has no SVG and no dark variant; in dark mode the logo is shown inverted with a CSS filter (white orcas, dark eyes). The site's name beside it is lower case in the text colour, as orcapod.org's navigation writes it; page titles keep "Orcapod".favicon.ico, unmodified (site/src/assets/favicon.ico). The site returned 404 for/orcapod-python/favicon.svg(Starlight's default).site/public/is regenerated byscripts/docs_site_content.pyon every build, so the script now writes the site's own static files there too (SITE_PUBLIC_FILES), with a test.@fontsource-variable/asap) and Lexend Exa bold for the name (@fontsource/lexend-exa, weight 700 only), twocustomCssentries ahead of the theme, with Starlight's system fonts after them. Both packages are OFL-1.1 (SIL Open Font License 1.1, OSI-approved), which the developer approved on 2026-11-17:scripts/check_site_licenses.pynow allowsOFL-1.1, with a comment saying so. No page requests a font host (fonts.googleapis/fonts.gstaticdo not occur in the built site); the Dependency review step does not deny OFL-1.1, anddocs/dev/security-exceptions.mdis untouched.splashtemplate with a hero: the header's logo (inverted in dark mode), the name set as orcapod.org's wordmark (Lexend Exa bold, lower case), the tagline "A Python library for building highly reproducible scientific data pipelines." (the first sentence ofdocs/index.md, shortened) and the buttons Get started, Tutorial and GitHub. The development-version banner stays above it.docs/index.mdis unchanged:scripts/docs_site_content.pywrites the hero into the generated page's front matter (HOME_HERO) and resolves its buttons like any link, so they follow the base path and a button to an unpublished page fails the build (tests intests/test_docs/test_site_content.py;--no-herobuilds a plain home page, used by the tests' small pages).orcapodlogofull.png, 3001 x 3001, 203 KB) would repeat the name under the title, and Astro resizes images only withsharp, which the site does not install (libvips is LGPL-3.0-or-later), so it would be served at full size. The hero uses the header's 80 KB icon instead; Astro's passthrough image service writes the hero's copy at a URL of its own, so the home page loads it twice (160 KB).site/src/styles/orcapod.css, Starlight's--sl-color-*variables): light mode keeps orcapod.org's background#fcfafcand text#0a0a0a; dark mode is a near-black with a blue tint (#0b0f16). Links, the current sidebar entry, the development-version banner and note asides are blue:#1565c0in light mode,#3d8fe8/#a8d0ffin dark mode. Caution, tip and danger asides keep their colours. The pipeline diagram is not touched.site/README.mdhas a "The theme" section;docs/dev/specs/2026-11-17-docs-site-theme/records what orcapod.org uses, the palette and the screenshots below.changelog.d/ITL-1170.mdgets one bullet.Screenshots
From a local
pnpm build, headless Chrome at 1280 x 900 (scaled) and 390 x 844 (phone), with the bundled fonts (Asap, Lexend Exa).The home page with the hero:
The other pages (and the home page before the hero, with the sidebar):
Checks
uv run pytest tests/test_docs/test_site_content.py: 63 passed (with the hero tests).scripts/assemble_changelog.py --check,scripts/design_issues.py --check: OK.pnpm licenses list --json --prod | uv run python ../scripts/check_site_licenses.py: 346 npm packages, all under allowed licenses.pnpm install --frozen-lockfile && pnpm build: 38 pages, all internal links valid; the hero's buttons resolve under/orcapod-python/; nofonts.googleapisorfonts.gstaticinsite/dist; 9 font files bundled under_astro/(latin, latin-ext, vietnamese subsets, loaded byunicode-range). Package changes: the two font packages (site/package.json,site/pnpm-lock.yaml).🤖 Generated with Claude Code
Summary by CodeRabbit