docs: implement the Lance Docs design as the mkdocs site theme by Xuanwo · Pull Request #7821 · lance-format/lance

Xuanwo · 2026-07-16T07:57:35Z

Why

Implements the new "Lance Docs" design as the real mkdocs site, so make serve / make build produce it directly.

The design is delivered by a dedicated custom MkDocs theme (docs/theme/) whose markup and CSS are ported from the design implementation: header with section tabs, GitHub star count and Discord link, grouped side navigation with ink rules, right-hand scroll-spy table of contents, light/dark mode, and the hero/stats/features homepage with real highlighted code blocks.

MkDocs keeps providing what fits the design — the markdown pipeline (admonitions, content tabs, snippets, autolinked URLs), awesome-pages navigation, and the search plugin's index — while the theme owns everything user-facing, including a lightweight search overlay (/ or Cmd/Ctrl+K) and on-demand mermaid rendering. mkdocs-material is no longer a dependency.

Preview:

cd docs
make serve

Summary by CodeRabbit

New Features
- Rolled out a custom documentation theme with a refreshed homepage, improved typography, navigation, and responsive layout.
- Added light/dark mode switching with saved preference.
- Introduced a search overlay with keyboard shortcuts, ranked results, and highlighted matches.
- Enhanced docs rendering with copy-to-clipboard code controls, on-demand Mermaid diagrams, horizontal table scrolling, and TOC scroll tracking.
- Added a dedicated 404 page and improved GitHub star display with caching/offline fallback.
Documentation
- Updated the MkDocs configuration and theme setup to use the new theme design.

coderabbitai · 2026-07-16T07:57:43Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 43079793-e347-4fb8-b551-ab21b9669d96

📥 Commits

Reviewing files that changed from the base of the PR and between 22dfa3c and 535bc64.

📒 Files selected for processing (1)

docs/theme/home.html

📝 Walkthrough

Walkthrough

The documentation site migrates from MkDocs Material to a custom Lance Docs theme, adding new templates, design tokens, responsive styling, and client-side features for themes, search, Mermaid, code blocks, navigation, and GitHub star counts.

Changes

Custom documentation theme

Layer / File(s)	Summary
Theme configuration and shared foundation `docs/mkdocs.yml`, `docs/pyproject.toml`, `docs/theme/base.html`, `docs/theme/404.html`, `docs/theme/assets/tokens.css`, `docs/README.md`	MkDocs now loads the custom theme, uses updated dependencies, renders shared metadata/header/footer/search structures, and supports light/dark design tokens and a custom 404 page.
Homepage and documentation layouts `docs/theme/home.html`, `docs/theme/main.html`, `docs/theme/assets/site.css`	New templates render the homepage and documentation pages with navigation, breadcrumbs, TOC, pagination, hero content, feature sections, article styling, and responsive layouts.
Browser-side documentation enhancements `docs/theme/assets/site.js`, `docs/theme/assets/site.css`	Client-side behavior adds theme persistence, GitHub star caching, code-copy controls, table wrapping, Mermaid rendering, TOC scroll tracking, and ranked search overlay interactions.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Browser
  participant site.js
  participant GitHubAPI
  participant SearchIndex
  participant MermaidESM
  Browser->>site.js: Initialize theme and documentation enhancements
  site.js->>GitHubAPI: Fetch uncached star count
  GitHubAPI-->>site.js: Return stargazers count
  site.js->>SearchIndex: Load search index when search opens
  SearchIndex-->>site.js: Return indexed documents
  site.js->>MermaidESM: Load Mermaid when diagrams are present
  MermaidESM-->>Browser: Render diagrams
  site.js-->>Browser: Update search results, code blocks, TOC, and stars

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: implementing the Lance Docs design as the MkDocs site theme.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch xuanwo/lance-docs-design-7249da

_{Comment @coderabbitai help to get the list of available commands.}

