{"id":48718223,"url":"https://github.com/relicloops/clarity","last_synced_at":"2026-04-17T23:01:54.659Z","repository":{"id":350708646,"uuid":"1207950357","full_name":"relicloops/clarity","owner":"relicloops","description":"A modern Sphinx theme with phosphor-green / UV-violet dual-accent palette, built-in AI documentation assistant (OpenRouter), GDPR consent banner, draggable chatbot with settings overlay, retro 404 page, and update checker. Dark / light / system modes, responsive, keyboard-navigable.","archived":false,"fork":false,"pushed_at":"2026-04-16T14:50:40.000Z","size":306,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-16T22:04:08.864Z","etag":null,"topics":["accessibility","ai-assistant","chatbot","consent","dark-mode","documentation","gdpr","light-mode","openrouter","pygments","python","responsive","sphinx","sphinx-theme"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/sphinx-clarity/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/relicloops.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["relicloops"]}},"created_at":"2026-04-11T16:12:25.000Z","updated_at":"2026-04-16T14:50:27.000Z","dependencies_parsed_at":"2026-04-16T22:00:34.207Z","dependency_job_id":null,"html_url":"https://github.com/relicloops/clarity","commit_stats":null,"previous_names":["relicloops/clarity"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/relicloops/clarity","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/relicloops%2Fclarity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/relicloops%2Fclarity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/relicloops%2Fclarity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/relicloops%2Fclarity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/relicloops","download_url":"https://codeload.github.com/relicloops/clarity/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/relicloops%2Fclarity/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31949435,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-17T17:29:20.459Z","status":"ssl_error","status_checked_at":"2026-04-17T17:28:47.801Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","ai-assistant","chatbot","consent","dark-mode","documentation","gdpr","light-mode","openrouter","pygments","python","responsive","sphinx","sphinx-theme"],"created_at":"2026-04-11T18:24:01.499Z","updated_at":"2026-04-17T23:01:54.619Z","avatar_url":"https://github.com/relicloops.png","language":"JavaScript","funding_links":["https://github.com/sponsors/relicloops"],"categories":[],"sub_categories":[],"readme":"# Clarity\n\nA clean, modern Sphinx theme with a phosphor-green / UV-violet dual-accent\npalette and a built-in AI documentation assistant.\n\n## Features\n\n- **Dark / light / system** theme toggle with Unicode glyphs (sun / moon / half-circle), remembered across visits\n- **Dual-accent palette** -- phosphor-green in dark mode, UV-violet in light\n- **Three-column layout** -- sidebar, content, collapsible on-this-page table of contents (sticky on desktop, collapsible below header on mobile)\n- **Responsive** -- desktop, tablet, and mobile breakpoints at 1100 / 900 / 640 px\n- **Keyboard navigation** -- arrow keys for prev/next, `/` to focus search\n- **Text size controls** -- readers can scale the article 75 % -- 150 %, all components scale together (em units); a floating percentage badge above the `-` / `+` pair shows the current size at a glance\n- **Language-tagged code blocks** with extended Pygments token coverage for Python, Rust, Go, JS, C\n- **Dual logo support** -- different images for dark and light modes\n- **AI assistant** -- page-aware chatbot with `/goto` navigation, `/read` page-summarization, and a `⚙` settings overlay where readers can override model, temperature, reasoning effort, and every other `chatbot_*` option from `conf.py` at runtime\n- **Chatbot digest / ingest** -- export the current conversation as JSON, Markdown + JSON (zip), or plain text + JSON (zip); re-import any JSON later via Replace or Append. API keys are never included\n- **Enhanced search** -- per-match `[line:col]` positions grouped by file, plain-text or `/regex/` matching, a `+ N more` toggle per file, and a rainbow-glowing `⁇` overlay while pages are being scanned\n- **Draggable and resizable** chatbot panel with geometry persistence, minimize/restore toggle (`─` / `□`), and container queries for responsive inner layout\n- **GDPR / ePrivacy consent** -- built-in banner, no third-party plugins, nothing stored until the reader accepts. Google Fonts loaded only after consent. Declined readers fall back to `sessionStorage` so preferences still work for the current tab\n- **Granular privacy + TTL** -- `Customize...` opens a settings modal where readers pick per-feature CAN / CANNOT and an automatic purge after Never / 1 day / 1 week / 1 month. Kill-switches cover Google Fonts, PyPI, and the OpenRouter API so the chatbot, update checker, and web fonts can be disabled independently\n- **Update checker** -- opt-in PyPI version check (consent-gated, `Opt+U` / `Alt+U` keybinding). Shows a top banner with links to every newer release, and a rainbow-glowing `⊛` spinner in the header while checking\n- **Retro 404 page** -- Press Start 2P pixelated font for the 404 heading (consent-gated Google Font, falls back to system when declined)\n- **Version warning** -- orange sidebar badge when `release` or `version` is missing from `conf.py`, plus a DevTools console warning so deployers notice before publishing\n- **Sidebar version display** -- auto-prefixes `v` when the release string doesn't start with one; supports the `vMAJOR.MINOR.PATCH-BUILD` tag format\n- **6 built-in skins** -- Unicorn (pastel light), Programmer (clean docs light), Matrix (green-on-black), Rainbow (saturated rainbow light), Darcula (deep dark), Coder (editor dark). Footer selector lets readers switch; deployers set a default via `skin` in `conf.py`. When a skin is active, the dark/light/system toggle is disabled\n\n## Install\n\n```bash\npip install sphinx-clarity\n```\n\n## Quick start\n\nCreate a new Sphinx project (if you do not already have one):\n\n```bash\nmkdir docs \u0026\u0026 cd docs\nsphinx-quickstart\n```\n\nEdit `conf.py` to use Clarity:\n\n```python\nhtml_theme = \"clarity\"\n\nhtml_theme_options = {\n    \"default_theme\": \"system\",    # \"dark\", \"light\", or \"system\"\n    \"font_stack\": \"default\",      # \"default\" or \"system\" (no remote fonts)\n    \"navigation_with_keys\": True,\n    \"show_toc_level\": 2,\n}\n```\n\nBuild and serve locally:\n\n```bash\nsphinx-build -b html . _build/html\npython -m http.server -d _build/html 8000\n```\n\nOpen http://localhost:8000.\n\n## Optional: enable the AI assistant\n\nAdd your OpenRouter settings to `conf.py`:\n\n```python\nhtml_theme_options = {\n    # ...\n    \"chatbot_enabled\": True,\n    \"chatbot_model\": \"openai/gpt-oss-120b:free\",\n}\n```\n\nThe reader supplies their own OpenRouter key in the chat panel -- it is\nstored locally in the browser, never sent to you. Set\n`\"chatbot_enabled\": False` to ship the theme without the assistant.\n\n## Add a logo\n\nDrop logo files into your Sphinx `_static/` folder and reference them:\n\n```python\nhtml_theme_options = {\n    # ...\n    \"light_logo\": \"logo-light.svg\",\n    \"dark_logo\": \"logo-dark.svg\",\n}\n```\n\n## Full walkthrough -- from zero to a docs site\n\nThis is a longer recipe for someone who is new to Sphinx. It mirrors how\nClarity's own docs are organized, so you end up with a similar layout.\n\n### 1. Create a new project\n\n```bash\nmkdir my-docs \u0026\u0026 cd my-docs\npython -m venv .venv\nsource .venv/bin/activate\npip install sphinx sphinx-clarity\nsphinx-quickstart docs\n```\n\nAccept the prompts (separate source and build directories, project\ntitle, author, release). You now have:\n\n```\nmy-docs/\n  docs/\n    Makefile\n    make.bat\n    source/\n      conf.py\n      index.rst\n    build/\n```\n\n### 2. Switch to Clarity\n\nOpen `docs/source/conf.py` and replace the `html_theme` line, then add\na minimal options block:\n\n```python\nhtml_theme = \"clarity\"\n\nhtml_theme_options = {\n    \"default_theme\": \"system\",\n    \"font_stack\": \"default\",\n    \"navigation_with_keys\": True,\n    \"show_toc_level\": 2,\n}\n```\n\nIf you set `release = \"v0.1.0-000\"` near the top of `conf.py`, Clarity\nshows the tag in the sidebar. When `release` is missing, an orange\n\"version not set in conf.py\" warning appears in the sidebar so you\nremember to fill it in before publishing.\n\n### 3. Write your first page\n\nEdit `docs/source/index.rst`:\n\n```rst\nMy Project\n==========\n\nWelcome!\n\n.. toctree::\n   :maxdepth: 2\n\n   guide\n```\n\nCreate `docs/source/guide.rst` alongside it:\n\n```rst\nGetting Started\n===============\n\nInstall::\n\n   pip install my-project\n```\n\n### 4. Build and preview\n\n```bash\nsphinx-build -b html docs/source docs/build/html\npython -m http.server -d docs/build/html 8000\n```\n\nOpen \u003chttp://localhost:8000\u003e. Toggle the theme, scale the text with the\n`-` / `+` buttons, try the keyboard navigation.\n\n### 5. Add a logo (optional)\n\nPut your logo files in `docs/source/_static/` and reference them from\n`conf.py`:\n\n```python\nhtml_theme_options = {\n    # ...\n    \"light_logo\": \"logo-light.svg\",\n    \"dark_logo\": \"logo-dark.svg\",\n}\n```\n\n### 6. Enable the AI assistant (optional)\n\nFlip on the chatbot and pick a model:\n\n```python\nhtml_theme_options = {\n    # ...\n    \"chatbot_enabled\": True,\n    \"chatbot_model\": \"openai/gpt-oss-120b:free\",\n}\n```\n\nRebuild. Each reader opens the chat with the `∂` button, pastes their\nown OpenRouter key (stored only in their browser), and can ask\nquestions about the current page.\n\n### 7. Tweak the assistant at runtime\n\nClick the `⚙` button in the chat panel to open the settings overlay.\nEvery `chatbot_*` option from `conf.py` is editable there -- model,\ntemperature, reasoning effort, system prompt. Overrides are saved in\nthe reader's own browser and don't affect anyone else. Hover any field\nto see a one-line explanation in the warning bar at the bottom of the\noverlay.\n\n### 8. Enable the update checker (optional)\n\n```python\nhtml_theme_options = {\n    # ...\n    \"update_check\": True,\n}\n```\n\nWhen enabled (and after the reader accepts the privacy banner), the\ntheme checks PyPI once per tab session for newer versions of\n`sphinx-clarity`. If any exist, a top banner appears with version\nlinks and a `pip install --upgrade` hint. The banner is dismissible\nand stays dismissed permanently (stored in localStorage).\n\nYou can also press `Opt+U` (macOS) or `Alt+U` (Win/Linux) to force\na fresh check at any time -- it bypasses the cache and the dismissed\nstate. A rainbow-glowing `⊛` spinner appears in the header while the\ncheck runs.\n\n### 9. Add a retro 404 page (optional)\n\n```python\nhtml_theme_options = {\n    # ...\n    \"retro_404\": True,\n}\n\nhtml_additional_pages = {\"404\": \"notfound.html\"}\n```\n\nBuilds a `404.html` with a neon-glow `404` heading in the Press\nStart 2P pixelated font (loaded via Google Fonts after consent).\nMost hosting providers serve `404.html` automatically for missing\npaths. Falls back to the heading font when consent is declined or\n`retro_404` is `False`.\n\n### 10. Pick a skin (optional)\n\nThe footer has a \"Skin\" dropdown. Readers can switch at any time.\nTo set a default for your site:\n\n```python\nhtml_theme_options = {\n    # ...\n    \"skin\": \"matrix\",  # or \"unicorn\", \"programmer\", \"rainbow\", \"darcula\", \"coder\"\n}\n```\n\nWhen a skin is active, the dark/light/system toggle disappears -- the\nskin controls the full palette. Switching back to \"Default\" restores\nthe toggle.\n\n### 11. Keep going\n\n- `configuration.rst` -- every `html_theme_options` field and default.\n- `chatbot.rst` -- assistant setup, slash commands, settings overlay.\n- `privacy.rst` -- exactly what Clarity stores and where.\n\nYou can add more pages to `docs/source/`, link them from the `toctree`\nin `index.rst`, and rerun `sphinx-build`. That's the whole loop.\n\n## Documentation\n\nFull documentation -- configuration reference, privacy details, chatbot\nsetup -- is published at the project docs site, and the sources live\nunder `docs/source/` on\n[GitHub](https://github.com/relicloops/clarity/tree/main/docs/source)\nif you prefer to browse them there.\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frelicloops%2Fclarity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frelicloops%2Fclarity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frelicloops%2Fclarity/lists"}