Sphinx extension that injects the canonical BrainX brand header and footer into any docs site, fetched live from brainx.chaobrain.com.
Project description
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.
| Setting | Default | Purpose |
|---|---|---|
brainx_header_url |
"https://brainx.chaobrain.com/shared-header" |
Where to fetch the canonical header |
brainx_header_ttl |
3600 |
Cache TTL in seconds |
brainx_header_offline |
False |
Use cache only, never fetch |
brainx_header_local |
None |
Path to a local shared-header dir for live preview |
brainx_inject_base |
True |
Inject <base href="{html_baseurl}"> into the docs index so the site works at both /<pkg> and /<pkg>/ (no-op if html_baseurl is unset) |
brainx_ssr_inject |
True |
Post-process every built .html to embed the header/footer markup in the document at first paint (no flash, SEO, no-JS, screen readers). The JS injection remains as a self-skipping fallback. |
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.cssfrom 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_themenative 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: 6remfor 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 viadata-bx-header/data-bx-footermarkers; the JS preambles also self-skip those markers so they become a pure behavior payload (plus a fallback if SSR is disabled). Disable viabrainx_ssr_inject = FalseorBRAINX_SSR_INJECT=0. - Slash-tolerant index: injects
<base href="{html_baseurl}">into the docs index page, so the site renders correctly whether reached viahttps://host/<pkg>orhttps://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 viabrainx_inject_base = Falseif you want the historical 301-redirect behavior.
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.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file brainx_sphinx_header-0.5.0.tar.gz.
File metadata
- Download URL: brainx_sphinx_header-0.5.0.tar.gz
- Upload date:
- Size: 14.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.8
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
01ce70fe3a14b585443695ef7e94ce5d365c4fe14b978fd52ccae048441dd154
|
|
| MD5 |
3bee6da377f6f6c93cf9a63efc7b5ce0
|
|
| BLAKE2b-256 |
597df56c7fcdf0d61c607324351920879593ad6213eb8d4d23f82613a933f7b9
|
File details
Details for the file brainx_sphinx_header-0.5.0-py3-none-any.whl.
File metadata
- Download URL: brainx_sphinx_header-0.5.0-py3-none-any.whl
- Upload date:
- Size: 13.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.8
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
835745bbc72d136a40d00b597ec0a7c43e013392abdfd03943dcc1b9f76f1a12
|
|
| MD5 |
6f734dd76dd5e1335f0562c3b6f9e2e0
|
|
| BLAKE2b-256 |
2c47e3d1d64a60b5a9883f79ae2a8882b5513baea9c616cfb3e7531a1a7dca32
|