- Use the wide Lance logo in the header; add GitHub star count and a Discord button to the top navigation - Link the VLDB paper above the fold (hero kicker + stats band) - Replace homepage code-snippet images with real highlighted code blocks - Add a light/dark theme with a header toggle (follows prefers-color-scheme, persists in localStorage) - Add a right-hand "On this page" TOC with scroll-spy highlight - Fix unreadable text selection inside dark code blocks - Fix integration links to match the assembled lance.org site and autolink bare URLs (community subproject tables)

Replace the standalone docs/web prototype with a full mkdocs-material integration so `make serve` / `make build` produce the new design: - lance-tokens.css maps the design tokens (white/ink/#625EFF, Space Grotesk / IBM Plex Sans / JetBrains Mono) onto both Material color schemes; code blocks stay ink-dark in light and dark mode - lance-theme.css restyles the Material chrome and typeset content (header, tabs, sidebars, TOC, admonitions, tables, buttons) with square corners and ink rules, and fixes selection contrast inside dark code blocks - overrides/home.html + home.css rebuild the homepage: hero with a VLDB '25 paper link above the fold, stats band, and numbered features with real highlighted code blocks instead of images - overrides/partials/header.html adds a Discord button next to the GitHub repo info (Material already renders the star count there) - pymdownx.magiclink autolinks the bare repository URLs in the community subproject tables Material keeps providing search, instant navigation, the palette toggle, and the scroll-spy table of contents.

… design Restyling Material could not reproduce the design, so the site now uses a dedicated MkDocs theme (docs/theme/) whose markup and CSS are ported directly from the design implementation: - base/main/home/404 templates render the design's header (wide logo, section tabs, GitHub stars, Discord, theme toggle), grouped sidenav with ink rules, breadcrumbs, right-hand "On this page" TOC, prev/next footer navigation, and the hero/stats/features homepage - tokens.css + site.css carry the design system (white/ink/#625EFF, Space Grotesk / IBM Plex Sans / JetBrains Mono, square corners, 1px ink rules) with a mirrored dark theme; article styles target python-markdown/pymdownx output (admonitions, content tabs, details, tables, pygments code blocks with language bar + copy button) - site.js adds the theme toggle, GitHub star count, TOC scroll-spy, code-block chrome, a lightweight search overlay on the standard search plugin index, and on-demand mermaid rendering - mkdocs-material is removed from the dependencies; pymdown-extensions and pygments are now direct dependencies

Reduce the visual weight of the docs theme and add richer affordances: - Lighten box outlines from --line-1 to --line-2 (code blocks, admonitions, details, content tabs, homepage code windows). - Add rounded corners via new --radius-box / --radius-chip tokens. - Drop the inline-code border for a cleaner filled chip in both themes. - Add Material-style type icons to admonition titles via CSS masks, colored by severity through currentColor. - Render Python/Rust/Java/Bash language logos in the code-bar label. - Switch the monospace font to Roboto Mono to match the previous Material theme default. Co-Authored-By: Claude Fable 5 <[email protected]>

prrao87 · 2026-07-17T14:02:57Z

@Xuanwo minor CSS changes (not sure if you think this needs to be updated in the design template you stored elsewhere), but I think this makes the code blocks and admonition boxes much more aesthetic and easier on the eyes. Tested locally in light and dark mode and looks great.

Summary

Softens the docs theme's visual weight and adds language/severity affordances. All changes are in docs/theme/assets/.

CSS changes

`tokens.css` — design tokens

Monospace font: --font-mono changed from JetBrains Mono → Roboto Mono (the previous Material theme default), with the Google Fonts @import updated to match.
New radius tokens: --radius-box: 6px (code blocks, admonitions, tabs, details) and --radius-chip: 4px (inline code).

`site.css` — component styles

Softer borders: every content-box outline moved from the heavy --line-1 to the faint --line-2 — code blocks (.ld-code + .ld-code__bar), admonitions, details, content tabs (.tabbed-set / .tabbed-labels), and homepage code windows (.ld-feature__code).
Rounded corners: added border-radius: var(--radius-box) + overflow: hidden to those same five box types (the overflow: hidden clips the dark code surface / bar backgrounds to the corner). Inline code got border-radius: var(--radius-chip).
Inline code: removed its border: 1px solid var(--line-2) entirely — now a borderless filled chip in both themes.
Admonition icons: the title is now a flexbox with gap, and a ::before pseudo-element paints a Material-style type icon via CSS mask in currentColor (so each icon inherits its severity color). One --ld-adm-icon custom property is set per admonition type (note, tip, warning, danger, success, info, question, example, bug, quote, etc., including aliases), using inline Material Design Icons SVG data-URIs.
Code-bar layout: .ld-code__bar span became an inline-flex with gap to seat the new language icon, plus a span svg { 13px } rule.

Non-CSS changes

`site.js` — the one behavioral change

Added a LANG_ICONS map (inline SVG viewBox + path for Python, Rust, Java, Bash) and a LANG_ALIASES map (py, rs, sh, shell, console, zsh → canonical). The code-bar builder now prepends the matching language logo before the label when one exists; unknown languages fall back to the plain label as before.

Notes about icons

Icon licensing: admonition icons are Material Design Icons (Apache 2.0); language logos are from Simple Icons (CC0), except Java, which is Devicon's coffee-cup mark.

mkdocs-linkcheck imports requests but does not declare it as a dependency. It was previously satisfied transitively; after the docs theme swap dropped mkdocs-material, requests fell out of the resolved environment and `mkdocs-linkcheck src` failed with ModuleNotFoundError. Declare it explicitly so the docs-check workflow resolves it. Co-Authored-By: Claude Fable 5 <[email protected]>

prrao87

Thanks a lot for this PR, it looks great! 🚀

coderabbitai

Actionable comments posted: 10

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/README.md`:
- Around line 63-69: Replace the bullet list under “Project Structure” with an
ASCII tree diagram showing the repository root, src, theme/assets, mkdocs.yml,
and pyproject.toml, using the proposed descriptions and hierarchy.

In `@docs/theme/assets/site.css`:
- Around line 39-75: Update the responsive rules for .ld-header__actions and the
corresponding secondary header controls so narrow screens collapse or hide
nonessential actions, while preserving the logo and scrollable .ld-topnav.
Ensure the action group no longer forces the header beyond the phone viewport,
including the related styles around the secondary header controls.
- Around line 419-426: Update the .ld-article .headerlink visibility rules so
the permalink becomes opaque when keyboard-focused, in addition to the existing
heading-hover behavior. Use the link’s focus-visible state and preserve the
current opacity transition and hover behavior.
- Line 521: Update the background-color declaration to use the
Stylelint-compliant casing for the currentColor keyword, preserving the existing
styling behavior.

In `@docs/theme/assets/site.js`:
- Around line 136-150: Update loadIndex so a rejected fetch or index-processing
promise clears indexPromise before propagating the error, allowing subsequent
searches to retry; preserve the existing promise caching behavior for successful
loads.
- Around line 75-82: Update the click handler’s clipboard flow around the
.ld-copy listener so “Copied” is set only after navigator.clipboard.writeText
successfully resolves. Guard unavailable APIs and rejected writes without
changing the button text, while preserving the existing reset timeout after
successful copies.
- Around line 157-163: Update highlight so each term is matched only against the
original escaped text, not HTML markup inserted by earlier iterations. Preserve
all existing term escaping and case-insensitive matching, while preventing terms
such as “mark” from modifying previously generated <mark> elements.
- Around line 93-108: Update the dynamic import in the Mermaid rendering flow to
use a pinned exact Mermaid release or an approved self-hosted local module,
rather than the floating `mermaid@11` CDN range. Keep the existing
initialization, rendering, and offline fallback behavior unchanged.

In `@docs/theme/assets/tokens.css`:
- Line 4: Update the Google Fonts import in the stylesheet to use the
repository’s configured `@import` notation instead of url(...), while preserving
the existing font families, weights, and display parameter.

In `@docs/theme/base.html`:
- Around line 104-109: The search dialog markup in docs/theme/base.html lines
104-109 must add aria-modal="true" and an explicit accessible name for the
search input. In docs/theme/assets/site.js lines 216-238, update the search
overlay open/close handling to remember the opener, trap Tab focus within the
dialog, and restore focus to the opener when closing.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 48aaacb1-0b06-401a-9833-a8c437e5fb2a

📥 Commits

Reviewing files that changed from the base of the PR and between 4f90cf4 and 30456ef.

📒 Files selected for processing (13)

docs/README.md
docs/mkdocs.yml
docs/overrides/home.html
docs/pyproject.toml
docs/src/assets/javascripts/nav-expand.js
docs/src/assets/stylesheets/home.css
docs/theme/404.html
docs/theme/assets/site.css
docs/theme/assets/site.js
docs/theme/assets/tokens.css
docs/theme/base.html
docs/theme/home.html
docs/theme/main.html

💤 Files with no reviewable changes (3)

docs/src/assets/javascripts/nav-expand.js
docs/overrides/home.html
docs/src/assets/stylesheets/home.css

Docs code blocks were hardcoded to the ink-dark surface and dark-theme Pygments colors in both themes. Introduce a theme-aware --code-* palette (surface + syntax token colors) so light mode renders code on a light surface with a readable light syntax scheme, matching the rest of the light theme. Dark mode keeps the existing ink palette. The always-dark homepage feature windows are unaffected (they use their own .tok-* classes), and light-theme docs blocks now use the default text selection color instead of the forced light-on-purple. Co-Authored-By: Claude Fable 5 <[email protected]>

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/theme/assets/tokens.css`:
- Line 116: Update the dark-theme --code-com token and the corresponding token
at the additionally referenced location to use a lighter color that provides
sufficient contrast against the dark code surface, while preserving their roles
for comments and prompts.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: dea39ec6-6243-41a2-a499-8ce45360c9c7

📥 Commits

Reviewing files that changed from the base of the PR and between 30456ef and 22dfa3c.

📒 Files selected for processing (2)

docs/theme/assets/site.css
docs/theme/assets/tokens.css

Reframe the hero lead and "What is Lance?" blurb around the workloads Lance targets — vector and full-text search, feature engineering, and model training — with fast random access and scans as the enabling primitive rather than a peer capability. Removes the redundancy of listing random access alongside search, and foregrounds training. Co-Authored-By: Claude Fable 5 <[email protected]>

…7853) <img width="439" height="699" alt="image" src="https://github.com/user-attachments/assets/a62876d0-d4bd-498f-b345-9631c35989c6" /> ## Why The custom "Lance Docs" theme introduced in #7821 was designed desktop-first: on phones and narrow windows the header overflows horizontally (the section tabs get squeezed to zero width while the non-shrinking action buttons push the page wider than the viewport), and the side navigation renders as a long static block above every article, forcing readers to scroll past the whole section index before reaching content. This makes the theme responsive: - Below 960px the header folds into two rows: brand plus icon-only actions on top ("Get started", the GitHub label, and the star count collapse away), with a horizontally scrollable section-tab row underneath. - The side navigation collapses behind a disclosure button labeled with the current section, so articles lead on mobile. - Anchor jumps now land clear of the sticky header (`scroll-margin-top`), the search overlay becomes an edge-to-edge sheet on small screens, and article headings, the footer, and the 404 page scale down. Verified in a real browser at 390px and 320px widths (home, docs pages, tables, code blocks, dark mode, search) and regression-checked the desktop layout, which is unchanged.

