Skip to content

Improve sidebar navigation, TOC structure, and doc cleanup#302

Open
jswir wants to merge 2 commits intomalloydata:mainfrom
jswir:docs/sidebar-nav-improvements
Open

Improve sidebar navigation, TOC structure, and doc cleanup#302
jswir wants to merge 2 commits intomalloydata:mainfrom
jswir:docs/sidebar-nav-improvements

Conversation

@jswir
Copy link
Copy Markdown
Contributor

@jswir jswir commented Apr 1, 2026

Summary

  • Sidebar defaults to collapsed — all sections start collapsed, with only the active page's ancestor chain auto-expanded. State persists within a browser session (sessionStorage) and resets on tab close.
  • Restructure Language Reference — group 30+ flat items into subsections: Core Concepts, Data & Types, Expressions & Functions, Aggregation & Analysis, Composition
  • Add 13 missing pages to TOC — pages that were linked from content but missing from sidebar nav (Quickstart, Time Ranges, Timestamp Operations, Timezones, Null Handling, Ungrouped Aggregates, Apply Operator, Filter Expressions, Custom Functions, Evaluation Spaces, SQL Blocks, HyperLogLog, API/JSON Results)
  • Restyle nested sidebar sections — replace heavy gray background boxes with left-border + indent
  • Make active item distinct from hover state (darker background + bold)
  • Fix section ID generationreplace(" ", "_") only replaced first space, breaking sessionStorage persistence
  • Remove empty window.malloynb — feature moved to GA as calculations_windows
  • Fix broken link in experiments.malloynb pointing to deleted window page
  • Add experimental flag callout to sql_expressions docs

Test plan

  • Verify sidebar starts collapsed on fresh session (clear sessionStorage)
  • Verify clicking a page auto-expands its ancestor sections
  • Verify manually expanded sections stay open across page navigations
  • Verify closing tab and reopening resets sidebar to collapsed
  • Verify all new TOC entries render and link correctly
  • Verify /documentation/experiments/sql_expressions renders correctly
  • Verify no build warnings or broken links (npm run build)

jswir added 2 commits April 1, 2026 12:34
- Default sidebar sections to collapsed, auto-expand active page's
  ancestor chain, persist state in sessionStorage (resets on tab close)
- Fix section ID generation to handle multi-word names with special chars
- Group Language Reference into subsections: Core Concepts, Data & Types,
  Expressions & Functions, Aggregation & Analysis, Composition
- Add 13 missing pages to TOC that were linked but not in sidebar nav
- Restyle nested sidebar sections with left border instead of gray boxes
- Make active sidebar item visually distinct from hover state
- Remove empty window.malloynb (moved to GA as calculations_windows)
- Fix broken link in experiments.malloynb to point to calculations_windows
- Add experimental flag callout to sql_expressions docs

Signed-off-by: James Swirhun <james@credibledata.com>
Remove 5 pages from TOC after audit against Malloy codebase:
- basic.malloynb: duplicated by querying_a_model + quickstart_modeling
- apply.malloynb: duplicated by expressions.malloynb Application section
- new_functions.malloynb: historical v0.0.39 changelog, covered in functions.malloynb
- sql_blocks.malloynb: superseded by sql_sources.malloynb
- apijson.malloynb: all code commented out, non-functional

Update inbound links:
- index.malloynb: Quickstart link now points to querying_a_model
- datatypes.malloynb: apply operator links point to expressions
- time-ranges.malloynb: apply operator links point to expressions
- connections.malloynb: remove broken apijson example link

Signed-off-by: James Swirhun <james@credibledata.com>
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