Skip to content

Restructure TOC: Add groups, captions, and icons #701

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bmunkholm merged 3 commits into from
Feb 12, 2026
Merged

Restructure TOC: Add groups, captions, and icons #701

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3647a78
Restructured TOC. Added captions.
bmunkholm Feb 9, 2026
a93958b
Add icons to TOC captions
bmunkholm Feb 10, 2026
c4edd40
Adjust captions and fix Overview boldness
bmunkholm Feb 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/crate/theme/rtd/crate/static/css/custom.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}

18 changes: 18 additions & 0 deletions src/crate/theme/rtd/crate/static/css/furo-collapsible-toc.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,24 @@
* Furo-Compatible Collapsible Navigation styling for CrateDB Theme
*/

/* TOC section captions */
ul.toctree.nav p.caption {
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 {
/* Match label height to our link height */
li.has-children > label {
Expand Down
9 changes: 9 additions & 0 deletions src/crate/theme/rtd/crate/static/js/custom.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,4 +160,13 @@ document.addEventListener('DOMContentLoaded', () => {
// If <ul> 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');
});
});
30 changes: 30 additions & 0 deletions src/crate/theme/rtd/icons.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Caption icons for sidebar navigation (inline SVGs with color accents)
# Using primary brand color #19c0ea for accent elements

ICON_BUILD = '''<svg class="caption-icon" viewBox="1 4 22 19" fill="none" stroke-width="1.5">
<path d="M3 21h18M6 21V12l6-5 6 5v9" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"/>
<path d="M9 21v-6h6v6" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"/>
<rect x="10" y="8" width="4" height="3" rx="0.5" fill="#19c0ea" stroke="#19c0ea"/>
</svg>'''

ICON_OPERATIONS = '''<svg class="caption-icon" viewBox="0 0 24 24" fill="none" stroke-width="1.5">
<rect x="3" y="4" width="18" height="6" rx="1" stroke="currentColor"/>
<rect x="3" y="14" width="18" height="6" rx="1" stroke="currentColor"/>
<circle cx="7" cy="7" r="1.5" fill="#19c0ea"/>
<circle cx="7" cy="17" r="1.5" fill="#19c0ea"/>
<line x1="11" y1="7" x2="17" y2="7" stroke="currentColor" stroke-linecap="round"/>
<line x1="11" y1="17" x2="17" y2="17" stroke="currentColor" stroke-linecap="round"/>
</svg>'''

ICON_REFERENCE = '''<svg class="caption-icon" viewBox="0 0 24 24" fill="none" stroke-width="1.5">
<path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H19" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"/>
<path d="M6.5 2H19v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"/>
<rect x="17" y="4" width="2" height="8" rx="0.5" fill="#19c0ea"/>
<line x1="8" y1="7" x2="14" y2="7" stroke="currentColor" stroke-linecap="round"/>
<line x1="8" y1="11" x2="14" y2="11" stroke="currentColor" stroke-linecap="round"/>
</svg>'''

ICON_TOOLS = '''<svg class="caption-icon" viewBox="0 0 24 24" fill="none" stroke-width="1.5">
<path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"/>
<circle cx="17" cy="7" r="2" fill="#19c0ea" opacity="0.6"/>
</svg>'''
68 changes: 47 additions & 21 deletions src/crate/theme/rtd/sidebartoc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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."""
Expand Down Expand Up @@ -124,38 +126,62 @@ def _get_toctree(maxdepth=-1, titles_only=True, collapse=False):
parts.append('<li class="navleft-item border-top"><a href="https://cratedb.com/docs/guide/connect/">All database drivers</a></li>')
return ''.join(parts)


# Start CrateDB docs TOC with a Search box
parts.append('<li>')
parts.append('<div class="search-link">')
parts.append('<div id="docsearch" style="min-height: 36px; margin-bottom: 20px;"></div>')
parts.append('</div>')
parts.append('</li>')

# 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('<li class="current">')
parts.append(f'<a class="current-active" href="{master_path}">Overview</a>')
parts.append('</li>')
else:
parts.append('<li class="navleft-item">')
parts.append(f'<a href="{master_path}">Overview</a>')
parts.append('</li>')
parts.append(_get_toctree())
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(
'<span class="caption-text">Build</span>',
f'{ICON_BUILD}<span class="caption-text">Build</span>'
)
toctree_html = toctree_html.replace(
'<span class="caption-text">Operations</span>',
f'{ICON_OPERATIONS}<span class="caption-text">Operations</span>'
)
parts.append(toctree_html)
else:
# Show Overview link to Guide's index (no icon - it's just an index page)
parts.append('<li class="navleft-item"><a href="/docs/guide/">Overview</a></li>')
# 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/')
builder.add_nav_link('Getting Started', '/docs/guide/start/')

# BUILD section
parts.append(f'<p class="caption" role="heading">{ICON_BUILD}<span class="caption-text">Build</span></p>')
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(f'<p class="caption" role="heading">{ICON_OPERATIONS}<span class="caption-text">Operations</span></p>')
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'<p class="caption" role="heading">{ICON_REFERENCE}<span class="caption-text">References</span></p>')
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/')

# 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(f'<p class="caption" role="heading">{ICON_TOOLS}<span class="caption-text">Tools</span></p>')
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/')

Expand Down