## Why Implements the new "Lance Docs" design as the real mkdocs site, so `make serve` / `make build` produce it directly. The design is delivered by a dedicated custom MkDocs theme (`docs/theme/`) whose markup and CSS are ported from the design implementation: header with section tabs, GitHub star count and Discord link, grouped side navigation with ink rules, right-hand scroll-spy table of contents, light/dark mode, and the hero/stats/features homepage with real highlighted code blocks. MkDocs keeps providing what fits the design — the markdown pipeline (admonitions, content tabs, snippets, autolinked URLs), awesome-pages navigation, and the search plugin's index — while the theme owns everything user-facing, including a lightweight search overlay (`/` or `Cmd/Ctrl+K`) and on-demand mermaid rendering. `mkdocs-material` is no longer a dependency. Preview: ```bash cd docs make serve ```  ## Summary by CodeRabbit * **New Features** * Rolled out a custom documentation theme with a refreshed homepage, improved typography, navigation, and responsive layout. * Added light/dark mode switching with saved preference. * Introduced a search overlay with keyboard shortcuts, ranked results, and highlighted matches. * Enhanced docs rendering with copy-to-clipboard code controls, on-demand Mermaid diagrams, horizontal table scrolling, and TOC scroll tracking. * Added a dedicated 404 page and improved GitHub star display with caching/offline fallback. * **Documentation** * Updated the MkDocs configuration and theme setup to use the new theme design.  --------- Co-authored-by: prrao87 <[email protected]> Co-authored-by: Claude Fable 5 <[email protected]> (cherry picked from commit da5ef90)

…7853) <img width="439" height="699" alt="image" src="https://github.com/user-attachments/assets/a62876d0-d4bd-498f-b345-9631c35989c6" /> ## Why The custom "Lance Docs" theme introduced in #7821 was designed desktop-first: on phones and narrow windows the header overflows horizontally (the section tabs get squeezed to zero width while the non-shrinking action buttons push the page wider than the viewport), and the side navigation renders as a long static block above every article, forcing readers to scroll past the whole section index before reaching content. This makes the theme responsive: - Below 960px the header folds into two rows: brand plus icon-only actions on top ("Get started", the GitHub label, and the star count collapse away), with a horizontally scrollable section-tab row underneath. - The side navigation collapses behind a disclosure button labeled with the current section, so articles lead on mobile. - Anchor jumps now land clear of the sticky header (`scroll-margin-top`), the search overlay becomes an edge-to-edge sheet on small screens, and article headings, the footer, and the 404 page scale down. Verified in a real browser at 390px and 320px widths (home, docs pages, tables, code blocks, dark mode, search) and regression-checked the desktop layout, which is unchanged. (cherry picked from commit 0f6fd2e)

docs: add static docs site implementing the Lance Docs design

9f3623c

github-actions Bot added A-docs Documentation documentation Improvements or additions to documentation labels Jul 16, 2026

