Skip to content

fix(docs): wide-table layout — stop clipping, fit backend table - #1905

Merged
igorls merged 2 commits into
developfrom
docs/fix-backend-table-layout
Jun 30, 2026
Merged

fix(docs): wide-table layout — stop clipping, fit backend table#1905
igorls merged 2 commits into
developfrom
docs/fix-backend-table-layout

Conversation

@igorls

@igorls igorls commented Jun 30, 2026

Copy link
Copy Markdown
Member

Summary

Batched, browser-validated frontend fixes for wide tables in the docs.

The docs theme clipped any table wider than the content column instead of
letting it scroll — visible on the storage-backends compatibility table, whose
right-most columns were cut off and unreachable.

Root cause: the custom theme set .vp-doc table { overflow: hidden } to clip
the rounded corners, which also overrode VitePress's default overflow-x: auto.
With overflow hidden, columns that don't fit are simply unreachable.

Changes

.vitepress/theme/style.css (site-wide):

  • .vp-doc tableoverflow-x: auto (keeps rounded corners, restores
    horizontal scroll for any wide table — fixes clipping everywhere, not just one
    page).
  • Denser table cells (8px 16px8px 12px) so comparison tables fit the
    content column without a scrollbar.
  • overflow-wrap: break-word on table-cell code so only genuinely long values
    (e.g. a Postgres DSN) wrap, while short identifiers like palace_path keep
    natural column sizing and stay on one line.

guide/configuration.md:

  • Drop the redundant Configure with column from the storage-backends table
    (each backend's connection variables are documented in full in its own
    subsection right below), shorten the capability headers, and
    Local (exact cosine)Local (exact). The comparison table is now five
    columns and fits cleanly.

Validation (Playwright, dev server)

Measured scrollWidth/clientWidth and page overflow, plus visual screenshots,
at 1280px and 375px:

  • No element clipping and no page-level horizontal overflow on the
    configuration, remote-server, reference (cli / mcp-tools / python-api),
    claude-code, and knowledge-graph pages.
  • The storage-backends comparison table now fits the content column with no
    scroll at desktop; on mobile it scrolls within its own container.
  • One subsection table (pgvector, long Postgres DSN) scrolls ~36px gracefully —
    reachable, never clipped.
  • bun run docs:build — clean, no dead links.

The custom theme set `.vp-doc table { overflow: hidden }` to clip its
rounded corners, which also overrode VitePress's default `overflow-x: auto`
— so any table wider than the content column was clipped with no way to
scroll to the hidden columns (visible on the storage-backends table). Switch
to `overflow-x: auto` so wide tables scroll, keeping the rounded corners.

Also shorten the storage-backends table's two capability headers
(Namespace isolation -> Namespaces, Lexical search -> Lexical) so the table
fits the content column without needing the scrollbar.
@igorls
igorls requested a review from milla-jovovich as a code owner June 30, 2026 10:51

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request enables horizontal scrolling for wide tables in the documentation by setting display: block and overflow-x: auto on tables, and simplifies table headers in the configuration guide. The feedback suggests updating the custom scrollbar CSS to include height: 6px; so that the horizontal scrollbar matches the customized thin appearance of the vertical scrollbar.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

Comment on lines +168 to +171
display: block;
/* Keep VitePress's horizontal scroll for wide tables; `overflow: hidden`
here would clip columns that don't fit the content column instead. */
overflow-x: auto;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

With overflow-x: auto now enabled to allow horizontal scrolling on wide tables, the horizontal scrollbar will become visible. However, the custom scrollbar styles defined at the bottom of this file (lines 200-207) only specify width: 6px; for ::-webkit-scrollbar.

In WebKit/Blink browsers, width only controls the vertical scrollbar thickness, while height controls the horizontal scrollbar thickness. Without specifying height: 6px;, the horizontal scrollbar on wide tables will render with the browser's default thick height, causing a visual inconsistency with the customized thin vertical scrollbars.

To fix this, please update the scrollbar rule at the bottom of the file as follows:

:::-webkit-scrollbar {
  width: 6px;
  height: 6px;
}

Browser-validated the table layout across desktop (1280) and mobile (375):

- Denser doc-table cell padding (8px 16px -> 8px 12px) so comparison tables
  fit the content column instead of needing a horizontal scrollbar.
- `overflow-wrap: break-word` on table-cell code so only genuinely long
  values (e.g. a Postgres DSN) wrap, while short identifiers like
  `palace_path` keep natural column sizing and stay on one line.
- Drop the redundant 'Configure with' column from the storage-backends table
  (each backend's connection variables are documented in full in its own
  subsection right below) and shorten 'Local (exact cosine)' -> 'Local
  (exact)'. The comparison table is now five columns and fits cleanly.

Verified no clipping and no page-level horizontal overflow on the
configuration, remote-server, reference (cli/mcp-tools/python-api),
claude-code, and knowledge-graph pages; wide tables scroll within their own
container on mobile.
@igorls igorls changed the title fix(docs): stop wide tables from clipping fix(docs): wide-table layout — stop clipping, fit backend table Jun 30, 2026
@igorls
igorls merged commit 0549a90 into develop Jun 30, 2026
13 of 14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant