datalog-theme 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdef033c462e7ded26169effe9d852f91cb9f8273736229255e331e9d3ec9482
-  data.tar.gz: cff04ea4051161711a57a1e4d2b088c799cf85cf0dfa546324ce0d67ce907e05
+  metadata.gz: 044a1ef441ccbf54db7acf3d354bb2c4c1285213894cb0271ec868fd1a1106ba
+  data.tar.gz: 76b0d5c472a965169b2dd773209c62d4b3628e93baec673175fdc0e301b43709
 SHA512:
-  metadata.gz: 2cbc7032d5fb6d0fa2f6e011865c942d6af2e695bf6c7cad798b4d7059a06ea51ff2e8c4fc6558a17ca69fa1a3cc524b31248857476e37b238c0e33cda5a6ff7
-  data.tar.gz: c72a7aa992fca99b8ec2c46839a20c8e74877ff785c0238ec00c2910e186362b37541dadf02e1c479c9a9ba7acdbe7fd085bbeb05d3c3435b9486e2237cd090f
+  metadata.gz: 13394db55c58db0f89ddbe3ebf165823558b5a089a8036dde9c1a0056f73851631306db760e953b868263e4e74e81554601217960f6753be918b50834f010ebc
+  data.tar.gz: f972bb963121de7210fff3b1ea607a32bdbb128cfcf211510cfd02da296c79b4ea65e0e2201da2d966e2e8502e2b3662b015f90d2ae9a9d08ab7d7b8f5c2db3e

