jeff-bruemmer · Sep 18, 2026 · Sep 18, 2026 · Sep 18, 2026 · Sep 18, 2026 · Sep 19, 2026
diff --git a/.stylelintrc b/.stylelintrc
@@ -13,6 +13,12 @@
       }
     ],
     "order/properties-alphabetical-order": true,
+    "value-keyword-case": [
+      "lower",
+      {
+        "ignoreProperties": ["/^--/"]
+      }
+    ],
     "selector-class-pattern": [
       "^([a-z][a-z0-9]*)(-(-*)[a-z0-9]+)*$",
       {
@@ -27,6 +33,12 @@
       }
     ],
     "scss/at-extend-no-missing-placeholder": null,
+    "scss/at-rule-no-unknown": [
+      true,
+      {
+        "ignoreAtRules": ["source", "theme", "custom-variant", "utility", "variant"]
+      }
+    ],
     "scss/at-if-no-null": [
       true,
       {

diff --git a/README.md b/README.md
@@ -61,11 +61,14 @@ retired (GRO-828) and then pruned to what the rendered docs pages actually use
 | ---------------- | ------------------------------------------------------------------------------------------- |
 | `styles.css`     | Minified Bootstrap 5 subset (scoped under `.bootstrap`) plus the header, footer, `.learn` docs layout, breadcrumb, in-page promo and code-copy styles ported from the marketing bundle. |
 | `main.css`       | Legacy global styles: typography, links, lists, tables, `.Button`, the old (pre-v0.44) docs layout, image zoom and the feedback widget. Linted by stylelint. |
-| `docs.css`       | Docs-only overrides for the old docs layout (`.MB-Documentation`, `.container-docs`).       |
-| `docs-local.css` | Styles that only ever lived in this repo (version selector tags, unsupported-version notice). Loaded last so it can override the files above. |
+| `docs.css`       | Docs-only overrides for the old docs layout (`.MB-Documentation`, `.container-docs`) and the unsupported-version notice. |
 | `gdpr.css`       | Metabase theme for the vendored GDPR cookie notice (`public/docs/gdpr-cookie-notice`).      |
 | `inkeep.css`     | Theme for the Inkeep search/chat widget.                                                    |
 
+Themed docs pages don't link these files: `src/styles/docs.css` imports
+`docs.css`, `styles.css`, `main.css` and `gdpr.css` into its `legacy` cascade
+layer. A prune must keep the rules those pages use too.
+
 Sections that remain large on purpose:
 
 - The Bootstrap reboot, grid (`.row`, `.col-*` used by the header) and spacing,

diff --git a/_includes/beta-blockquote.html b/_includes/beta-blockquote.html
@@ -1,5 +1,9 @@
+{%- comment -%}
+  The `.md` version of a doc renders markdown/beta-blockquote.html instead.
+  Keep the wording in sync.
+{%- endcomment -%}
 <div>
-  <blockquote>
+  <blockquote class="beta-blockquote">
     ⚠️ This feature is in beta. Feel free to play around with it, but be aware that things might change (and may not work
     as expected).
     {% if include.message %}

diff --git a/_includes/chrome/stylesheets.html b/_includes/chrome/stylesheets.html
@@ -1,14 +1,30 @@
+{% comment %}
+Themed docs pages use only Lato 400/700 and Roboto Mono; src/styles/docs.css
+drops the Lato 900 uses in styles.css. Other pages keep the marketing set.
+{% endcomment %}
+{% if include.docs_theme %}
+<link href="https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,400;0,700;1,400;1,700&family=Roboto+Mono&display=swap" rel="stylesheet" />
+{% else %}
 <link href="https://fonts.googleapis.com/css2?family=Merriweather:ital,wght@0,400;0,700;0,900&display=swap" rel="stylesheet" />
 <link href="https://fonts.googleapis.com/css2?family=Fira+Code&display=swap" rel="stylesheet" />
 <link href="https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,400;0,700;0,900;1,400;1,700&family=Roboto+Mono&display=swap" rel="stylesheet" />
+{% endif %}
+{% comment %}
+Themed docs pages get these five through src/styles/docs.css (Tailwind), which
+puts them in a cascade layer below the utilities.
+{% endcomment %}
+{% unless include.docs_theme %}
 <link href="/docs/gdpr-cookie-notice/dist/style.css" rel="stylesheet" />
 {% unless page.layout == "docs-api" %}
 <link href="/docs/css/docs.css" rel="stylesheet" />
 <link href="/docs/css/styles.css" rel="stylesheet" />
 <link href="/docs/css/main.css" rel="stylesheet" />
 {% endunless %}
 <link href="/docs/css/gdpr.css" rel="stylesheet" />
+{% endunless %}
 <link href="https://vjs.zencdn.net/7.20.3/video-js.css" rel="stylesheet" />
 <link href="https://cdnjs.cloudflare.com/ajax/libs/flexboxgrid/6.3.1/flexboxgrid.min.css" rel="stylesheet" type="text/css" />
-<link href="https://vjs.zencdn.net/7.20.3/video-js.css" rel="stylesheet" />
+{% comment %}Themed docs pages get their syntax colors from src/styles/docs.css.{% endcomment %}
+{% unless include.docs_theme %}
 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/styles/base16/atelier-sulphurpool-light.min.css" integrity="sha512-qrwjMzcPG1EHhhg9z2nH7VW7hj525RVx0o7GlxQc4ZhWkghp9slpnTjOUu5thnPaRfRqfAUlX7anvAqD9EonfQ==" crossorigin="anonymous" referrerpolicy="no-referrer" />
+{% endunless %}
diff --git a/_includes/docs-metadata.html b/_includes/docs-metadata.html
@@ -1,12 +1,28 @@
-{% assign title = page.title | append: " | Metabase Documentation"%}
+{% comment %}
+Versioned pages name their version, so tabs and search results for different
+versions of a page can be told apart.
+{% endcomment %}
+{% if page.latest != true and page.version %}
+{% assign version_label = page.version | remove_first: "v0." %}
+{% assign title = page.title | append: " | Metabase " | append: version_label | append: " Documentation" %}
+{% else %}
+{% assign title = page.title | append: " | Metabase Documentation" %}
+{% endif %}
+{% assign title = title | escape_once %}
 
-{% if page.description %}
-{% assign desc = page.description %}
+{% comment %}
+meta_description is plain text from the doc page routes
+(src/lib/docs/docPages.ts): the description or summary, else the body's
+opening words.
+{% endcomment %}
+{% if page.meta_description %}
+{% assign desc = page.meta_description %}
+{% elsif page.description %}
+{% assign desc = page.description | strip_html %}
 {% elsif page.summary %}
-{% assign desc = page.summary %}
-{% else %}
-{% assign desc = page.content | strip_html | truncatewords: 25 | escape_once %}
+{% assign desc = page.summary | strip_html %}
 {% endif %}
+{% assign desc = desc | escape_once %}
 
 {% assign img = "https://cdn.metabase.com/images/docs/docs-og.png" %}
 

diff --git a/_includes/docs/theme-init.js b/_includes/docs/theme-init.js
@@ -0,0 +1,45 @@
+// Inlined into <head> by head.html before any stylesheet loads, so the theme
+// attribute is present at first paint (no flash of the wrong theme).
+// data-theme-preference holds the visitor's choice from the theme options in
+// DocsMoreMenu.astro: system (the default, nothing stored), light or dark.
+// data-theme holds the theme in use; on system it follows the system theme,
+// live. Rendered through Liquid, so keep it free of Liquid tag syntax.
+(() => {
+  const KEY = "mb-docs-theme";
+  const root = document.documentElement;
+  const systemDark = matchMedia("(prefers-color-scheme: dark)");
+
+  const stored = () => {
+    try {
+      const theme = localStorage.getItem(KEY);
+      return theme === "light" || theme === "dark" ? theme : null;
+    } catch {
+      return null; /* storage blocked (private mode, disabled cookies) */
+    }
+  };
+  const apply = () => {
+    const preference = root.dataset.themePreference;
+    root.dataset.theme =
+      preference === "light" || preference === "dark"
+        ? preference
+        : systemDark.matches
+          ? "dark"
+          : "light";
+  };
+
+  // For the theme options in DocsMoreMenu.astro.
+  window.setDocsTheme = (preference) => {
+    root.dataset.themePreference = preference;
+    apply();
+    try {
+      if (preference === "system") localStorage.removeItem(KEY);
+      else localStorage.setItem(KEY, preference);
+    } catch {
+      /* storage blocked; the choice lasts for this page only */
+    }
+  };
+
+  root.dataset.themePreference = stored() ?? "system";
+  apply();
+  systemDark.addEventListener("change", apply);
+})();
diff --git a/_includes/head.html b/_includes/head.html
@@ -1,7 +1,7 @@
 <head>
   <meta charset="utf-8" />
   <meta content="IE=edge" http-equiv="X-UA-Compatible" />
-  <meta content="width=device-width, initial-scale=1, maximum-scale=1" name="viewport" />
+  <meta content="width=device-width, initial-scale=1" name="viewport" />
 
   <meta content="frame-ancestors 'none'" http-equiv="Content-Security-Policy" />
   <meta content="deny" http-equiv="X-Frame-Options" />
@@ -32,6 +32,9 @@
   {% include docs-metadata.html %}
 
   {% include schema-markup.html %}
+  {% if include.json_ld %}
+  <script type="application/ld+json">{{ include.json_ld }}</script>
+  {% endif %}
 
   {% if jekyll.environment == "development" %}
   <link href="/docs/images/favicon-dev.svg" rel="shortcut icon" />
@@ -43,13 +46,12 @@
   <link rel="apple-touch-icon" href="/docs/images/apple-touch-icon.png" />
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-  {% include chrome/stylesheets.html %}
-
-  {% comment %}
-  Loaded after the local chrome so it can override those stylesheets. Must stay
-  outside the canonical-URL block above, which skips versioned docs pages.
-  {% endcomment %}
-  <link rel="stylesheet" href="/docs/css/docs-local.css" />
+  {% if include.docs_theme %}
+  <script>
+    {% include docs/theme-init.js %}
+  </script>
+  {% endif %}
+  {% include chrome/stylesheets.html docs_theme=include.docs_theme %}
 
   {% if page.url contains "/data-stack-report-2023/" %}
   <!-- Cooper Font -->

diff --git a/_includes/markdown/beta-blockquote.html b/_includes/markdown/beta-blockquote.html
@@ -0,0 +1,8 @@
+{%- comment -%}
+  Markdown stand-in for ../beta-blockquote.html.
+{%- endcomment -%}
+> ⚠️ This feature is in beta. Feel free to play around with it, but be aware that things might change (and may not work as expected).
+{%- if include.message %}
+>
+> {{ include.message }}
+{%- endif -%}
diff --git a/_includes/markdown/plans-blockquote.html b/_includes/markdown/plans-blockquote.html
@@ -0,0 +1,22 @@
+{%- comment -%}
+  Markdown stand-in for ../plans-blockquote.html, used by the `.md` version of
+  a doc (see MARKDOWN_INCLUDES_ROOT in src/lib/liquid/liquidRenderer.ts).
+{%- endcomment -%}
+{%- if include.convert_pro_link_to_embedding -%}
+  {%- assign pro_link = "https://store.metabase.com/checkout/embedding" -%}
+{%- else -%}
+  {%- assign pro_link = "/product/pro" -%}
+{%- endif -%}
+{%- assign feature_text = include.feature | default: "This feature" -%}
+{%- assign verb = "is" -%}
+{%- if include.is_plural -%}
+  {%- assign verb = "are" -%}
+{%- endif -%}
+> {{ feature_text }} {{ verb }} only available on
+{%- if include.enterprise-only %} [Enterprise](/product/enterprise) plans
+{%- else %} [Pro]({{ pro_link }}) and [Enterprise](/product/enterprise) plans
+{%- endif -%}
+{%- if include.self-hosted-only %} (only on self-hosted plans)
+{%- else %} (both self-hosted and on Metabase Cloud)
+{%- endif -%}
+.
diff --git a/_includes/markdown/shared/in-page-promo-embedding-workshop.html b/_includes/markdown/shared/in-page-promo-embedding-workshop.html
@@ -0,0 +1,3 @@
+{%- comment -%}
+  Promo banners are left out of the Markdown version of a doc.
+{%- endcomment -%}
diff --git a/_includes/markdown/shared/in-page-promo.html b/_includes/markdown/shared/in-page-promo.html
@@ -0,0 +1,3 @@
+{%- comment -%}
+  Promo banners are left out of the Markdown version of a doc.
+{%- endcomment -%}
diff --git a/_includes/markdown/svg-icons/cross.svg b/_includes/markdown/svg-icons/cross.svg
diff --git a/_includes/markdown/youtube.html b/_includes/markdown/youtube.html
@@ -0,0 +1,5 @@
+{%- comment -%}
+  Markdown stand-in for ../youtube.html: a link, since an iframe means nothing
+  outside a browser.
+{%- endcomment -%}
+[Watch the video on YouTube](https://www.youtube.com/watch?v={{ include.id }})
diff --git a/_includes/plans-blockquote.html b/_includes/plans-blockquote.html
@@ -1,3 +1,7 @@
+{%- comment -%}
+  The `.md` version of a doc renders markdown/plans-blockquote.html instead.
+  Keep the wording in sync.
+{%- endcomment -%}
 {% if include.convert_pro_link_to_embedding %}
   {% assign pro_link = "https://store.metabase.com/checkout/embedding" %}
 {% else %}

diff --git a/_includes/youtube.html b/_includes/youtube.html
@@ -1,3 +1,6 @@
+{%- comment -%}
+  The `.md` version of a doc renders markdown/youtube.html instead.
+{%- endcomment -%}
 {% if include.width != '' %}
 <div style='width: {{include.width}}; margin-bottom: 2em;'>
     {% else %}

diff --git a/amplify.yml b/amplify.yml
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -1,5 +1,6 @@
 // @ts-check
 import path from "node:path";
+import tailwindcss from "@tailwindcss/vite";
 import { defineConfig } from "astro/config";
 import { viteStaticCopy } from "vite-plugin-static-copy";
 import { DOCS_DEST, DOCS_SRC_ROOT } from "./src/constants";
@@ -35,6 +36,9 @@ export default defineConfig({
   },
   vite: {
     plugins: [
+      // Themed docs pages (src/styles/docs.css). Legacy `layout: docs` pages
+      // keep linking the vendored stylesheets from _includes/chrome/stylesheets.html.
+      tailwindcss(),
       viteStaticCopy({
         targets: [
           {