Skip to content

docs(ui): readable tables and a clear "On this page" menu at every width; link the Python docs - #511

Merged
lvca merged 5 commits into
ArcadeData:mainfrom
tae898:docs/toc-and-table-layout
Nov 5, 2026
Merged

docs(ui): readable tables and a clear "On this page" menu at every width; link the Python docs#511
lvca merged 5 commits into
ArcadeData:mainfrom
tae898:docs/toc-and-table-layout

Conversation

@tae898

@tae898 tae898 commented Oct 28, 2026

Copy link
Copy Markdown
Contributor

Two layout problems on docs.arcadedb.com, visible at most widths, plus a link update now that the Python docs are on the site (#505).

1. "On this page" menu. aside.toc.sidebar and .toc-menu both drew the left rule, and the links started 1px from it, so the text sat on the line. Now there is one rule, on the menu, with 0.75rem before the links.

2. Tables. To keep long setting names from running under the right sidebar, cells had overflow-wrap: anywhere and inline code word-break: break-all. That lets the browser shrink a column to almost nothing, so on narrow columns words split mid-word ("Pack-age", "arca-dedb", pip install arca-dedb), and on a phone a 4-column table degraded to one letter per line. This PR keeps the sidebar safe without breaking words:

  • the table is as wide as its content needs, up to the content column, and scrolls sideways beyond that (display: block; width: max-content; max-width: 100%; overflow-x: auto, the pattern GitHub uses for markdown tables);
  • cell text wraps at spaces (overflow-wrap: break-word, word-break: normal, hyphens: manual); long inline code may still wrap anywhere;
  • cell padding 12px instead of 12px 16px, which lets a 7- or 8-column table fit a desktop content column;
  • at 768px and below, cells keep a 7.5rem minimum, so a multi-column table scrolls instead of squeezing.

Checked by injecting the rules into the live pages in Chrome and measuring, at widths 360, 390, 768, 984, 1280 and 1920, all 11 pages of the arcadedb-python component plus reference/settings: no page overflows horizontally, and no element of the article reaches under the right sidebar outside a scroll container. On reference/settings at 1280, every table stays inside the content column, and the one whose content is wider scrolls sideways (with break-word alone, without the scroll container, it reached 1146px against a column ending at 1013px). With 12px padding the concurrency page's 7- and 8-column tables fit at 1280 without scrolling. Tables narrower than the column now take their natural width instead of being stretched; on the pages checked, most still fill about 95% of it.

3. how-to/connectivity/python-embedded said the repository holds the full guides; it now links the guides at https://docs.arcadedb.com/arcadedb-python/ and keeps the repository link for the source, examples and issues.

@mergify

mergify Bot commented Oct 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

This pull request does not currently match the merge queue conditions, so it cannot be queued from here. The box comes back if it matches again.

This was referenced Oct 28, 2026
Merged
Merged
@tae898
tae898 force-pushed the docs/toc-and-table-layout branch from 4c2c9a3 to 30f0a62 Compare November 5, 2026 01:57
tae898 and others added 4 commits November 5, 2026 10:58
@tae898 @claude
docs: fix the three broken cross-references and two anchor names that…
b2d7624 
… fail Documentation Validation

- postgres.adoc: <<Column type mapping,...>> pointed at a section title; the
  section gets [[postgres-column-type-mapping]].
- settings.adoc: <<_a_statement_that_fails_halfway>> relied on the generated
  id; the section in transactions.adoc gets [[statement-fails-halfway]].
- sql/chapter.adoc: <<vector-neighbours,...>> -> the anchor is vector-neighbors.
- sql-functions.adoc: [[cchShortestPath]] and [[duanSSSP]] -> cch-shortest-path
  and duan-sssp (lowercase with hyphens), with the three references updated.

docs-validator.py passes locally (it failed on main with these five).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tae898 @claude
docs: write inline code that holds *, _, #, ~ or a <placeholder> as l…
5d388ca 
…iteral monospace

The "Validate HTML output" step (html5validator on the single-page build,
target/generated-docs/index.html) failed with 21 errors, on main as well.
Asciidoctor applies strong, emphasis, mark and subscript before monospace,
so a pair of `*` (or `_`, `#`, `~`) in two different backtick spans pairs up
across them: `wal.group.*` and `commit.lock.*` rendered as
<code>wal.group.<strong></code> and <code>commit.lock.</strong></code>,
which is a stray "code" end tag, and `=~`/`!~` and `#` did the same with
sub and mark. `file://exports/<file-name>` was turned into a bare link with
an illegal href. The same markup renders the live pages wrong (bold running
over the text between two code spans), so the fix is in the sources.

Each affected span is now `+...+` literal monospace, the form sql-projections.adoc
already used. Only spans in the paragraphs that rendered wrongly changed.
Checked by rendering index.adoc with Asciidoctor 3 and scanning for
misnested code/strong/em/mark/sub tags (80 before, 0 after); the real
html5validator run is the CI step.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tae898 @claude
docs: fix what main gained since this PR was opened
457e662 
main moved by about 130 commits; two new things would fail the same two
CI steps again. The anchor [[util-validatePredicate]] (utility.adoc) is
renamed util-validate-predicate, the lowercase-with-hyphens form the
validator requires (nothing refers to it). In redis.adoc, `*1\r\n:1\r\n`
and `'*'` paired as strong across the two code spans, giving a stray
"code" end tag in the single-page build; both are literal monospace now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tae898 @claude
docs(ui): readable tables and an "On this page" menu clear of its rul…
931c4ca 
…e, at every width; link the Python docs

- Right TOC: the aside and the menu both drew the left rule and the links started 1px from it;
  now one rule on the menu and 0.75rem before the links.
- Tables: as wide as the content needs up to the content column, scrolling sideways beyond it
  (display:block, width:max-content, max-width:100%, overflow-x:auto) instead of splitting
  words; no automatic hyphenation; inline code no longer word-break:break-all (still
  overflow-wrap:anywhere for long setting names); 12px cell padding; at <= 768px a minimum
  column width so tables scroll instead of squeezing.
- python-embedded page: link the arcadedb-python component, now published on this site.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tae898
tae898 force-pushed the docs/toc-and-table-layout branch from 30f0a62 to 931c4ca Compare November 5, 2026 01:59
@tae898

tae898 commented Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

Rebased on #515 (both green now; until #515 is merged this diff also shows its three commits, and one rebase on main drops them afterwards).

Measured locally to check the change does what it says: a build of this branch against a build of #515 (that is main plus only the markup fixes), data tables only (table.tableblock; Asciidoctor also renders admonitions as tables, those are left out), each page loaded in a frame of exactly the given width:

page width data tables narrowest cell (main / this PR) cells over 8 lines (main / this PR) tables that scroll sideways (main / this PR) page wider than the screen (main / this PR)
arcadedb-python which-package 390 px 3 56 px / 128 px 39 of 57 / 33 of 57 0 / 3 no / no
arcadedb-python which-package 768 px 3 107 px / 128 px 18 of 57 / 18 of 57 0 / 0 no / no
reference/http-api/http 390 px 16 43 px / 128 px 46 of 270 / 32 of 270 0 / 7 no / no
reference/http-api/http 768 px 16 64 px / 128 px 0 of 270 / 0 of 270 0 / 0 no / no
concepts/timeseries 390 px 11 47 px / 128 px 134 of 294 / 62 of 294 0 / 6 no / no
concepts/timeseries 768 px 11 64 px / 128 px 18 of 294 / 21 of 294 0 / 1 no / no

At phone width the narrowest column goes from about 45 px to 128 px and the wide tables scroll sideways instead of squeezing every column to a few characters; above 768 px nothing changes. The "On this page" menu now has one rule line with room before the links. Ready for review whenever you have a moment; happy to adjust the 7.5rem minimum if you prefer another value.

@tae898 @claude
docs(ui): on a phone the last table column (the prose) gets a 14rem r…
a706e7d 
…eading width

Measured on a local build in frames of exact device widths: at 360 and 393 px the cells over 8 lines drop from 33 to 24 (which-package), 32 to 19 (http) and 62 to 47 (timeseries), and the longest cell from 27 to 15 and 69 to 31 lines; the table scrolls sideways instead (GitHub's pattern). Tablet and wider are unchanged by this rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tae898

tae898 commented Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

One more commit (a706e7d): on a phone the last table column, which usually holds the prose, gets a 14rem reading width, so the table scrolls sideways instead of folding the description into a column a few words wide.

Measured again on local builds of this branch and of main (data tables only, stylesheets loaded fresh in each frame, each page in a frame of the device's CSS width):

page device narrowest cell (main / this PR) cells over 8 lines (main / this PR) longest cell in lines (main / this PR) tables that scroll sideways (main / this PR) page wider than the screen (main / this PR)
arcadedb-python which-package Android small, 360 px 51 px / 128 px 42 of 57 / 24 of 57 41 / 35 0 / 3 no / no
arcadedb-python which-package iPhone, 393 px 57 px / 128 px 39 of 57 / 24 of 57 36 / 35 0 / 3 no / no
arcadedb-python which-package iPad, 820 px 107 px / 107 px 18 of 57 / 12 of 57 15 / 15 0 / 0 no / no
arcadedb-python which-package Z Fold 7 open, 880 px 107 px / 107 px 18 of 57 / 12 of 57 15 / 15 0 / 0 no / no
arcadedb-python which-package Laptop, 1280 px 111 px / 111 px 18 of 57 / 15 of 57 15 / 15 0 / 0 no / no
arcadedb-python which-package Desktop, 1920 px 132 px / 132 px 9 of 57 / 6 of 57 13 / 13 0 / 0 no / no
reference/http-api/http Android small, 360 px 43 px / 128 px 53 of 270 / 19 of 270 21 / 15 0 / 16 no / no
reference/http-api/http iPhone, 393 px 43 px / 128 px 46 of 270 / 19 of 270 21 / 15 0 / 16 no / no
reference/http-api/http iPad, 820 px 64 px / 79 px 0 of 270 / 0 of 270 8 / 8 0 / 0 no / no
reference/http-api/http Z Fold 7 open, 880 px 64 px / 79 px 0 of 270 / 0 of 270 8 / 8 0 / 0 no / no
reference/http-api/http Laptop, 1280 px 67 px / 82 px 0 of 270 / 0 of 270 8 / 8 0 / 0 no / no
reference/http-api/http Desktop, 1920 px 79 px / 82 px 0 of 270 / 0 of 270 8 / 7 0 / 0 no / no
concepts/timeseries Android small, 360 px 47 px / 128 px 146 of 294 / 47 of 294 64 / 31 0 / 11 no / no
concepts/timeseries iPhone, 393 px 47 px / 128 px 128 of 294 / 47 of 294 51 / 31 0 / 11 no / no
concepts/timeseries iPad, 820 px 64 px / 79 px 18 of 294 / 21 of 294 18 / 18 0 / 1 no / no
concepts/timeseries Z Fold 7 open, 880 px 64 px / 79 px 18 of 294 / 21 of 294 18 / 18 0 / 1 no / no
concepts/timeseries Laptop, 1280 px 67 px / 82 px 18 of 294 / 21 of 294 19 / 18 0 / 1 no / no
concepts/timeseries Desktop, 1920 px 79 px / 82 px 18 of 294 / 18 of 294 15 / 15 0 / 0 no / no

Phones gain the most (on the time-series page the cells over 8 lines drop from 146 to 47 at 360 px). One cost to know about: on the time-series page, one table now scrolls sideways from tablet to laptop width and has three more tall cells, because words are no longer broken in the middle. The Z Fold 7 open width (880 px) is an approximation.

This was referenced Nov 5, 2026
Closed
Merged
@lvca

lvca commented Nov 5, 2026

Copy link
Copy Markdown
Member

@claude review this

lvca added a commit that referenced this pull request Nov 5, 2026
@lvca
Merge pull request #520 from tae898/docs/dark-mode-a11y
abf5d30 
docs(ui): dark mode that follows the system setting, a theme toggle, and accessibility fixes (stacked on #511)
@lvca
lvca merged commit a706e7d into ArcadeData:main Nov 5, 2026
4 checks passed
@tae898
tae898 deleted the docs/toc-and-table-layout branch November 5, 2026 04:59
@lvca

lvca commented Nov 5, 2026

Copy link
Copy Markdown
Member

Awesome, thanks

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@tae898 @lvca