From 3647a7854bdd8d147b111a5164cb39fb1422f899 Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Mon, 9 Feb 2026 21:46:53 +0100 Subject: [PATCH 1/3] Restructured TOC. Added captions. --- .../static/css/furo-collapsible-toc.scss | 8 ++++ src/crate/theme/rtd/sidebartoc.py | 43 +++++++++++-------- 2 files changed, 32 insertions(+), 19 deletions(-) diff --git a/src/crate/theme/rtd/crate/static/css/furo-collapsible-toc.scss b/src/crate/theme/rtd/crate/static/css/furo-collapsible-toc.scss index 0a7db2f5..d9fc58ea 100644 --- a/src/crate/theme/rtd/crate/static/css/furo-collapsible-toc.scss +++ b/src/crate/theme/rtd/crate/static/css/furo-collapsible-toc.scss @@ -2,6 +2,14 @@ * Furo-Compatible Collapsible Navigation styling for CrateDB Theme */ +/* Reduce spacing around TOC section captions */ +ul.toctree.nav p.caption { + margin-top: 0.75rem; + margin-bottom: 0.25rem; + padding-top: 0; + padding-bottom: 0; +} + .bs-docs-sidenav.sidebar-tree { /* Match label height to our link height */ li.has-children > label { diff --git a/src/crate/theme/rtd/sidebartoc.py b/src/crate/theme/rtd/sidebartoc.py index 079445b8..49dccbfa 100644 --- a/src/crate/theme/rtd/sidebartoc.py +++ b/src/crate/theme/rtd/sidebartoc.py @@ -131,31 +131,36 @@ def _get_toctree(maxdepth=-1, titles_only=True, collapse=False): parts.append('') parts.append('') - # Add Overview and top level entries defined in the Guide's toctree. - # The Guide project is the only one that has multiple top-level entries. + # Add Guide's toctree entries (Overview, Getting Started, captions, etc.) if project == 'CrateDB: Guide': - if pagename == 'index': - parts.append('
  • ') - parts.append(f'Overview') - parts.append('
    • ') - else: - parts.append('
  • ') - parts.append(f'Overview') - parts.append('
    • ') parts.append(_get_toctree()) else: - # Show Overview link to Guide's index (no icon - it's just an index page) - parts.append('
  • Overview
    • ') - # Add Guide's level 1 entries with icons - builder.add_nav_link('Getting Started','/docs/guide/start/') - builder.add_nav_link('Handbook', '/docs/guide/handbook/') - - # Add individual projects + # Show Guide's navigation structure when viewing other projects + # This must be kept in sync with the Guide's index.md toctree + builder.add_nav_link('Overview', '/docs/guide/overview/') + builder.add_nav_link('Getting Started', '/docs/guide/start/') + + # BUILD section + parts.append('

    Build

    ') + builder.add_nav_link('Load data into CrateDB', '/docs/guide/ingest/') + builder.add_nav_link('Connect / Drivers', '/docs/guide/connect/') + builder.add_nav_link('Integrations', '/docs/guide/integrate/') + builder.add_nav_link('All Features', '/docs/guide/feature/') + + # OPERATIONS section + parts.append('

    Operations

    ') + builder.add_nav_link('Install', '/docs/guide/install/') + builder.add_nav_link('Administration', '/docs/guide/admin/') + builder.add_nav_link('Performance guides', '/docs/guide/performance/') + + # Add Reference section with caption + parts.append('

    Reference

    ') builder.add_project_nav_item('CrateDB Cloud', 'CrateDB Cloud', '/docs/cloud/') builder.add_project_nav_item('CrateDB: Reference', 'Reference Manual', '/docs/crate/reference/') - # Start new section with a border - builder.add_project_nav_item('CrateDB: Admin UI', 'Admin UI', '/docs/crate/admin-ui/', border_top=True) + # Add Tools section with caption + parts.append('

    Tools

    ') + builder.add_project_nav_item('CrateDB: Admin UI', 'Admin UI', '/docs/crate/admin-ui/') builder.add_project_nav_item('CrateDB: Crash CLI', 'CrateDB CLI', '/docs/crate/crash/') builder.add_project_nav_item('CrateDB Cloud: Croud CLI', 'Cloud CLI', '/docs/cloud/cli/') From a93958b3f83f366e78361c17f0592bd0679020fe Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Tue, 10 Feb 2026 17:40:29 +0100 Subject: [PATCH 2/3] Add icons to TOC captions --- .../theme/rtd/crate/static/css/custom.css | 1 + .../static/css/furo-collapsible-toc.scss | 14 +++++++-- src/crate/theme/rtd/icons.py | 30 +++++++++++++++++++ src/crate/theme/rtd/sidebartoc.py | 22 ++++++++++---- 4 files changed, 60 insertions(+), 7 deletions(-) create mode 100644 src/crate/theme/rtd/icons.py diff --git a/src/crate/theme/rtd/crate/static/css/custom.css b/src/crate/theme/rtd/crate/static/css/custom.css index 5d497f20..f247735c 100644 --- a/src/crate/theme/rtd/crate/static/css/custom.css +++ b/src/crate/theme/rtd/crate/static/css/custom.css @@ -1865,3 +1865,4 @@ div.cell_output tbody tr:nth-child(odd):hover, div.cell_output tbody tr:nth-child(even):hover { background: rgba(66, 165, 245, 0.2); } + diff --git a/src/crate/theme/rtd/crate/static/css/furo-collapsible-toc.scss b/src/crate/theme/rtd/crate/static/css/furo-collapsible-toc.scss index d9fc58ea..468190a6 100644 --- a/src/crate/theme/rtd/crate/static/css/furo-collapsible-toc.scss +++ b/src/crate/theme/rtd/crate/static/css/furo-collapsible-toc.scss @@ -2,12 +2,22 @@ * Furo-Compatible Collapsible Navigation styling for CrateDB Theme */ -/* Reduce spacing around TOC section captions */ +/* TOC section captions */ ul.toctree.nav p.caption { - margin-top: 0.75rem; + margin-top: 1.25rem; margin-bottom: 0.25rem; padding-top: 0; padding-bottom: 0; + font-size: 13px; /* Match TOC link size */ +} + +/* Caption icons in navigation */ +.caption-icon { + width: 14px; + height: 14px; + margin-right: 6px; + vertical-align: -1px; + display: inline-block; } .bs-docs-sidenav.sidebar-tree { diff --git a/src/crate/theme/rtd/icons.py b/src/crate/theme/rtd/icons.py new file mode 100644 index 00000000..5bee8b0d --- /dev/null +++ b/src/crate/theme/rtd/icons.py @@ -0,0 +1,30 @@ +# Caption icons for sidebar navigation (inline SVGs with color accents) +# Using primary brand color #19c0ea for accent elements + +ICON_BUILD = ''' + + + +''' + +ICON_OPERATIONS = ''' + + + + + + +''' + +ICON_REFERENCE = ''' + + + + + +''' + +ICON_TOOLS = ''' + + +''' diff --git a/src/crate/theme/rtd/sidebartoc.py b/src/crate/theme/rtd/sidebartoc.py index 49dccbfa..e02222ca 100644 --- a/src/crate/theme/rtd/sidebartoc.py +++ b/src/crate/theme/rtd/sidebartoc.py @@ -24,6 +24,8 @@ import os import re +from crate.theme.rtd.icons import ICON_BUILD, ICON_OPERATIONS, ICON_REFERENCE, ICON_TOOLS + def _slugify_id(text): """Normalize text to a safe HTML ID: alphanumerics and hyphens only.""" @@ -133,7 +135,17 @@ def _get_toctree(maxdepth=-1, titles_only=True, collapse=False): # Add Guide's toctree entries (Overview, Getting Started, captions, etc.) if project == 'CrateDB: Guide': - parts.append(_get_toctree()) + toctree_html = _get_toctree() + # Add icons to captions + toctree_html = toctree_html.replace( + 'Build', + f'{ICON_BUILD}Build' + ) + toctree_html = toctree_html.replace( + 'Operations', + f'{ICON_OPERATIONS}Operations' + ) + parts.append(toctree_html) else: # Show Guide's navigation structure when viewing other projects # This must be kept in sync with the Guide's index.md toctree @@ -141,25 +153,25 @@ def _get_toctree(maxdepth=-1, titles_only=True, collapse=False): builder.add_nav_link('Getting Started', '/docs/guide/start/') # BUILD section - parts.append('

    Build

    ') + parts.append(f'

    {ICON_BUILD}Build

    ') builder.add_nav_link('Load data into CrateDB', '/docs/guide/ingest/') builder.add_nav_link('Connect / Drivers', '/docs/guide/connect/') builder.add_nav_link('Integrations', '/docs/guide/integrate/') builder.add_nav_link('All Features', '/docs/guide/feature/') # OPERATIONS section - parts.append('

    Operations

    ') + parts.append(f'

    {ICON_OPERATIONS}Operations

    ') builder.add_nav_link('Install', '/docs/guide/install/') builder.add_nav_link('Administration', '/docs/guide/admin/') builder.add_nav_link('Performance guides', '/docs/guide/performance/') # Add Reference section with caption - parts.append('

    Reference

    ') + parts.append(f'

    {ICON_REFERENCE}Reference

    ') builder.add_project_nav_item('CrateDB Cloud', 'CrateDB Cloud', '/docs/cloud/') builder.add_project_nav_item('CrateDB: Reference', 'Reference Manual', '/docs/crate/reference/') # Add Tools section with caption - parts.append('

    Tools

    ') + parts.append(f'

    {ICON_TOOLS}Tools

    ') builder.add_project_nav_item('CrateDB: Admin UI', 'Admin UI', '/docs/crate/admin-ui/') builder.add_project_nav_item('CrateDB: Crash CLI', 'CrateDB CLI', '/docs/crate/crash/') builder.add_project_nav_item('CrateDB Cloud: Croud CLI', 'Cloud CLI', '/docs/cloud/cli/') From c4edd40d464347e5def3975d9151c871a2866ae8 Mon Sep 17 00:00:00 2001 From: Brian Munkholm Date: Wed, 11 Feb 2026 23:14:41 +0100 Subject: [PATCH 3/3] Adjust captions and fix Overview boldness --- src/crate/theme/rtd/crate/static/js/custom.js | 9 +++++++++ src/crate/theme/rtd/sidebartoc.py | 17 +++++++++++++---- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/src/crate/theme/rtd/crate/static/js/custom.js b/src/crate/theme/rtd/crate/static/js/custom.js index ed542ff7..b69c4095 100644 --- a/src/crate/theme/rtd/crate/static/js/custom.js +++ b/src/crate/theme/rtd/crate/static/js/custom.js @@ -160,4 +160,13 @@ document.addEventListener('DOMContentLoaded', () => { // If
      has children, default behavior (toggle checkbox) applies }); }); + + // Mark Overview as current on root page. The overview content lives in + // index.md but Sphinx only marks toctree entries as "current" when the + // pagename matches. Since the Overview href is rewritten to "#" (self) + // on the root page, we detect that and add the current class. + document.querySelectorAll('.sidebar-tree .toctree-l1 > a[href="#"]').forEach((a) => { + a.classList.add('current'); + a.closest('li').classList.add('current'); + }); }); diff --git a/src/crate/theme/rtd/sidebartoc.py b/src/crate/theme/rtd/sidebartoc.py index e02222ca..cef5089c 100644 --- a/src/crate/theme/rtd/sidebartoc.py +++ b/src/crate/theme/rtd/sidebartoc.py @@ -126,6 +126,7 @@ def _get_toctree(maxdepth=-1, titles_only=True, collapse=False): parts.append('
    • All database drivers
      • ') return ''.join(parts) + # Start CrateDB docs TOC with a Search box parts.append('
    • ') parts.append('
      ') @@ -136,6 +137,14 @@ def _get_toctree(maxdepth=-1, titles_only=True, collapse=False): # Add Guide's toctree entries (Overview, Getting Started, captions, etc.) if project == 'CrateDB: Guide': toctree_html = _get_toctree() + # Rewrite the Overview sidebar link to point to root (index.md) + # instead of overview/. The overview content lives in index.md; + # overview/index.md is only kept for toctree structure. + toctree_html = re.sub( + r'href="([^"]*overview/(?:index\.html)?)"', + f'href="{master_path}"', + toctree_html + ) # Add icons to captions toctree_html = toctree_html.replace( 'Build', @@ -149,7 +158,7 @@ def _get_toctree(maxdepth=-1, titles_only=True, collapse=False): else: # Show Guide's navigation structure when viewing other projects # This must be kept in sync with the Guide's index.md toctree - builder.add_nav_link('Overview', '/docs/guide/overview/') + builder.add_nav_link('Overview', '/docs/guide/') builder.add_nav_link('Getting Started', '/docs/guide/start/') # BUILD section @@ -161,14 +170,14 @@ def _get_toctree(maxdepth=-1, titles_only=True, collapse=False): # OPERATIONS section parts.append(f'

      {ICON_OPERATIONS}Operations

      ') - builder.add_nav_link('Install', '/docs/guide/install/') + builder.add_nav_link('Installation', '/docs/guide/install/') builder.add_nav_link('Administration', '/docs/guide/admin/') builder.add_nav_link('Performance guides', '/docs/guide/performance/') # Add Reference section with caption - parts.append(f'

      {ICON_REFERENCE}Reference

      ') + parts.append(f'

      {ICON_REFERENCE}References

      ') builder.add_project_nav_item('CrateDB Cloud', 'CrateDB Cloud', '/docs/cloud/') - builder.add_project_nav_item('CrateDB: Reference', 'Reference Manual', '/docs/crate/reference/') + builder.add_project_nav_item('CrateDB: Reference', 'CrateDB', '/docs/crate/reference/') # Add Tools section with caption parts.append(f'

      {ICON_TOOLS}Tools

      ')