data/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-09-12
+
+### Added
+
+- `tests/test_search_pages.rb` covers the generator: both pages when search is on, neither when it is off or unconfigured, and no duplicate when the site provides its own.
+- The README carries a badge showing the version published on RubyGems, linking to the gem page.
+- `scripts/verify_gem_package.rb` checks that a built gem contains every bundle its manifest references; the release workflow builds the bundles and runs it before publishing.
+- `tests/test_gem_package.rb` covers what a site using the gem needs: the bundles are packaged, the plugins' gem dependencies are declared, and requiring the theme registers its Liquid tags.
+- The search index test checks that tags are whole tags rather than only that the field is an array.
+- The integration suite runs axe-core over six pages in both light and dark mode, so contrast, missing accessible names and misplaced ARIA cannot regress unnoticed.
+- A social card image (`assets/img/social-card.png`), so the Open Graph and Twitter image tags no longer point at a missing file.
+- The release workflow now does a release in one run plus one pull request: "Run workflow" with a version bumps `develop` and opens the PR into `main`; merging it tags `main`, publishes the GitHub release and starts the gem publish.
+
+### Changed
+
+- MathJax is only loaded on pages that contain math (`theme_options.math.render_on_load: auto`, the new default of the demo site) and Prism only on pages with a code block (`theme_options.syntax_highlighting.load: auto`); pages can still opt in or out with `math:` and `syntax_highlighting:` front matter, and a page with `math: false` is also left alone by the math preprocessor. Pages without either skip about 400 KB of CDN scripts and stylesheets.
+- The IBM Plex web fonts fall back to local fonts scaled to Plex's metrics, so the swap once the web font arrives no longer moves the layout, and the Google Fonts stylesheet no longer blocks rendering.
+- The home hero image is preloaded and small screens get a 640 px variant (`hero_image_small` for pages that set their own `hero_image`).
+- The Lighthouse workflow inlines critical CSS before building, as the deploy does, so it measures the published configuration.
+- CI jobs install only what they use: the Jekyll test job no longer installs libvips (the image plugin uses MiniMagick, which the runners already provide) or keeps redundant pip and `_site` caches, and the accessibility, Lighthouse and deploy workflows no longer set up Python, which only the Rake verification task needs.
+- The hero background is served as a 46 KB WebP instead of a 1.27 MB PNG.
+- Footer text and links, and the skip link in dark mode, meet the 4.5:1 contrast ratio; the blog listing uses second-level headings for its cards.
+- The Tests workflow runs for pull requests into `main` as well as `develop`; the duplicate theme-stability workflow is gone.
+- The configuration guide documents where settings actually live (`_config.yml` plus `_data/config/author.yml`).
+- The gem publish can authenticate with RubyGems trusted publishing (OpenID Connect) instead of a stored API key; the `RUBYGEMS_TRUSTED_PUBLISHING` repository variable selects it.
+
+### Fixed
+
+- Sites installing the gem had the search interface and its JavaScript but no search: the page that renders it and the one that builds its index are pages, which a theme gem cannot ship. Both are generated now for any site with `features.search` enabled, and a site that defines either path keeps its own.
+- The published gem could not be used. Jekyll reads `_plugins/` for a site but not for a theme gem, and `lib/datalog-theme.rb` did not load them, so the tags the layouts use were never registered and every consumer site failed to build with `Unknown tag 't'`. Naming the theme under `plugins:` now loads them.
+- The gem shipped `_data/js_manifest.json`, which points every page at the browser bundles, without the bundles themselves: `assets/js/dist/` is build output that git does not track, and the gemspec selected files with `git ls-files`. Sites using the theme loaded no JavaScript at all.
+- The gemspec did not declare `loofah`, which the notebook plugin requires, so loading the theme raised `cannot load such file -- loofah`.
+- The home layout sorted `site.portfolio`, which is nil unless a site declares that collection, and sorting nil stops the build. The section is skipped when the collection is absent.
+- The search index shipped every tag as a list of single characters, so the tag filter on the search page offered 34 buttons reading `a`, `b`, `[`, `"` and so on instead of the 48 real tags. A `split: ''` in the index template turned each tag array into its string form before splitting it.
+- A tag consisting only of whitespace produced a filter button with no accessible name at all, which fails WCAG 4.1.2.
+- The fallback author avatar carried an `aria-label` on a plain `div`, where ARIA prohibits it, so screen readers announced nothing for it. It is now an image role, matching the photo it stands in for.
+- Text set in the teal accent failed WCAG AA everywhere it appeared, reaching only 3.0:1 to 3.5:1 on post badges, skill tags, search highlights and Prism keywords. Teal text now uses a darker tone; the original teal stays for fills and borders.
+- Dark mode had several unreadable components, none of which any check covered: the citation tools kept light backgrounds under light text, leaving a heading white on white at 1.09:1, and difficulty badges kept their light-mode text colour on a near-black pill at 1.93:1.
+- Buttons marked `btn--ghost` were never styled, so they fell back to the browser's own button chrome and could not follow the theme.
+- The Playwright and coverage reports were copied into the built site and published with it. Both are excluded now, and the Playwright report is also ignored by git.
+- `datalog check` reported every dependency as missing on Windows, including bundler, which it treats as a critical failure. The probe called `command -v`, a POSIX shell builtin with no executable behind it; it now searches `PATH` itself, honouring `PATHEXT`.
+- The build and test scripts run on Windows. `npm run test:integration` spawned the Playwright `.cmd` launcher, which Node refuses with `EINVAL`; `npm run build:critical` spawned `bundle`, which is a `.bat` there and failed with `ENOENT`; `bundle exec rake ci:verify` invoked `python3`, which on Windows is a Microsoft Store stub rather than the interpreter; and the CLI tests ran the binstub through its shebang. Node dependencies now run under the current Node binary instead of their launcher shims, and the remaining launchers go through the command interpreter with arguments quoted, so paths containing spaces survive.
+- The site navigation no longer renders expanded and then animates shut on small screens once the script runs, which moved the whole page by about 340 px and put every page's cumulative layout shift near 0.3.
+
+### Removed
+
+- Percy and its visual suite (`tests/visual/`): Percy never ran without a token and carried the last open npm advisory and about 150 packages, and the suite failed 34 of its 58 specs on CDN waits and strict locators, locally and in CI. The integration specs under `tests/integration/` remain the browser checks and gate every deploy. `npm audit` is clean.
+- The `jekyll-jupyter-notebook` gem and the Jupyter toolchain. Notebook pages are rendered by the theme; only `nbformat` remains, for the notebook validation script.
+- `_data/config/site.yml`, `theme.yml` and `features.yml`, which nothing read.
+
 ## [0.6.1] - 2026-09-11
 
 ### Fixed

data/CITATION.cff

@@ -16,8 +16,8 @@ abstract: >-
   It offers integrated notebook publishing, advanced math rendering, interactive
   visualization workflows, and reproducibility tooling optimised for open science communities.
 license: MIT
-version: 0.6.1
-date-released: 2026-09-11
+version: 0.7.0
+date-released: 2026-09-12
 keywords:
   - data-science
   - jekyll

data/README.md

@@ -1,5 +1,6 @@
 # DataLog — A Data Science Jekyll Theme
 
