brainx-sphinx-header

Sphinx extension that injects the canonical BrainX brand header and footer into any docs site, fetched live from the landing site so every package's docs stays in visual sync.

Install

pip install brainx-sphinx-header

Use

In your docs/conf.py:

extensions = [
    # ...
    "brainx_sphinx_header",
]

That's it. On the next build, the BrainX header and footer are fetched from https://brainx.chaobrain.com/shared-header, cached at <docs>/_brand/, and emitted as _static/css/brainx-header.css + _static/js/brainx-header.js (plus the matching brainx-footer.{css,js}).

Configuration (optional)

All settings have sensible defaults. Override in conf.py only if you need to.

Each setting also honors an environment variable (BRAINX_HEADER_URL, BRAINX_HEADER_TTL, BRAINX_HEADER_OFFLINE=1, BRAINX_HEADER_LOCAL, BRAINX_SSR_INJECT=0) which takes precedence — handy for CI.

What it does

• Fetches header.html, header.css, header.js, footer.html, footer.css from the BrainX landing site (with TTL cache + stale fallback).
• Emits them as Sphinx static assets and registers them via add_css_file / add_js_file.
• Header: appends CSS overrides that hide sphinx_book_theme / pydata_sphinx_theme native top bars (header.bd-header, .bd-header-article, .header-article-items.header-article__inner); wires the BrainX header's burger to the theme's hidden original (.primary-toggle) so sidebar toggle keeps working — no template overrides needed.
• Footer: appends below the theme's native footer. The canonical CSS ships margin-top: 6rem for the Astro landing page; the extension appends an override that zeros that margin in docs context so the brand footer sits flush against the theme footer instead of leaving a 6–8rem blank band. {{YEAR}} is substituted at extension-emit time.
• SSR injection (v0.5.0+): on build-finished, every built page outside _static/ gets the header markup written in right after <body> and the footer right before </body>. The document ships the brand chrome at first paint — no flash, crawlers and no-JS clients see it, screen readers see it. Idempotent via data-bx-header / data-bx-footer markers; the JS preambles also self-skip those markers so they become a pure behavior payload (plus a fallback if SSR is disabled). Disable via brainx_ssr_inject = False or BRAINX_SSR_INJECT=0.
• Slash-tolerant index: injects <base href="{html_baseurl}"> into the docs index page, so the site renders correctly whether reached via https://host/<pkg> or https://host/<pkg>/. Sub-pages already resolve correctly via their own real paths and are not touched. Pair with an exact-match nginx block (location = /<pkg> { alias .../current/index.html; default_type text/html; }) to actually serve the no-slash URL without a redirect. Disable via brainx_inject_base = False if you want the historical 301-redirect behavior.
• Sitemap + index canonical (v0.6.0+): on build-finished, writes sitemap.xml (one <url> per source document) so search engines can find every page; the landing site's sitemap-index.xml lists each /<pkg>/sitemap.xml. The docs index's canonical becomes /<pkg>/ instead of Sphinx's default /<pkg>/index.html, matching every link to it; the sitemap uses the same URL.

Local development

To preview a header change against your local landing-site build before pushing:

BRAINX_HEADER_LOCAL=/path/to/brainx.chaobrain.com/dist/shared-header sphinx-build -b html docs docs/_build/html

Supported themes

sphinx_book_theme, pydata_sphinx_theme (the bd-* selector family). Other themes will still render the BrainX header but without button delegation; their native header is unaffected.