From 9aa485280a6c77e10266605668572c0e911a8ebc Mon Sep 17 00:00:00 2001 From: James Swirhun Date: Wed, 1 Apr 2026 12:32:14 -0600 Subject: [PATCH 1/2] Improve sidebar navigation and fix doc cleanup issues - 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 --- scripts/page.ts | 8 +- src/css/document.css | 24 +- .../experiments/experiments.malloynb | 2 +- .../experiments/sql_expressions.malloynb | 4 +- src/documentation/experiments/window.malloynb | 2 - src/js/sidebar_state.js | 25 +- src/table_of_contents.json | 217 ++++++++++++------ 7 files changed, 185 insertions(+), 97 deletions(-) delete mode 100644 src/documentation/experiments/window.malloynb diff --git a/scripts/page.ts b/scripts/page.ts index 4e29ee8a..8f5a1a61 100644 --- a/scripts/page.ts +++ b/scripts/page.ts @@ -56,7 +56,7 @@ function isSectionItem(item: SectionItem | Section): item is SectionItem { function enrichTableOfContents(sections: Section[]): EnrichedSection[] { return sections.map((section) => { return { - id: section.title.toLowerCase().replace(" ", "_"), + id: section.title.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/(^_|_$)/g, ""), title: section.title, items: section.items.map((item) => { if (isSectionItem(item)) { @@ -101,11 +101,7 @@ function renderSection(section: EnrichedSection | EnrichedSectionItem): string { } else { return `
${section.title} section open diff --git a/src/css/document.css b/src/css/document.css index 333bcb6f..ca3c8c08 100644 --- a/src/css/document.css +++ b/src/css/document.css @@ -114,27 +114,28 @@ div.sidebar { /* Top-level section groups */ .sidebar-section { - margin-bottom: 12px; + margin-bottom: 4px; padding: 8px; background-color: #fafafa; border-radius: 8px; } -/* Nested sections - darker background */ +/* Nested sections - indented, no extra background */ .sidebar-section .sidebar-section { - margin-left: -4px; - margin-right: -4px; - margin-top: 8px; - margin-bottom: 8px; - padding: 8px; - background-color: #f0f0f0; - border-radius: 6px; + margin-left: 0; + margin-right: 0; + margin-top: 4px; + margin-bottom: 4px; + padding: 0 0 0 8px; + background-color: transparent; + border-left: 2px solid #e0e0e0; + border-radius: 0; } .sidebar-section .sidebar-section .sidebar-section-title { font-size: 11px; font-weight: 600; - color: #888; + color: #999; text-transform: uppercase; letter-spacing: 0.5px; } @@ -169,7 +170,8 @@ div.sidebar div.sidebar-item a:hover { } div.sidebar div.sidebar-item.active a { - background-color: #85b0f730; + background-color: #85b0f760; + font-weight: 600; } div.sidebar-section-title { diff --git a/src/documentation/experiments/experiments.malloynb b/src/documentation/experiments/experiments.malloynb index b5af33fe..660e10a6 100644 --- a/src/documentation/experiments/experiments.malloynb +++ b/src/documentation/experiments/experiments.malloynb @@ -8,7 +8,7 @@ We value feedback during the experimental phase. Please make sure you let us kn Below is a list of currently running experiments and how to turn them on. * `##! experimental.join_types` - [Additional Join Type](joins.malloynb) -* `##! experimental { function_order_by partition_by aggregate_limit }` - [ordering and partitioning in calculations](window.malloynb) +* `##! experimental { function_order_by partition_by aggregate_limit }` - [ordering and partitioning in calculations](../language/calculations_windows.malloynb) * `##! experimental.sql_functions` - [Write expression in SQL](sql_expressions.malloynb) * `##! experimental.parameters` - [Declare sources with parameters](parameters.malloynb) * `##! experimental.composite_sources` - [Create composite sources backed by multiple cube tables or source definitions](composite_sources.malloynb) diff --git a/src/documentation/experiments/sql_expressions.malloynb b/src/documentation/experiments/sql_expressions.malloynb index c0a997b2..98b555be 100644 --- a/src/documentation/experiments/sql_expressions.malloynb +++ b/src/documentation/experiments/sql_expressions.malloynb @@ -1,6 +1,8 @@ >>>markdown ## SQL Expressions +_This feature requires the experimental flag `##! experimental{sql_functions}` at the top of your model._ + Malloy allows you to call native database functions using `!type`. For example if you wanted to call the duckdb function bit_length that returns a number, in Malloy you couild write `bitlength!number("this string)`. Sometimes the SQL expression you want to write can't be expressed this way. For example in DUCKDB, the extract function looks like. @@ -8,7 +10,7 @@ Sometimes the SQL expression you want to write can't be expressed this way. For `extract(part from date)` -In order to make Malloy write an expression like this you can escape to a `sql_` function. In the string parameter you can reference dimensions using the substitution operator `${dimension_name}`. +In order to make Malloy write an expression like this you can escape to a `sql_` function. In the string parameter you can reference dimensions using the substitution operator `${dimension_name}`. SQL functions are diff --git a/src/documentation/experiments/window.malloynb b/src/documentation/experiments/window.malloynb deleted file mode 100644 index 2359eea4..00000000 --- a/src/documentation/experiments/window.malloynb +++ /dev/null @@ -1,2 +0,0 @@ ->>>markdown -## Calculation Partitioning \ No newline at end of file diff --git a/src/js/sidebar_state.js b/src/js/sidebar_state.js index 2df09983..772d0817 100644 --- a/src/js/sidebar_state.js +++ b/src/js/sidebar_state.js @@ -34,14 +34,14 @@ function toggleTab(tabElement) { function getCollapseState() { try { - return JSON.parse(localStorage.getItem("collapse_state")) || {}; + return JSON.parse(sessionStorage.getItem("collapse_state")) || {}; } catch (_error) { return {}; } } function setCollapseState(collapseState) { - localStorage.setItem("collapse_state", JSON.stringify(collapseState)); + sessionStorage.setItem("collapse_state", JSON.stringify(collapseState)); } function setCollapsed(id, isCollapsed) { @@ -58,6 +58,7 @@ function getCollapsed(id) { Array.from(document.getElementsByClassName("sidebar-section-title")).forEach( (element) => { + // Restore session state if (!getCollapsed(element.id)) { element.classList.remove("collapsed"); } @@ -65,8 +66,24 @@ Array.from(document.getElementsByClassName("sidebar-section-title")).forEach( } ); +// Expand all ancestor sections of the active page (after restoring session state) +var activeItem = document.querySelector(".sidebar-item.active"); +if (activeItem) { + var parent = activeItem.parentElement; + while (parent) { + if (parent.classList && parent.classList.contains("sidebar-section")) { + var title = parent.querySelector(":scope > .sidebar-section-title"); + if (title && title.classList.contains("collapsed")) { + title.classList.remove("collapsed"); + setCollapsed(title.id, false); + } + } + parent = parent.parentElement; + } +} + const sidebarElement = document.getElementById("sidebar"); sidebarElement.addEventListener("scroll", () => { - localStorage.setItem("sidebar_scroll_position", sidebarElement.scrollTop); + sessionStorage.setItem("sidebar_scroll_position", sidebarElement.scrollTop); }); -sidebarElement.scrollTop = localStorage.getItem("sidebar_scroll_position") || 0; +sidebarElement.scrollTop = sessionStorage.getItem("sidebar_scroll_position") || 0; diff --git a/src/table_of_contents.json b/src/table_of_contents.json index 95e5775d..971e0020 100644 --- a/src/table_of_contents.json +++ b/src/table_of_contents.json @@ -44,6 +44,10 @@ { "title": "Getting Started", "items": [ + { + "title": "Quickstart", + "link": "/user_guides/basic.malloynb" + }, { "title": "Querying a Semantic Model", "link": "/user_guides/querying_a_model.malloynb" @@ -132,84 +136,149 @@ "title": "Language Reference", "items": [ { - "title": "Models", - "link": "/language/statement.malloynb" - }, - { - "title": "Sources", - "link": "/language/source.malloynb" - }, - { - "title": "Queries", - "link": "/language/query.malloynb" - }, - { - "title": "Views", - "link": "/language/views.malloynb" - }, - { - "title": "Data Types", - "link": "/language/datatypes.malloynb" - }, - { - "title": "Fields", - "link": "/language/fields.malloynb" - }, - { - "title": "Aggregates", - "link": "/language/aggregates.malloynb" - }, - { - "title": "Expressions", - "link": "/language/expressions.malloynb" - }, - { - "title": "Functions", - "link": "/language/functions.malloynb" - }, - { - "title": "Filters", - "link": "/language/filters.malloynb" - }, - { - "title": "Calculations (window functions)", - "link": "/language/calculations_windows.malloynb" - }, - { - "title": "Ordering and Limiting", - "link": "/language/order_by.malloynb" - }, - { - "title": "Joins", - "link": "/language/join.malloynb" - }, - { - "title": "Nested Views", - "link": "/language/nesting.malloynb" - }, - { - "title": "SQL Sources", - "link": "/language/sql_sources.malloynb" + "title": "Quick Reference", + "link": "/language/quick_reference.html" }, { - "title": "Imports", - "link": "/language/imports.malloynb" + "title": "Core Concepts", + "items": [ + { + "title": "Models", + "link": "/language/statement.malloynb" + }, + { + "title": "Sources", + "link": "/language/source.malloynb" + }, + { + "title": "Queries", + "link": "/language/query.malloynb" + }, + { + "title": "Views", + "link": "/language/views.malloynb" + }, + { + "title": "Fields", + "link": "/language/fields.malloynb" + } + ] }, { - "title": "Connections", - "link": "/language/connections.malloynb" + "title": "Data & Types", + "items": [ + { + "title": "Data Types", + "link": "/language/datatypes.malloynb" + }, + { + "title": "Time Ranges", + "link": "/language/time-ranges.malloynb" + }, + { + "title": "Timestamp Operations", + "link": "/language/timestamp-operations.malloynb" + }, + { + "title": "Timezones", + "link": "/language/timezones.malloynb" + }, + { + "title": "Null Handling", + "link": "/language/null-handling.malloynb" + } + ] }, { - "title": "Tags", - "link": "/language/tags.malloynb" + "title": "Expressions & Functions", + "items": [ + { + "title": "Expressions", + "link": "/language/expressions.malloynb" + }, + { + "title": "Apply Operator", + "link": "/language/apply.malloynb" + }, + { + "title": "Functions", + "link": "/language/functions.malloynb" + }, + { + "title": "Custom Functions", + "link": "/language/new_functions.malloynb" + }, + { + "title": "Filters", + "link": "/language/filters.malloynb" + }, + { + "title": "Filter Expressions", + "link": "/language/filter-expressions.malloynb" + } + ] }, { - "title": "Quick Reference", - "link": "/language/quick_reference.html" + "title": "Aggregation & Analysis", + "items": [ + { + "title": "Aggregates", + "link": "/language/aggregates.malloynb" + }, + { + "title": "Ungrouped Aggregates", + "link": "/language/ungrouped-aggregates.malloynb" + }, + { + "title": "Calculations (window functions)", + "link": "/language/calculations_windows.malloynb" + }, + { + "title": "Evaluation Spaces", + "link": "/language/eval_space.malloynb" + }, + { + "title": "Ordering and Limiting", + "link": "/language/order_by.malloynb" + } + ] }, { - "title": "Change Log", - "link": "/language/changelog.malloynb" + "title": "Composition", + "items": [ + { + "title": "Joins", + "link": "/language/join.malloynb" + }, + { + "title": "Nested Views", + "link": "/language/nesting.malloynb" + }, + { + "title": "SQL Sources", + "link": "/language/sql_sources.malloynb" + }, + { + "title": "SQL Blocks", + "link": "/language/sql_blocks.malloynb" + }, + { + "title": "Imports", + "link": "/language/imports.malloynb" + }, + { + "title": "Connections", + "link": "/language/connections.malloynb" + }, + { + "title": "Tags", + "link": "/language/tags.malloynb" + }, + { + "title": "HyperLogLog", + "link": "/language/hyperloglog.malloynb" + } + ] }, { "title": "Dialects", @@ -241,6 +310,10 @@ "link": "/language/dialect/mssql-via-duckdb.malloynb" } ] + }, + { + "title": "Change Log", + "link": "/language/changelog.malloynb" } ] }, @@ -294,6 +367,10 @@ { "title": "Dimensional Indexes", "link": "/patterns/dim_index.malloynb" + }, + { + "title": "API / JSON Results", + "link": "/patterns/apijson.malloynb" } ] }, @@ -408,10 +485,6 @@ "title": "SQL Expressions", "link": "/experiments/sql_expressions.malloynb" }, - { - "title": "Window Partitions", - "link": "/experiments/window.malloynb" - }, { "title": "Parameters", "link": "/experiments/parameters.malloynb" From 0eb8a9d9b91f1cef334454043048409d5fad8714 Mon Sep 17 00:00:00 2001 From: James Swirhun Date: Wed, 1 Apr 2026 16:11:15 -0600 Subject: [PATCH 2/2] Remove stale/duplicate pages from TOC, update inbound links 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 --- src/documentation/index.malloynb | 2 +- .../language/connections.malloynb | 2 +- src/documentation/language/datatypes.malloynb | 6 +++--- .../language/time-ranges.malloynb | 4 ++-- src/table_of_contents.json | 20 ------------------- 5 files changed, 7 insertions(+), 27 deletions(-) diff --git a/src/documentation/index.malloynb b/src/documentation/index.malloynb index 09eda088..c05a0abe 100644 --- a/src/documentation/index.malloynb +++ b/src/documentation/index.malloynb @@ -10,7 +10,7 @@ Malloy is a modern open source language for describing data relationships and tr Malloy is a work in progress. Malloy is designed to be a language for anyone who works with SQL--whether you’re an analyst, data scientist, data engineer, or someone building a data application. If you know SQL, Malloy will feel familiar, while more powerful and efficient. Malloy allows you to model as you go, so there is no heavy up-front work before you can start answering complex questions, and you're never held back or restricted by the model. ## Try Malloy Today -- Try the language in your browser now and run live Malloy queries while following the [Quickstart](user_guides/basic.malloynb) +- Try the language in your browser now and run live Malloy queries while following the [Quickstart](user_guides/querying_a_model.malloynb) - Write Malloy in the Visual Studio Code extension: build semantic data models, query and transform data, and create simple visualizations and dashboards. - Explore data with the Malloy Composer, a demo of a data exploration application built on top of Malloy diff --git a/src/documentation/language/connections.malloynb b/src/documentation/language/connections.malloynb index f494475f..40174be9 100644 --- a/src/documentation/language/connections.malloynb +++ b/src/documentation/language/connections.malloynb @@ -31,7 +31,7 @@ In Databricks, the string passed to the `.table()` connection method can be a on ### DuckDB -In DuckDB, the `.table()` method accepts the path (relative to the Malloy file) of a CSV, JSON, or Parquet file containing the table data, e.g. `duckdb.table('data/users.csv')` or `duckdb.table('../../users.parquet')`. URLs to such files (or APIs) are also allowed: see [an example here](../patterns/apijson.malloynb). +In DuckDB, the `.table()` method accepts the path (relative to the Malloy file) of a CSV, JSON, or Parquet file containing the table data, e.g. `duckdb.table('data/users.csv')` or `duckdb.table('../../users.parquet')`. URLs to such files (or APIs) are also allowed. ### Postgres diff --git a/src/documentation/language/datatypes.malloynb b/src/documentation/language/datatypes.malloynb index 993cfa17..77f4e9d3 100644 --- a/src/documentation/language/datatypes.malloynb +++ b/src/documentation/language/datatypes.malloynb @@ -216,14 +216,14 @@ In the future, the literal regular expressions will likely be simply slash-enclosed, e.g /.*/. Values of type `string` may be compared against regular -expressions using either the [apply operator](apply.malloynb), `name ? r'c.*'` or the like operator, `name ~ r'c.*'`. +expressions using either the [apply operator](expressions.malloynb), `name ? r'c.*'` or the like operator, `name ~ r'c.*'`. ### Ranges There are three types of ranges today: `number` ranges, `date` ranges, and `timestamp` ranges. The most basic ranges are of the form `start to end` and represent the range from `start` up to, but not including, `end`, e.g. `10 to 20` or `@2004-01 to @2005-05`. -Ranges may be used in conjunction with the [apply operator](apply.malloynb) to test whether a value falls within a given range. +Ranges may be used in conjunction with the [apply operator](expressions.malloynb) to test whether a value falls within a given range. ### Alternations and Partials @@ -249,7 +249,7 @@ inclusion respectively. For example, `'CA' | r'N.*'` represents the condition of being equal to 'CA' or starting with 'N', and `10 to 20 | 20 to 30` represents the condition of being _either_ between 10 and 20 _or_ 20 and 30. -Alternations and partials may be used in conjunction with the [apply operator](apply.malloynb) to test whether a value meets the given condition. +Alternations and partials may be used in conjunction with the [apply operator](expressions.malloynb) to test whether a value meets the given condition. ## Nullability diff --git a/src/documentation/language/time-ranges.malloynb b/src/documentation/language/time-ranges.malloynb index b023c08f..d474bbff 100644 --- a/src/documentation/language/time-ranges.malloynb +++ b/src/documentation/language/time-ranges.malloynb @@ -10,7 +10,7 @@ There are two forms of range expressions A timestamp can be compared to a range. If the time stamp is within the range it will be `=`. Before the range it will be `<` and after -the range it will be `>`. If you [apply](apply.malloynb) a range, (for example, `eventDate: @2003 to @2004`) that will also check if the value is within the range. +the range it will be `>`. If you [apply](expressions.malloynb) a range, (for example, `eventDate: @2003 to @2004`) that will also check if the value is within the range. ## Range shortcuts @@ -38,7 +38,7 @@ at the moment of truncation and the duration is the timeframe unit used to specify the truncation, so for example `eventDate.year` would be a range covering the entire year which contains `eventDate` -This is extremely useful with the [Apply operator](apply.malloynb), `?`. To see if two events happen in the same calendar year, for example, the boolean expression in Malloy could be `oneEvent ? otherEvent.year` +This is extremely useful with the [Apply operator](expressions.malloynb), `?`. To see if two events happen in the same calendar year, for example, the boolean expression in Malloy could be `oneEvent ? otherEvent.year` ## Interval Measurement diff --git a/src/table_of_contents.json b/src/table_of_contents.json index 971e0020..7772cf6b 100644 --- a/src/table_of_contents.json +++ b/src/table_of_contents.json @@ -44,10 +44,6 @@ { "title": "Getting Started", "items": [ - { - "title": "Quickstart", - "link": "/user_guides/basic.malloynb" - }, { "title": "Querying a Semantic Model", "link": "/user_guides/querying_a_model.malloynb" @@ -196,18 +192,10 @@ "title": "Expressions", "link": "/language/expressions.malloynb" }, - { - "title": "Apply Operator", - "link": "/language/apply.malloynb" - }, { "title": "Functions", "link": "/language/functions.malloynb" }, - { - "title": "Custom Functions", - "link": "/language/new_functions.malloynb" - }, { "title": "Filters", "link": "/language/filters.malloynb" @@ -258,10 +246,6 @@ "title": "SQL Sources", "link": "/language/sql_sources.malloynb" }, - { - "title": "SQL Blocks", - "link": "/language/sql_blocks.malloynb" - }, { "title": "Imports", "link": "/language/imports.malloynb" @@ -367,10 +351,6 @@ { "title": "Dimensional Indexes", "link": "/patterns/dim_index.malloynb" - }, - { - "title": "API / JSON Results", - "link": "/patterns/apijson.malloynb" } ] },