+[![Gem Version](https://img.shields.io/gem/v/datalog-theme)](https://rubygems.org/gems/datalog-theme)
 [![Tests](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/test.yml/badge.svg)](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/test.yml)
 [![Deploy](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/deploy.yml/badge.svg)](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/deploy.yml)
 [![Gem Release](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/gem-release.yml/badge.svg)](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/gem-release.yml)
@@ -40,7 +41,7 @@ site; the rest is reference content you can copy from.
 | Demo content (this site only) | `_posts/`, `_notebooks/`, `_portfolio/`, `_datasets/`, `_packages/`, `_pages/`, `index.md`, `404.html` |
 | Starter scaffold | `template/` — minimal seed for the [GitHub template repository](docs/template-repository.md); excluded from this site's build |
 | Configuration | `_config.yml`, `_data/`, `Gemfile`, `package.json`, `requirements.txt` |
-| Tests & tooling | `tests/`, `scripts/`, `Rakefile`, `vitest.config.js`, `playwright.config.js`, `pa11yci.json`, `lighthouserc.json`, `percy.config.yml` |
+| Tests & tooling | `tests/`, `scripts/`, `Rakefile`, `vitest.config.js`, `playwright.config.js`, `pa11yci.json`, `lighthouserc.json` |
 | Docs | `docs/`, `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md`, `TESTING.md` |
 
 ```
@@ -95,7 +96,7 @@ site; the rest is reference content you can copy from.
 2. **Configure environment** (optional)
 
    Copy [`.env.example`](.env.example) to `.env` and fill in any keys you
-   need — GA4 credentials, Percy/Codecov tokens, Playwright base URL, etc.
+   need — GA4 credentials, the Codecov token, Playwright base URL, etc.
    All values are optional; the site runs without them, and features that
    require credentials will skip cleanly. See
    [docs/environment-setup.md](docs/environment-setup.md) for the full reference.

data/_data/js_meta.json

@@ -1,42 +1,42 @@
 {
   "inputs": {
     "assets/js/core/dark-mode.js": {
-      "bytes": 2141,
+      "bytes": 2409,
       "imports": [],
       "format": "esm"
     },
     "assets/js/core/github-cards.js": {
-      "bytes": 3529,
+      "bytes": 3406,
       "imports": [],
       "format": "esm"
     },
     "assets/js/core/language-filter.js": {
-      "bytes": 544,
+      "bytes": 2032,
       "imports": [],
       "format": "esm"
     },
     "assets/js/core/navigation.js": {
-      "bytes": 4931,
+      "bytes": 4747,
       "imports": [],
       "format": "esm"
     },
     "assets/js/core/scroll-progress.js": {
-      "bytes": 1533,
+      "bytes": 1511,
       "imports": [],
       "format": "esm"
     },
     "assets/js/core/search-hotkeys.js": {
-      "bytes": 1697,
+      "bytes": 1635,
       "imports": [],
       "format": "esm"
     },
     "assets/js/core/skip-links.js": {
-      "bytes": 1541,
+      "bytes": 1479,
       "imports": [],
       "format": "esm"
     },
     "assets/js/main.js": {
-      "bytes": 769,
+      "bytes": 746,
       "imports": [
         {
           "path": "assets/js/core/dark-mode.js",
@@ -77,22 +77,22 @@
       "format": "esm"
     },
     "assets/js/loader.js": {
-      "bytes": 4855,
+      "bytes": 4692,
       "imports": [],
       "format": "esm"
     },
     "assets/js/search/analytics.js": {
-      "bytes": 2144,
+      "bytes": 2547,
       "imports": [],
       "format": "esm"
     },
     "assets/js/search/utils.js": {
-      "bytes": 2571,
+      "bytes": 2472,
       "imports": [],
       "format": "esm"
     },
     "assets/js/search/autocomplete.js": {
-      "bytes": 3285,
+      "bytes": 3165,
       "imports": [
         {
           "path": "assets/js/search/utils.js",
@@ -103,7 +103,7 @@
       "format": "esm"
     },
     "assets/js/search/engine.js": {
-      "bytes": 7382,
+      "bytes": 7122,
       "imports": [
         {
           "path": "assets/js/search/utils.js",
@@ -114,12 +114,12 @@
       "format": "esm"
     },
     "assets/js/search/filters.js": {
-      "bytes": 1089,
+      "bytes": 1269,
       "imports": [],
       "format": "esm"
     },
     "assets/js/search/render.js": {
-      "bytes": 7229,
+      "bytes": 7012,
       "imports": [
         {
           "path": "assets/js/search/utils.js",
@@ -130,7 +130,7 @@
       "format": "esm"
     },
     "assets/js/search/app.js": {
-      "bytes": 8173,
+      "bytes": 7902,
       "imports": [
         {
           "path": "assets/js/search/analytics.js",
@@ -161,7 +161,7 @@
       "format": "esm"
     },
     "assets/js/search.js": {
-      "bytes": 10374,
+      "bytes": 10020,
       "imports": [
         {
           "path": "assets/js/search/app.js",
@@ -172,27 +172,27 @@
       "format": "esm"
     },
     "assets/js/math.js": {
-      "bytes": 27298,
+      "bytes": 26480,
       "imports": [],
       "format": "esm"
     },
     "assets/js/visualizations.js": {
-      "bytes": 27138,
+      "bytes": 26322,
       "imports": [],
       "format": "esm"
     },
     "assets/js/notebook.js": {
-      "bytes": 5385,
+      "bytes": 5227,
       "imports": [],
       "format": "esm"
     },
     "assets/js/academic.js": {
-      "bytes": 8818,
+      "bytes": 8556,
       "imports": [],
       "format": "esm"
     },
     "assets/js/analytics-dashboard.js": {
-      "bytes": 12542,
+      "bytes": 12160,
       "imports": [],
       "format": "esm"
     }
@@ -206,19 +206,19 @@
       "entryPoint": "assets/js/main.js",
       "inputs": {
         "assets/js/core/dark-mode.js": {
-          "bytesInOutput": 630
+          "bytesInOutput": 750
         },
         "assets/js/core/github-cards.js": {
           "bytesInOutput": 1333
         },
         "assets/js/core/language-filter.js": {
-          "bytesInOutput": 163
+          "bytesInOutput": 470
         },
         "assets/js/core/navigation.js": {
           "bytesInOutput": 1851
         },
         "assets/js/core/scroll-progress.js": {
-          "bytesInOutput": 518
+          "bytesInOutput": 542
         },
         "assets/js/core/search-hotkeys.js": {
           "bytesInOutput": 563
@@ -230,7 +230,7 @@
           "bytesInOutput": 125
         }
       },
-      "bytes": 5749
+      "bytes": 6200
     },
     "assets/js/dist/loader.js": {
       "imports": [],
@@ -255,7 +255,7 @@
       "entryPoint": "assets/js/search.js",
       "inputs": {
         "assets/js/search/analytics.js": {
-          "bytesInOutput": 955
+          "bytesInOutput": 1057
         },
         "assets/js/search/utils.js": {
           "bytesInOutput": 1374
@@ -267,7 +267,7 @@
           "bytesInOutput": 2886
         },
         "assets/js/search/filters.js": {
-          "bytesInOutput": 603
+          "bytesInOutput": 631
         },
         "assets/js/search/render.js": {
           "bytesInOutput": 3641
@@ -279,7 +279,7 @@
           "bytesInOutput": 4357
         }
       },
-      "bytes": 18899
+      "bytes": 19029
     },
     "assets/js/dist/math.js": {
       "imports": [],

data/_includes/components/author-bio.html

@@ -34,8 +34,8 @@ Parameters:
         {%- else -%}
           {%- comment -%} Fallback avatar with initials {%- endcomment -%}
           {%- assign initials = author_name | split: ' ' | map: 'first' | slice: 0, 2 | join: '' | upcase -%}
-          <div class="author-bio__avatar-placeholder" aria-label="{{ author_name }}">
-            <span>{{ initials }}</span>
+          <div class="author-bio__avatar-placeholder" role="img" aria-label="{{ author_name }}">
+            <span aria-hidden="true">{{ initials }}</span>
           </div>
         {%- endif -%}
       </div>

data/_includes/components/hero.html

@@ -1,6 +1,24 @@
-{% assign hero_bg = page.hero_image | default: '/assets/img/20220607123041_detail.001.png' %}
+{% assign hero_bg = page.hero_image | default: '/assets/img/hero-detail.webp' %}
+{% assign hero_bg_small = page.hero_image_small %}
+{% if page.hero_image == nil and hero_bg_small == nil %}
+  {% assign hero_bg_small = '/assets/img/hero-detail-640.webp' %}
+{% endif %}
+{%- comment -%}
+  The hero is the largest paint on the page. A CSS background is only requested
+  once the stylesheet applies, so preload it; small screens get a 640 px
+  variant (page.hero_image_small when a page brings its own hero_image).
+{%- endcomment -%}
+{% if hero_bg_small %}
+<link rel="preload" as="image" href="{{ hero_bg_small | relative_url }}" media="(max-width: 640px)" fetchpriority="high" />
+<link rel="preload" as="image" href="{{ hero_bg | relative_url }}" media="(min-width: 641px)" fetchpriority="high" />
+{% else %}
+<link rel="preload" as="image" href="{{ hero_bg | relative_url }}" fetchpriority="high" />
+{% endif %}
 <style nonce="{{ page.csp_nonce }}">
   .hero { --hero-bg: url('{{ hero_bg | relative_url }}'); }
+{% if hero_bg_small %}
+  @media (max-width: 640px) { .hero { --hero-bg: url('{{ hero_bg_small | relative_url }}'); } }
+{% endif %}
 </style>
 <section class="hero">
   <div class="hero-overlay"></div>

data/_includes/head.html

@@ -10,21 +10,14 @@
 {% elsif raw_keywords %}
   {% assign keyword_list = raw_keywords | replace: ';', ',' | split: ',' %}
 {% endif %}
-{% assign math_settings = site.theme_options.math %}
-{% assign math_engine = page.math_engine | default: math_settings.engine | default: 'mathjax' %}
-{% assign math_enabled = page.mathjax %}
-{% if math_enabled == nil %}
-  {% assign math_enabled = page.math %}
-{% endif %}
-{% if math_enabled == nil %}
-  {% assign math_enabled = math_settings.render_on_load | default: site.features.mathjax %}
-{% endif %}
+{% include meta/math-config.html page=page %}
 {% assign js_manifest = site.data.js_manifest %}
 {% assign syntax_config = site.theme_options.syntax_highlighting %}
 {% assign prism_cdn = syntax_config.cdn | default: 'https://cdn.jsdelivr.net/npm/prismjs@1.29.0' %}
 {% assign prism_theme = syntax_config.themes.dark | default: syntax_config.themes.light | default: 'prism-tomorrow' %}
 {% assign prism_theme_url = prism_cdn | append: '/themes/' | append: prism_theme | append: '.css' %}
 {% assign prism_line_numbers_url = prism_cdn | append: '/plugins/line-numbers/prism-line-numbers.min.css' %}
+{% include meta/syntax-config.html %}
 <meta charset="utf-8" />
 <meta http-equiv="X-UA-Compatible" content="IE=edge" />
 {% include csp-meta.html %}
@@ -103,14 +96,16 @@
 <link rel="preconnect" href="https://fonts.googleapis.com" />
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
 <link rel="preload" href="{{ 'https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;500;600;700&family=IBM+Plex+Serif:wght@400;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap' | add_sri }}" as="style" />
-<link rel="stylesheet" href="{{ 'https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;500;600;700&family=IBM+Plex+Serif:wght@400;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap' | add_sri }}" media="print" data-async-style />
+<link rel="stylesheet" href="{{ 'https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;500;600;700&family=IBM+Plex+Serif:wght@400;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap' | add_sri }}" media="print" data-async-style media="print" data-async-style />
 <noscript>
   <link rel="stylesheet" href="{{ 'https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;500;600;700&family=IBM+Plex+Serif:wght@400;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap' | add_sri }}" />
 </noscript>
 
 <link rel="preconnect" href="https://cdn.jsdelivr.net" crossorigin />
+{% if prism_enabled %}
 <link rel="stylesheet" href="{{ prism_theme_url | add_sri }}" />
 <link rel="stylesheet" href="{{ prism_line_numbers_url | add_sri }}" />
+{% endif %}
 {% assign critical_config = site.critical_css | default: {} %}
 {% assign critical_enabled = critical_config.enabled | default: false %}
 {% assign main_stylesheet = '/assets/css/main.css' | relative_url %}

data/_includes/header.html

@@ -63,7 +63,7 @@
     {% if page.layout %}{% assign page_contexts = page_contexts | push: page.layout %}{% endif %}
     {% if page.collection %}{% assign page_contexts = page_contexts | push: page.collection %}{% endif %}
     {% if page.type %}{% assign page_contexts = page_contexts | push: page.type %}{% endif %}
-    <nav id="site-nav" class="site-nav" role="navigation" aria-label="Primary navigation" data-open="true">
+    <nav id="site-nav" class="site-nav" role="navigation" aria-label="Primary navigation" data-open="false">
       {% include header/navigation.html items=nav_items page=page contexts=page_contexts %}
     </nav>
   </div>

data/_includes/meta/math-config.html

@@ -7,10 +7,16 @@ optional:
 ---
 Computes math rendering settings shared by layouts.
 Exposes math_enabled, math_engine, math_status_id, and math_has_expressions variables.
+
+math_enabled resolves, in order: the page's `mathjax` or `math` front matter,
+then `theme_options.math.render_on_load` (falling back to `features.mathjax`).
+With `render_on_load: auto` the engine is only loaded when the rendered page
+contains math (`$`, `\(`, `\[` or kramdown's `math/tex` scripts) or declares
+`math_expressions`; `true` loads it on every page; `false` only on pages that
+opt in.
 {%- endcomment -%}
 {%- assign math_settings = site.theme_options.math | default: {} -%}
 {%- assign math_engine = include.page.math_engine | default: math_settings.engine | default: 'mathjax' -%}
-{%- assign math_enabled = include.page.mathjax | default: include.page.math | default: math_settings.render_on_load | default: site.features.mathjax -%}
 {%- assign math_status_id = include.status_id | default: 'math-status' -%}
 {%- assign math_expressions = include.page.math_expressions | default: '' -%}
 {%- assign math_has_expressions = false -%}
@@ -19,3 +25,19 @@ Exposes math_enabled, math_engine, math_status_id, and math_has_expressions vari
     {%- assign math_has_expressions = true -%}
   {%- endif -%}
 {%- endif -%}
+{%- assign math_load = math_settings.render_on_load -%}
+{%- if math_load == nil -%}
+  {%- assign math_load = site.features.mathjax -%}
+{%- endif -%}
+{%- if include.page.mathjax != nil -%}
+  {%- assign math_enabled = include.page.mathjax -%}
+{%- elsif include.page.math != nil -%}
+  {%- assign math_enabled = include.page.math -%}
+{%- elsif math_load == 'auto' -%}
+  {%- assign math_enabled = math_has_expressions -%}
+  {%- if content contains 'math/tex' or content contains '$' or content contains '\(' or content contains '\[' -%}
+    {%- assign math_enabled = true -%}
+  {%- endif -%}
+{%- else -%}
+  {%- assign math_enabled = math_load -%}
+{%- endif -%}

data/_includes/meta/scripts-loader.html

@@ -12,7 +12,8 @@ Pass location="head" or location="body" to control which block renders.
 {%- assign prism_cdn = syntax.cdn | default: 'https://cdn.jsdelivr.net/npm/prismjs@1.29.0' -%}
 {%- assign default_components = 'python|r|sql|julia|javascript' | split: '|' -%}
 {%- assign prism_components = syntax.components | default: default_components -%}
-{%- if include.location == 'head' -%}
+{%- include meta/syntax-config.html -%}
+{%- if include.location == 'head' and prism_enabled -%}
   <script defer src="{{ (prism_cdn | append: '/prism.min.js') | add_sri }}"></script>
   {%- for component in prism_components -%}
     {%- unless component == 'core' -%}

data/_includes/meta/syntax-config.html

@@ -0,0 +1,19 @@
+{%- comment -%}
+Decides whether the Prism assets are needed on this page. Exposes prism_enabled.
+
+Resolution order: the page's `syntax_highlighting` front matter, then
+`theme_options.syntax_highlighting.load`: `auto` (the default) loads Prism only
+when the rendered page contains a code block; `always` loads it on every page.
+{%- endcomment -%}
+{%- assign syntax_settings = site.theme_options.syntax_highlighting | default: {} -%}
+{%- assign syntax_load = syntax_settings.load | default: 'auto' -%}
+{%- if page.syntax_highlighting != nil -%}
+  {%- assign prism_enabled = page.syntax_highlighting -%}
+{%- elsif syntax_load == 'auto' -%}
+  {%- assign prism_enabled = false -%}
+  {%- if content contains '<pre' or content contains 'class="language-' or content contains 'class="highlight' -%}
+    {%- assign prism_enabled = true -%}
+  {%- endif -%}
+{%- else -%}
+  {%- assign prism_enabled = true -%}
+{%- endif -%}

data/_includes/scripts.html

@@ -1,12 +1,4 @@
-{% assign math_settings = site.theme_options.math %}
-{% assign math_engine = page.math_engine | default: math_settings.engine | default: 'mathjax' %}
-{% assign math_enabled = page.mathjax %}
-{% if math_enabled == nil %}
-  {% assign math_enabled = page.math %}
-{% endif %}
-{% if math_enabled == nil %}
-  {% assign math_enabled = math_settings.render_on_load | default: site.features.mathjax %}
-{% endif %}
+{% include meta/math-config.html page=page %}
 {% assign js_manifest = site.data.js_manifest %}
 
 {% if site.features.search %}