Improve sidebar navigation, TOC structure, and doc cleanup

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 `<div class="sidebar-section">
       <div id=${section.id}
-        class="sidebar-section-title {% unless ${extractItems(
-          section.items
-        ).map(
-          (item) => (item as EnrichedSectionItem).compareLink
-        )} contains page.url)} %}collapsed-this-isnt-working-its-always-collapsed-ben-took-it-out{% endunless %}"
+        class="sidebar-section-title collapsed"
       >
         ${section.title}
         <img class="chevron-open" src="{{ site.baseurl }}/img/section_open.svg" alt="section open"/>

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 {

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)

src/documentation/experiments/sql_expressions.malloynb

@@ -1,14 +1,16 @@
 >>>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.
 
   `extract(part from date)`
 
 
-In order to make Malloy write an expression like this you can escape to a `sql_<type>` 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_<type>` function.  In the string parameter you can reference dimensions using the substitution operator `${dimension_name}`.
 
 SQL functions are
 

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
-- <a href="https://github.dev/malloydata/try-malloy/airports.malloy" target="_blank">Try the language in your browser now</a> and run live Malloy queries while following the [Quickstart](user_guides/basic.malloynb)
+- <a href="https://github.dev/malloydata/try-malloy/airports.malloy" target="_blank">Try the language in your browser now</a> and run live Malloy queries while following the [Quickstart](user_guides/querying_a_model.malloynb)
 - Write Malloy in the <a href="https://marketplace.visualstudio.com/items?itemName=malloydata.malloy-vscode" target="_blank">Visual Studio Code extension</a>: build semantic data models, query and transform data, and create simple visualizations and dashboards.
 - Explore data with the <a href="https://github.com/malloydata/malloy-composer" target="_blank">Malloy Composer</a>, a demo of a data exploration application built on top of Malloy
 

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
 

src/documentation/language/datatypes.malloynb

@@ -216,14 +216,14 @@ In the future, the literal regular expressions will likely
 be simply slash-enclosed, e.g <code>/.*/</code>.
 
 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
 

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
 

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,15 +58,32 @@ function getCollapsed(id) {
 
 Array.from(document.getElementsByClassName("sidebar-section-title")).forEach(
   (element) => {
+    // Restore session state
     if (!getCollapsed(element.id)) {
       element.classList.remove("collapsed");
     }
     element.addEventListener("click", () => toggleTab(element));
   }
 );
 
+// 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;