Skip to content

feat(docs-site): orcapod.org logo, favicon, fonts and a blue theme (ITL-1170) - #431

Merged
eywalker merged 4 commits into
mainfrom
eywalker/itl-1170-docs-site-theme
Nov 18, 2026
Merged

eywalker merged 4 commits into
mainfrom
eywalker/itl-1170-docs-site-theme

Conversation

@eywalker

@eywalker eywalker commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

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.

  • Logo: orcapod.org's 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: orcapod.org's favicon.ico, unmodified (site/src/assets/favicon.ico). The site returned 404 for /orcapod-python/favicon.svg (Starlight's default). site/public/ is regenerated by scripts/docs_site_content.py on every build, so the script now writes the site's own static files there too (SITE_PUBLIC_FILES), with a test.
  • Fonts: orcapod.org's fonts are bundled with the site and served by it: Asap for the text (@fontsource-variable/asap) and Lexend Exa bold for the name (@fontsource/lexend-exa, weight 700 only), two customCss entries 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.py now allows OFL-1.1, with a comment saying so. No page requests a font host (fonts.googleapis / fonts.gstatic do not occur in the built site); the Dependency review step does not deny OFL-1.1, and docs/dev/security-exceptions.md is untouched.
  • Home page hero: Starlight's splash template 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 of docs/index.md, shortened) and the buttons Get started, Tutorial and GitHub. The development-version banner stays above it. 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 (tests in tests/test_docs/test_site_content.py; --no-hero builds a plain home page, used by the tests' small pages).
    • Splash means no sidebar or table of contents on the home page; at phone width there is no menu button there (the buttons, the search and "Next steps" lead on).
    • Logo: orcapod.org's full logo (orcapodlogofull.png, 3001 x 3001, 203 KB) would repeat the name under the title, and Astro resizes images only with sharp, 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).
  • Colours (site/src/styles/orcapod.css, Starlight's --sl-color-* variables): light mode keeps orcapod.org's background #fcfafc and 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: #1565c0 in light mode, #3d8fe8 / #a8d0ff in dark mode. Caution, tip and danger asides keep their colours. The pipeline diagram is not touched.
  • Contrast (WCAG AA is 4.5:1): light body text 12.1:1, links 5.5:1 (4.9:1 on inline-code background), banner 5.5:1; dark body text 12.3:1, links 12.0:1 (9.4:1 on inline code), banner 9.1:1.
  • site/README.md has 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.md gets 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:

Light Dark
home with hero, light home with hero, dark
home with hero, phone, light home with hero, phone, dark

The other pages (and the home page before the hero, with the sidebar):

Light Dark
home before the hero, light home before the hero, dark
function pods page: code, caution and note asides, light function pods page, dark
in-development notice, light in-development notice, dark
API reference, light API reference, dark

Checks

  • uv run pytest tests/test_docs/test_site_content.py: 63 passed (with the hero tests).
  • ruff check, ruff format --check, basedpyright: clean (0 errors).
  • 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.
  • Local pnpm install --frozen-lockfile && pnpm build: 38 pages, all internal links valid; the hero's buttons resolve under /orcapod-python/; no fonts.googleapis or fonts.gstatic in site/dist; 9 font files bundled under _astro/ (latin, latin-ext, vietnamese subsets, loaded by unicode-range). Package changes: the two font packages (site/package.json, site/pnpm-lock.yaml).

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features
    • Updated the documentation site with Orcapod branding, including its logo, favicon, typography, and blue accents in both light and dark modes.
    • The site now includes its favicon in generated public content.
  • Documentation
    • Added guidance describing the site’s theme and visual styling.

Edgar Y. Walker and others added 2 commits November 17, 2026 15:13
…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>
@eywalker
eywalker requested a balanced review from Copilot November 17, 2026 23:22
@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between ad3f241 and f2d55c4.

Files ignored due to path filters: 10

  • docs/dev/specs/2026-11-17-docs-site-theme/api-operators-dark.png is excluded by !**/*.png
  • docs/dev/specs/2026-11-17-docs-site-theme/api-operators-light.png is excluded by !**/*.png
  • docs/dev/specs/2026-11-17-docs-site-theme/concept-function-pods-dark.png is excluded by !**/*.png
  • docs/dev/specs/2026-11-17-docs-site-theme/concept-function-pods-light.png is excluded by !**/*.png
  • docs/dev/specs/2026-11-17-docs-site-theme/home-dark.png is excluded by !**/*.png
  • docs/dev/specs/2026-11-17-docs-site-theme/home-light.png is excluded by !**/*.png
  • docs/dev/specs/2026-11-17-docs-site-theme/in-development-notice-dark.png is excluded by !**/*.png
  • docs/dev/specs/2026-11-17-docs-site-theme/in-development-notice-light.png is excluded by !**/*.png
  • site/src/assets/favicon.ico is excluded by !**/*.ico
  • site/src/assets/orcapod-icon.png is excluded by !**/*.png
Files selected for processing: 8

  • changelog.d/ITL-1170.md
  • docs/dev/specs/2026-11-17-docs-site-theme/README.md
  • scripts/docs_site_content.py
  • site/README.md
  • site/astro.config.mjs
  • site/pnpm-workspace.yaml
  • site/src/styles/orcapod.css
  • tests/test_docs/test_site_content.py

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Recent review details

Context from checks skipped due to timeout: 5

  • GitHub Check: test (3.13)
  • GitHub Check: copilot-pull-request-reviewer
  • GitHub Check: CodeRabbit
  • GitHub Check: test (3.12)
  • GitHub Check: test (3.13)
Additional context used

Code guidelines: 1

CLAUDE.md — auto-discovered
Path-based instructions: 5

Source excerpt: A pull request never edits `CHANGELOG.md` (developer, November 11, 2026; ITL-961).

CodeRabbit inference engine (CLAUDE.md)

Files:

  • changelog.d/ITL-1170.md
Source excerpt: `docs/` is the only source.

CodeRabbit inference engine (CLAUDE.md)

Files:

  • docs/dev/specs/2026-11-17-docs-site-theme/README.md
Source excerpt: The file holds only the text that would have gone under the release heading in `CHANGELOG.md`: the same category headings `CHANGELOG.md` uses (`### Breaking changes and migration`, `### Added`, `### Changed`, `### Fixed`, `#...

CodeRabbit inference engine (CLAUDE.md)

Files:

  • changelog.d/ITL-1170.md
Source excerpt: Documents written during development are kept in the repository, under `docs/dev/` (developer, November 16, 2026; ITL-1169): Specs go in `docs/dev/specs/`, plans in `docs/dev/plans/`, and the scripts and evidence they cite i...

CodeRabbit inference engine (CLAUDE.md)

Files:

  • docs/dev/specs/2026-11-17-docs-site-theme/README.md
Source excerpt: What is published is decided in `scripts/docs_site_content.py` (`PUBLISHED_FILES`, `PUBLISHED_FOLDERS`, `EXCLUDED`).

CodeRabbit inference engine (CLAUDE.md)

Files:

  • docs/dev/specs/2026-11-17-docs-site-theme/README.md
Additional comments: 1

site/astro.config.mjs: 1

89-89: Functional Correctness

The favicon option is a Starlight framework input, not a literal template href. Starlight 0.43.1 prefixes root-relative favicon paths with the configured base. The rendered link therefore points to /orcapod-python/favicon.ico, which is the path the author verified. The concern that the page requests the origin root does not hold, and favicon: '/favicon.ico' needs no change.

Walkthrough

The documentation site now uses Orcapod branding, with light and dark theme styling. The content generator also publishes the site favicon to the public directory.

Changes: Documentation site branding

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

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: Passed 4

Check name Status Explanation
Title check Passed 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, fo…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 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

codecov Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
see 4 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Edgar Y. Walker and others added 2 commits November 17, 2026 15:48
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>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are reported for the documentation branding and home-page hero updates.

No open issues 🎉

1 file not reviewed
  • site/pnpm-lock.yaml: Generated file

Review effort: Balanced

@eywalker
eywalker merged commit 84a3fd2 into main Nov 18, 2026
17 checks passed
@eywalker
eywalker deleted the eywalker/itl-1170-docs-site-theme branch November 18, 2026 00:10
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.

2 participants