Xuanwo added 3 commits July 17, 2026 14:28

github-actions Bot added the A-deps Dependency updates label Jul 17, 2026

docs: unify header control heights in the docs theme

77d4318

Xuanwo changed the title ~~docs: add static docs site implementing the Lance Docs design~~ docs: implement the Lance Docs design as the mkdocs site theme Jul 17, 2026

prrao87 marked this pull request as ready for review July 17, 2026 14:10

prrao87 approved these changes Jul 17, 2026

View reviewed changes

coderabbitai Bot reviewed Jul 17, 2026

View reviewed changes

Comment thread docs/theme/assets/tokens.css

prrao87 merged commit da5ef90 into main Jul 17, 2026
10 checks passed

prrao87 deleted the xuanwo/lance-docs-design-7249da branch July 17, 2026 19:35

Xuanwo mentioned this pull request Jul 20, 2026

docs: make the docs site theme usable on mobile and narrow screens #7853

Merged

Uh oh!

Conversation

Xuanwo commented Jul 16, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

prrao87 commented Jul 17, 2026

Summary

CSS changes

tokens.css — design tokens

site.css — component styles

Non-CSS changes

site.js — the one behavioral change

Notes about icons

Uh oh!

prrao87 left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Xuanwo commented Jul 16, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 16, 2026 •

edited

Loading

`tokens.css` — design tokens

`site.css` — component styles

`site.js` — the one behavioral change