datalog-theme 0.10.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64603590b57087b7aa895fb3e0e5047d213506583382a640d775541e85d1c929
-  data.tar.gz: 4ee7ec7bdc68fcbe9876ec07aaf74d9e78e70666f34c1135244ff382cae4e3fd
+  metadata.gz: 0a6f608b10a3157fb14d9f0c48112f37f53f1772fd824871dd092c22384b9312
+  data.tar.gz: 7c60b3bcc2a41c04d48b7975169d75de86f53e589ed0aa228ec026f6c7151484
 SHA512:
-  metadata.gz: 80b4d09c2a23c57e540dbf4853c07b73f9b78f231acbba8cf0b6577e07df61d5ddd77efb2d619f0ebfeb14847a5f42dc0b2f9495562f91317ec384383697a194
-  data.tar.gz: a2a82ffd1dd92e1961d5aeccdde0161e28a39f63755b85eb933faf61556530bad647d88d20fbc84b0cd38723e25196415d1d44ce80e48239bc3246ba27431737
+  metadata.gz: 846cd1d47b6a4e711d210411765137c459cd047f8787d559021e353317614d7033f61ade9e05502eb46b8c51fc56324999df7ff0b7442f82ade3b3dc0693b831
+  data.tar.gz: 4d1bd2d991ffdaa7d7c867aa4994b8010471658eba5fee85619585643db2f6ec34a1c49e278fab8081e48e05032fb56b39b3f552096e9a2b00b8dadce6517a18

data/CHANGELOG.md

@@ -2,6 +2,133 @@
 
 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.11.0] - 2026-10-04
+
+### Upgrading from 0.10.x
+
+These change what an existing site shows. Each names the setting that keeps the old behaviour, where there is one:
+
+- **A first visit is dark.** A site without `theme_options.color_scheme.default` used to follow the operating system; set `default: system` to keep that (#374).
+- **Display equations are plain, and only the ones the text can refer to are numbered.** Set `theme_options.math.display_style: card` and `theme_options.math.numbering: all` for the old cards and numbers (#318).
+- **The author and editorial note follows the article.** `theme_options.provenance.position: start`, or `provenance_position` in a post's front matter, puts it back before the body (#317).
+- **A page lists only the works it cites.** A page that cites none listed every entry; add `nocite: all` to keep the full list (#289).
+- **Related posts are ranked by relevance**, so a post may recommend different ones. `related_posts` in `_config.yml` tunes the ranking, and a post's front matter can name its own picks (#294).
+- **A post shows its `summary` under its title**, where the heading repeated its first paragraph; a post without one shows none. Pages with a header of their own (packages, datasets, projects, notebooks, research articles, the home page) no longer get a date, a byline and the build time as "Published" above it (#411).
+
+These need an edit, or can stop a build:
+
+- **Three components are gone:** `components/enhanced-code-block.html`, `components/performance-monitor.html` and `components/viz-table-fallback.html`. A site that includes one gets a build error naming it; remove the include (#355).
+- **Citation keys are checked.** A cited key that no source has, or that two entries share, stops the build and names the page and the key. In `{% datalog_cite key label %}` the second word is now a second key, not a label (#289).
+- **An error raised in a plugin hook stops the build.** A `Jekyll::Errors::FatalException` from a hook was logged as a warning (#289).
+- **`datalog critical-css` runs critical 9.** It needs Node.js 22.13, and Playwright's Chromium for the default `render` engine (`npx playwright install chromium`); `critical_css.engine: static` needs no browser. Remove `critical_css.penthouse_options`, which the build now warns about. A site whose own `node_modules` holds critical 8 needs to update it, and the command says how (#360).
+
+One more to know about, needing no edit: `$dark-ink-200` and `$dark-ink-100` are now slate greys that read on dark surfaces. A site that uses them in its own styles gets the new colours, and one that sets them keeps its own (#415).
+
+### Fixed
+
+- **The maths editor's preview names what it draws** (#422).
+  - **The name:** the preview is a live region, so a screen reader announces what is drawn in it. Its expression had no name, so what was announced was its MathML flattened to text: "σ 2 + E [X]" for `\sigma^2 + \mathbb{E}[X]`. It now gets `role="math"` and the name the rest of the page would give it ("sigma squared + double-struck E [X]"), or its `% alt:` comment, and the name follows each change.
+  - **A "<" in the LaTeX:** `renderLatex` set the LaTeX as HTML, so `a<b` began a tag and nothing was drawn; the preview showed, and announced, "\[a". It now sets it as text.
+  - **Search previews:** the maths previews in search results are drawn the same way, and stay unnamed and out of the tab order, since the LaTeX beside them is what is read (#365).
+
+- **The maths toolkit starts whichever script loads second** (#421).
+  - **The bug:** MathJax's `ready()` started the toolkit only if `math.js` had already loaded, and the loader imports `math.js` after `DOMContentLoaded` while MathJax loads `async`. With MathJax in the browser's cache it was often ready first, and then nothing started the toolkit: no expression got its tab stop, its name on the rendered formula, or its copy and edit tools.
+  - **Now:** `math.js` starts the toolkit itself when it arrives after MathJax's `ready()`, and the toolkit starts once either way. Its options (`numbering`) now sit in the MathJax configuration, under `datalog`, so both sides read the same ones.
+
+- **A formula's screen-reader name says what the formula says** (#417).
+  - **The bug:** the build and the browser derived the name from the LaTeX by spelling out a few commands and replacing every other one with a space. So `f : [a, b] \to \mathbb{R}` was named "f : [a, b] R", `c \in (a, b)` "c (a, b)", and `\pi`, `\sin` and the Greek letters vanished. Spacing commands and `\label` keys were read out, and `\square` became "Mathematical expression".
+  - **Now:** both read the LaTeX as words from one table (`lib/datalog/latex_speech/words.json`). Theorem 1 reads "f: [a, b] to double-struck R", and `\lim_{x \to 0}` reads "limit as x approaches 0". Fractions and roots nest, and a command with no word of its own is read by its name. Sizing, spacing, `\label`, the equation number from `\tag` and the names of environments such as `equation` or `align` are left out of the name; a matrix or `cases` is announced, as "matrix … end matrix".
+  - **Overrides:** a `% alt:` comment still names an expression, and the configuration guide now documents it.
+
+- **A notebook page shows its title once.** Most notebooks open with their title as a `# Title` heading, and the page showed it again straight under its own `<h1>`, as an `<h2>` in a cell box of its own. When the first Markdown cell opens with a heading that is the page's title, that heading is now left out, and a cell that held nothing else isn't drawn. A heading that says something else, and the rest of that cell, stay (#416).
+- **Text that kept the light theme's colour in dark mode now meets AA contrast.** The axe sweep missed all of it: the notebook page wasn't in the sweep, axe leaves text over the notebook header's gradient undecided, and it passes over single characters such as punctuation (#415).
+  - **Notebook page:** the header's values and summary, and the sidebar's counts and execution details, were dark grey on the dark panel at 2.1:1. The header's label was indigo at 2.3:1. They now use the dark theme's secondary ink and accent. A cell's code and outputs sat on a lighter wash than the cell, which put an output's text at 4.2:1 and a chart's warning at 2.9:1. They now sit a shade darker than the cell, as in light mode. In light mode, the header's tags were purple on their own tint at 4:1, and now use a darker purple, `$color-accent-tertiary-text`.
+  - **Code:** 14 Rouge token colours had no dark colour and kept the light one, about 2:1 on the dark code background. They are punctuation, HTML tags, constants, symbols, variables, regular expressions, deleted lines and error output. Each now has a dark colour.
+  - **Palette:** `$dark-ink-200` and `$dark-ink-100` were warm greys left from an older palette, at 2.3:1 and 1.7:1 on the dark page. They are now slate greys that read at 4.5:1 or more on every dark surface.
+  - **Removed:** five notebook output styles that nothing writes (`--stream`, `--error`, `__trace`, `__figure` and `--widget`).
+- **A click on a formula no longer collapses part of it**, nor takes away its focus, its place in the tab order, its role or its label. MathJax's collapsible setting was on: it wrapped parts of an expression in toggles, so a click meant to select or copy a formula collapsed part of it to ◂…▸ ("Let f : ◂ ▸ be twice continuously differentiable"). MathJax then drew the expression again into a new container with none of what the theme gives an expression. The setting is now off (#412).
+  - **Menu changes:** MathJax also draws every expression again when a reader changes a setting in its menu, including turning collapsing back on. A render action in the theme's MathJax configuration now gives each new container its tab stop, role, label and LaTeX back, and the focus to the one that had it, without adding a second link after an equation reference. It sits in the configuration because the menu builds a new MathJax document for some settings, which would lose an action added later.
+- **The default layout's heading no longer repeats or invents a date, an author and a summary** above every layout's own (#411).
+  - **Posts:** a post showed its date and author twice, as bare lines under the title and again in its own row. It now shows them once, and under its title the `summary` its author wrote, where the heading had repeated the post's first paragraph.
+  - **Layouts with their own header:** package, dataset, project, portfolio, notebook, research and home pages show nothing above it but the site header. Before, they showed a "summary" taken from their first paragraph (on the demo, "Installation" or "Key artifacts"), a byline, and the time of the build labelled "Published". A research article no longer has two `<h1>`s.
+  - **Dates:** no page shows the time of the build or of the checkout as its publication date. Jekyll gives an undated document the build's time, and the notebook converter gave a notebook without an execution time its file's, which is the checkout's. Neither reaches the page, the JSON-LD, the citation meta tags, or a citation and its BibTeX, RIS and EndNote exports any more. A citation takes the date it is given, else the page's real date, else its `updated` or `last_updated` date where the layout passes one, and otherwise has no year.
+  - **Microdata:** the heading is no longer a `ScholarlyArticle` microdata item around every page. That item contradicted the JSON-LD of the home page, the archives, packages and datasets, and gave a post a second item of another type. A post's own `TechArticle` item now carries its headline.
+  - **Layouts and plain pages:** `article_meta: false` is how a layout or a page leaves the date and authors to itself, as `show_title: false` leaves it the `<h1>` and the summary under it. A research article shows its `summary` under its own title. A plain page's date and authors are labelled, in the post row's style.
+- A package page in a language other than Python or R had an "Installation" heading over an empty panel. It now shows the Git tab when the page has a `github_url`, and no panel otherwise. The Git tab's `cd` now names the directory the clone makes, which is the repository's name; it used the package's. The buttons of a package or project card wrap onto a second line rather than squeezing their labels into two (#290).
+- The citations plugin escapes every value it writes into the page. The in-text link took `url` straight into `href`, and the list took the formatted entry and the title unescaped. Only an `http(s)` address or a DOI becomes a link now (#289).
+- The academic dashboard (`components/academic-dashboard.html`) works, and the demo renders it at `/academic/` in place of a hand-written English copy. Nothing had rendered it, and it had decayed:
+  - its profiles never appeared, because a `for` loop cannot filter its own collection;
+  - it carried a second `h1`, and a heading for each section even when the data had nothing for it;
+  - its metrics were `dt`/`dd` pairs outside any `dl`, and the bibliography box had no label;
+  - the bibliography entries were joined with a literal `\n\n`, and date-only calendar events read "00:00".
+
+  Citations by year now keep the numbers `_data/academic.yml` gives and draw each bar against the busiest year. The script used to replace them with the publications generator's series, which counts citations by the year of publication, and it set a width CSS cannot read, so no bar showed. The submission and calendar filters now load `academic.js` even on a dashboard without citation metrics. The profile links carry `rel="me"`, like the author card's. A map passed as `academic` supplies the metrics too, and `docs/components.md` documents the component and its data (#355).
+- `datalog update` no longer stops at "already at" when a path-installed theme is already at the release asked for. It answered before checking anything, so a checkout whose script bundles were never built reported success, and `--build` built nothing. It now rebuilds the bundles when they are missing or were built from other sources, runs the same site checks as after an update, and builds the site with `--build`; `--dry-run` says which of these it would do. The exit status is still 0 (#295).
+- A reader who reaches the contact, subscription or correction form before its script has loaded is now told when the service does not take it. Each form asked the service only on the reader's first focus, or for a correction report when its panel opened; on a slow connection that had already happened before the script was listening, so the form stayed ready until the reader sent it and was refused. The check now runs at once when focus is already inside the form or the panel is already open. The same race failed the contact form's browser test on a slow CI runner.
+- Search results are an ordinary list again, so a screen reader can reach what is inside them. Each result was an `option` in a `listbox`, a role whose children are presentational, which put the title link and the matching-section links of every result out of reach in browse mode. The arrow keys now move real focus through the results rather than pointing `aria-activedescendant` at them, Tab reaches them as it reaches any link, Enter follows the focused link, and Escape from the list returns to the query without clearing it (#365).
+- The search results meet AA contrast in both themes. The query highlight took its colour from the card around it, which in dark mode put light grey on a light amber wash at 2.26:1; the tag and difficulty chips sat at 4.32:1 on their own tint; the loading text kept the light theme's grey on the dark surface at 3.27:1. The highlight now takes its colour from the wash it sits on, and the chips and the loading text have dark-mode colours of their own (#365).
+- Code and LaTeX previews in a search result can be scrolled from the keyboard, and the rendered maths beside the LaTeX is `inert`, so it is neither a focus stop nor announced twice (#365).
+- `datalog update`, `datalog check` and `datalog critical-css` read `_config.yml` as Jekyll does. The update's site checks loaded it with a YAML loader that allowed no dates, so a configuration with a date in it (`launched: 2024-01-01`) stopped the update with a `Psych::DisallowedClass` error after the theme checkout had already moved; and all three commands failed on a YAML alias, which Jekyll accepts. One loader now serves the three, allowing dates, times and aliases (#295).
+
+### Added
+
+- **Share cards.** With `theme_options.social_cards.enabled`, the build draws a 1200×630 PNG for each post that names no image of its own. The card shows the title, the series or subtitle, the authors and date, the site's name and logo, and a research article's venue and DOI, on the theme's colours. `og:image` and `twitter:image` point at it, with its width, height and alt text, and so does the JSON-LD `image`. Before, every post without an `og_image` was shared with `social.default_image`.
+  - **Precedence:** `og_image` or `image` in front matter wins, then the card, then the default image. `social_card: false` asks for none.
+  - **Drawing:** ImageMagick draws the cards, as it draws the image variants. The text is set in IBM Plex Serif and Sans, which the gem now ships under the SIL Open Font License, and drawn as outlines, so no font is looked up and Ubuntu's ImageMagick 6 and Windows' ImageMagick 7 draw the same pixels. TeX in a title reads as text ("α-stable laws for X_t²"), and a title of 140 characters fits whole.
+  - **Caching and degrading:** cards are kept in `.jekyll-cache/datalog-social-cards`, keyed by what they show, so an unchanged page draws nothing on the next build. Without ImageMagick the build warns once and every page keeps the default image.
+  - **Settings:** `scheme` (dark or light, both AA for every text colour), `background`, `logo`, `template` (an SVG of the site's own) and `collections`. `docs/configuration-guide.md` documents them and the tools to install. The demo draws a card for each of its posts (#297).
+- **Package pages know their registries.** A package names them in `registry:` (`pypi`, `conda_forge`, `cran`, `crates`, `rubygems`, `npm`, `julia`), and each gives its link and an install tab: `cargo add` with a docs.rs link, `gem install` with the Gemfile line, `npm install` and `Pkg.add`, beside pip, conda, CRAN and Git. `docs_url` adds a Documentation link, and `status` (alpha, beta, stable) shows beside the version. `pypi_url` and `cran_url` still work.
+  - **`bundle exec datalog packages refresh`** reads each package's latest release from PyPI, crates.io, RubyGems, CRAN (through crandb) and npm into `_data/package_releases.yml`: the version, release date and licence, the language version it needs, and whether it is a pre-release (by the registry's own rules: PEP 440, semver or RubyGems) or yanked. The layout shows that release before the front matter's `version`, and the build stays offline. A registry that cannot be read stops the command with exit 1 before the file is touched.
+  - **`components/package-index.html`** lists every package as cards or a table, with its release, install command and purpose, optionally grouped by `language` or any other field. The demo's `/packages/` is that include.
+  - **JSON-LD:** a package page describes its package as `SoftwareSourceCode`, with its repository, language, version, licence, author and registry pages.
+  - `docs/components.md` documents the front matter, the command and the index (#290).
+- **`bundle exec datalog audit`** reports, with the file and line of each finding, what the theme's newer authoring features would improve. It reads the site through Jekyll's reader and never builds or writes it. `docs/scripts-reference.md` describes each check.
+  - **Opportunities** (advice): statements typed as bold "**Theorem**" or "**Definition**"; "Figure 3" typed by hand; posts that look like parts of a series; posts linking a repository, notebook or DOI with no reproducibility block; posts edited long after publication with no revision entry; hand-written reference lists.
+  - **Problems** (warnings, exit 1 with `--strict`): front matter keys that nothing in the theme or the site reads, with the known keys taken from the sources rather than kept as a list; images without alt text; links to pages the site does not build; `math` switched against a post's content.
+  - **Options:** `--format json` or `markdown`, `--only`, `--path`; `audit.known_keys`, `audit.ignore_links` and `audit.revision_after_days` in `_config.yml`.
+  - **Demo:** its first run found dead front matter, which is now removed: `hero:` on eleven posts, pointing at images that do not exist, and `nav_exclude:`, a Just the Docs field, on four pages (#296).
+- **Citations work like `{% ref %}`.**
+  - **Sources:** a page names a BibTeX (`.bib`) or CSL-JSON (`.json`) file in `bibliography`, or the site does in `citations.bibliography`. Entries in front matter still work.
+  - **Tags:** `{% cite key %}`, `{% cite a b %}` and `{% cite key p="12" %}` become "[1]", "[2, 3]" and "[1, p. 12]", each linked to its entry. With `citations.style: author-year` (or `citation_style` on a page) they read "(Rubin 1987)".
+  - **The list:** the article ends with the cited works in citation order (numeric) or by author and year, each entry with its DOI or address as a link and a link back to each place it is cited. `nocite` lists works the text does not cite.
+  - **Errors:** a key no source has, or one two entries share, stops the build and names the page and the key.
+  - **Metadata:** on a research article, each cited work is a `citation_reference` meta tag and a `CreativeWork` in the JSON-LD `citation`.
+  - **Plugin:** it no longer needs `datalog-search`, and adds the cited keys to the index only when search is on. The BibTeX subset is read without a dependency, and the words are translated in English, Portuguese and Spanish. `docs/user-guide.md` has a worked example and `docs/components.md` the reference (#289).
+- An `archive` layout for year, tag, category and curated topic pages, with jump lists, counts per section, localized dates, optional month sections and series grouping for topics, sharing `components/post-list.html` (compact, dated and teaser variants) with the rest of the theme. The starter template includes `/archives/years/`, `/tags/` and `/categories/`; `datalog new archive --type year|tag|category|topic` scaffolds another; a site whose archives live elsewhere sets `tag_archive.path` and `category_archive.path` so tag and category links reach them (#293).
+- Posts offer a way to report an error on a site without dynamic services: a link to a pre-filled GitHub or GitLab issue, labelled with `corrections.issue_labels` and saying before the reader follows it that the issue is public, or an email to `contact_email` (else `author.email`). `corrections.fallback` chooses `issue`, `email` or `none`, and by default takes the issue link when `repository` is a GitHub or GitLab address. The link works without JavaScript; with it, the section and the selected passage are added. The form still takes over wherever the service offers corrections (#292).
+- `datalog update` updates a theme installed from a Git submodule or a local path: it moves the checkout to the latest stable release tag, or the one `--to` names, refuses a checkout with local changes, rebuilds the script bundles, installs the site's gems, prints the release's Removed, Changed and Deprecated notes, and stages the new submodule pointer without committing. `--dry-run` says what it would do and `--build` builds the site into a temporary directory first. It exits 0 when already current, 2 after an update and 1 on failure; installs from RubyGems update as before (#295).
+- The home layout's hero is a contained panel with up to two actions (`hero_cta_label` and `hero_cta_url`, `hero_secondary_cta_label` and `hero_secondary_cta_url`), and `home_features` in the home page's front matter lists feature cards with a title, description and link. The latest posts and portfolio sections are left out when their collections are empty, and a hero background image is preloaded only when one is configured (#375).
+- `layout: docs` gives a guide a section sidebar, drawn from optional `docs` groups in `_data/navigation.yml`, an on-page contents list and links to the previous and next guides; guides share the posts' code-copy control. The documentation site uses it, with search, the colour toggle, a homepage that leads to installation, and a technical authoring guide (#376, #379, #380).
+- The dynamic features have a backend to deploy. [datalog-services](https://github.com/DiogoRibeiro7/datalog-services), a separate repository outside the gem, implements every route of the dynamic-services contract as a Cloudflare Worker with a D1 database, with an OpenAPI description of the contract, a conformance suite any backend can run against a base URL, and a deployment guide. `docs/dynamic-services.md` links all four, and its prose reference deployment is now only what they leave out; `docs/moderation.md` and `docs/components.md` point at the service where they described one (#291).
+- The site can describe itself to search engines. With `site_identity` in `_config.yml` (`true`, or a map with `name` and `alternate_names`), the homepage carries a `WebSite` node with the site's name, other names and URL, which is what Google reads as a site's name, and the publisher in full: the author's `Person` or the `Organization`. `og:site_name` follows the same name. A page with `schema_type: ProfilePage` is now a real profile page: its `mainEntity` is its author (or the publisher, with `main_entity: publisher`) and it is `isPartOf` the website, where the type alone used to change nothing else. The author's `Person` reads `alternate_name`, `job_title` or `roles`, the avatar, `bio`, `knows_about` (or `expertise`, `research_areas`) and a `same_as` list, for every author whose record has them. The site's author and the publisher carry stable `@id`s (`/#person`, `/#organization`) on every page, so an article's author, its publisher and the homepage's person are one entity rather than one per page; this adds an `@id` to the JSON-LD of every page, and a guest gets none. `seo_title_suffix: false` drops the ` | site title` from a page's `<title>`, and a string replaces the site title there. The JSON-LD description already followed the meta description's order (`seo_description`, `description`, excerpt, site description), which a test now holds. Off by default, so a site with its own `WebSite` block does not get two (#322).
+- The site author's profile links say `rel="me"`, so IndieAuth, Mastodon's verified links and other identity checks can connect the site to its owner's accounts, as the JSON-LD `sameAs` already did. It covers the author card's GitHub, Twitter/X, LinkedIn, ORCID and Google Scholar links, each author's ORCID link in the research layout, and the footer's ORCID link, which all follow one rule: `me noopener noreferrer` for the site's own author, `noopener noreferrer` for anyone else, so a guest's profiles are never claimed as the owner's. `profile_rel` on `author` in `_config.yml`, or on a `_data/authors.yml` record, replaces `me` for that person; `noopener` and `noreferrer` are always kept. The footer's ORCID link gains `noreferrer`, which it lacked (#323).
+- A page in `_datasets/` now carries `schema.org/Dataset` structured data, which is what Google Dataset Search indexes; the `WebPage` description a dataset page had could not reach it. The title, summary, `updated`, `license` and field `schema` it already declares fill most of it in, and `doi`, `keywords`, `temporal_coverage`, `spatial_coverage`, `measurement_technique`, `citation`, `is_accessible_for_free` and a `distributions` list are read when present. A dataset with no `date:` claims no publication date rather than the build time (#334).
+- Figures can carry a dark companion. Put `power-dark.png` beside `power.png` and it becomes a `<source media="(prefers-color-scheme: dark)">` at the front of the same `<picture>`, with its own resized copies and modern formats; the `<img>` keeps the light file, its alt text and its dimensions, so the figure is described once. `{% figure %}` takes `dark_src` for a companion that does not follow the convention, as does any `<img data-dark-src="...">`, including one the variant pipeline never reads, such as an SVG. `theme_options.images.dark_suffix` changes the suffix, and `""` turns the convention off. `prefers-color-scheme` follows the operating system and the theme's toggle does not, so `core/dark-mode.js` overrules the query on those sources whenever a reader has chosen a mode for the site; with JavaScript off the figures follow the system. A page's `hero_image` gets the same treatment, through `components/responsive-image.html`, which now builds its `srcset`s with the same code the optimizer uses rather than three copies of its own (#335).
+- Search results link to the section of a page the query was found in, not just to the page. A result is still one entry per page, with at most three matching sections listed under it, each an anchor to the heading itself; the excerpt now comes from the section's own text. The sections are taken from the page's own `h2` and `h3` at build time, using the ids kramdown already gives them, so there is nothing to write in front matter. A page with no headings indexes as one section, as every page did before; the text before the first heading is never offered as a section of itself; a heading with no id still indexes and links to the page; and the split runs over the document's own content, so the headings a layout puts around an article are not sections of every result. An index generated without sections, by an older build or a site's own template, still searches. The repeated text takes `search.json` from 32 KB to 39 KB served compressed on the demo site, and a budget assertion holds it there (#336).
+
+### Changed
+
+- **`datalog critical-css` runs critical 9.** critical 9 rewrote its command line, and the command's `--base`, `--css` and `--penthouse-*` options stopped it with "Unknown option '--base'". The theme's `devDependency` and the `npx` fallback move together, so the theme and the sites using it run the same version.
+  - **How pages reach it:** each page goes to critical on its standard input, from the built site's root, with `assets/css/main.css` as its only stylesheet. The inlined CSS still carries no Google Fonts rules, now whatever the site's `baseurl`. The viewports are one `--dimensions` list.
+  - **Engines:** `critical_css.engine: render`, the default, measures the first screen in Playwright's Chromium at each viewport, as critical 8 did in Puppeteer's Chrome. critical 9 does not download that browser: install it with `npx playwright install chromium`, or let the command install it when it runs critical through `npx`. `engine: static` needs no browser and writes more CSS. On the demo, render's CSS is a quarter to a half larger than critical 8's (4.3 to 6.3 KB gzipped against 3.5 to 4.0 KB), because critical 9 keeps the media queries of every viewport it measures.
+  - **Checks:** the command names a Node.js older than 22.13, which critical 8 needed as well, and a site whose own `node_modules` holds critical 8, with the command that updates it.
+  - **Removed:** `critical_css.penthouse_options`: critical 9 has no penthouse, and the build now warns while the setting is there. The Tests, Deploy and Lighthouse workflows install Playwright's Chromium before they run critical. The unit tests now run the installed critical with the theme's arguments, so a refused option fails there as well as in the consumer test (#360).
+
+- **A page lists only the works it cites.** The citations plugin listed every entry of a page that cited none of them; `nocite: all` restores that.
+  - **Research layout:** its `references:` list of strings is no longer read as citation entries (a list of maps still is), and it shows the cited works in its References section.
+  - **JSON-LD:** `citation` lists the cited works, not the page's own `citation_key`.
+  - **The old tag:** `{% datalog_cite key label %}` is now an alias of `{% cite %}`, so a second word is a second key rather than a custom label.
+  - **Plugin errors:** a `Jekyll::Errors::FatalException` raised in a plugin hook now stops the build instead of being logged as a warning (#289).
+- **Display equations are set plain, and only the ones the text can refer to are numbered.** Each display equation was a bordered, shadowed card, 106 px tall around a 16 px formula, and every one was numbered. An equation now stands on its own line with a `1.25rem` margin and adds nothing to the page but its height and margins; its copy and edit tools appear at the end of its line when the pointer or the focus reaches it, and stay in the tab order. MathJax numbers what amsmath numbers (`equation`, `align`, `gather` and the rest, not their starred forms) and any `$$…$$` display with a `\label{}`, so `\eqref{}` still finds it, and leaves `$$x = 1$$` unnumbered. To keep the old look and numbering, set `theme_options.math.display_style: card` and `theme_options.math.numbering: all`; `numbering: none` numbers only a `\tag{}` of the author's. The validator accepts only those values. The card's styles are compiled only for a site that asks for it, so a plain site's stylesheet does not grow (#318).
+- **The author and editorial note follows the article.** The note that `why_this_exists`, `evidence`, `methodology` and `reviewed_at` make stood between the topics and the body, a screenful on a phone before the first sentence. It now comes after the body and the reproducibility panel, before the revision history and "How to cite", in the document and so for screen readers and in print as well as on screen. A row of the metadata, "Author and editorial note", says when the article was reviewed and links to it. `theme_options.provenance.position: start` puts the note back where it was, and `provenance_position` in a post's front matter chooses for that post (#317).
+- **A first visit is dark.** The palette is indigo and cyan, and a site without `theme_options.color_scheme.default` now opens dark, where it used to follow the operating system. Set `default: system` to keep the old behaviour, or `light`; a reader's choice with the toggle still wins, and dark figure variants follow the mode in effect (#374).
+- **Related posts are ranked by relevance**, so a site's posts may recommend different ones than before. Shared tags count by how rare they are, then categories and keywords, and the date only breaks ties. `related_posts` in `_config.yml` sets `limit`, `min_score` and `weights` (a `text` weight for shared title and excerpt words is off by default). In a post's front matter, `related_posts` lists picks by URL, path or exact title, shown first; a pick that matches nothing or more than one post stops the build. A post's own series is left out and another series appears at most once; `related: false` keeps a post out of other posts' lists and `related_posts: false` hides the section (#294).
+- The analytics dashboard follows the theme's dark and light palettes, redraws its charts when the mode changes, and offers each chart's values as a table. It tells apart data that is configured, empty, unavailable, not set up and stale: when a refresh from the analytics API fails, the last good data stays on the page marked stale rather than shown as current (#377).
+
+### Removed
+
+- `components/enhanced-code-block.html`, `components/performance-monitor.html` and `components/viz-table-fallback.html`, which no layout, page or script included. The first two held inline scripts that the Content Security Policy would block. Code blocks get their copy button from the layouts, and `assets/js/visualizations.js` builds the table fallback's template itself when the page has none, which was always. A site that includes one of them gets a build error naming the file. A test now fails when a file in `_includes/components/` is included by nothing the build renders (#355).
+
 ## [0.10.1] - 2026-09-22
 
 ### 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.10.1
-date-released: 2026-09-22
+version: 0.11.0
+date-released: 2026-10-04
 keywords:
   - data-science
   - jekyll

data/README.md

@@ -75,7 +75,7 @@ site; the rest is reference content you can copy from.
 ## Documentation
 
 - [Documentation Index](docs/README.md) — every guide, grouped by what you want to do.
-- [Documentation Site](docs/site/README.md) — source for the live `datalog-theme.github.io` documentation hub with feature walk-throughs, interactive demos, and migration guides.
+- [Documentation Site](docs/site/README.md) — source for a documentation site built with the theme, with feature walk-throughs, interactive demos, and migration guides. It is not published yet; CI builds it and checks it in a browser on every pull request. The live example of the theme is the [demo site](https://diogoribeiro7.github.io/analytics-blog-jekyll/).
 - [User Guide](docs/user-guide.md) — comprehensive documentation covering installation, notebooks, math, visualizations, research workflows, accessibility, performance, and collaboration best practices for DataLog users.
 - [Environment Setup Guide](docs/environment-setup.md) — configure environment variables, secrets, and integrations for analytics, testing, and deployment.
 - [Scripts Reference](docs/scripts-reference.md) — complete reference for all build, test, import/export, and utility scripts.
@@ -134,6 +134,8 @@ bin/datalog --help
 - `bin/datalog new notebook` — create a notebook landing page and starter `.ipynb` in one step.
 - `bin/datalog new project` — scaffold a portfolio entry with metadata and placeholder sections.
 - `bin/datalog check` — validate runtime dependencies, configuration, and optional tooling like Node.js.
+- `bin/datalog audit` — list the posts that would gain from newer authoring features (statements, figures, series, citations) and content problems (unread front matter, images without alt text, broken internal links), with file and line; `--strict` for CI. See [docs/scripts-reference.md](docs/scripts-reference.md#datalog-audit).
+- `bin/datalog packages refresh` — read each package's latest release from its registries (PyPI, crates.io, RubyGems, CRAN, npm) into `_data/package_releases.yml`, which package pages show before their front matter. See [docs/components.md](docs/components.md#package-pages).
 - `bin/datalog publish` — build the site and push the `_site` artifacts to your GitHub Pages branch via git worktrees.
 - `bin/datalog update` — upgrade the `datalog-theme` gem and refresh npm packages when applicable.
 
@@ -208,7 +210,7 @@ Data-driven configuration allows you to publish or reorder projects, datasets, s
 Add the theme gem to your Jekyll site:
 
 ```ruby
-gem "datalog-theme", "~> 0.10.0"
+gem "datalog-theme", "~> 0.11.0"
 ```
 
 The constraint takes the patch releases of the current minor series. Until 1.0 a minor release may include breaking changes, listed in the [changelog](CHANGELOG.md).

data/_data/i18n/en.yml

@@ -2,6 +2,7 @@
 date:
   formats:
     long: "%B %-d, %Y"
+    month: "%B"
     datetime: "%B %-d, %Y %H:%M"
   months:
     1: January
@@ -45,6 +46,14 @@ date:
     4: Thu
     5: Fri
     6: Sat
+archive:
+  jump: Jump to archive section
+  count: "({{count}} posts)"
+  show_all: "Show all ({{count}} more)"
+  series: Series
+  parts: "({{count}} parts)"
+  articles: Articles
+  empty: No articles published yet.
 global:
   skip_to_main: Skip to main content
   math_ready: Mathematical content is ready
@@ -147,6 +156,8 @@ navigation:
       julia: Julia
       javascript: JavaScript
 home:
+  features: What you can publish
+  explore_more: Explore more
   latest_research: Latest Research Notes
   reading_time_one: 1 min read
   reading_time_many: "{{minutes}} mins read"
@@ -162,6 +173,14 @@ article:
     authors: Authors
 corrections:
   summary: Report an error or suggest a correction
+  fallback:
+    subject: "Correction: {{title}}"
+    article: Article
+    url: Address
+    prompt: "Describe the error and the suggested correction."
+    section: Section
+    quote: Selected passage
+    public_note: "Issue reports are public. Do not include private information."
   intro: "Spotted a mistake in the mathematics, the facts, a citation, the code or the reproducibility? Say what and where. The report goes to the author, not onto the page."
   category: What kind of problem
   section: Where
@@ -370,6 +389,16 @@ dynamic_services:
     aborted: The request was cancelled.
     retry_after: "Try again in {{seconds}} seconds."
     reference: "Reference: {{id}}"
+citations:
+  and: and
+  et_al: et al.
+  no_date: n.d.
+  back: "Back to citation {{n}}"
+  locators:
+    p: p.
+    pp: pp.
+    chap: ch.
+    sec: sec.
 references:
   figure: Figure
   table: Table
@@ -390,6 +419,8 @@ post:
     evidence: Evidence used
     method: Method
     reviewed: Reviewed
+    reviewed_on: "Reviewed {{date}}"
+    link: How this article was made
   revisions:
     heading: Revision history
     corrected_on: "Corrected on {{date}}."
@@ -550,9 +581,6 @@ notebook:
     launch_binder: Launch in Binder
     open_colab: Open in Colab
 academic_dashboard:
-  header:
-    title: Academic integration hub
-    description: Monitor publication metrics, synchronize academic profiles, and coordinate submissions, funding, and mentorship opportunities.
   profiles:
     title: Academic profiles & synchronization
     view_profile: View profile
@@ -565,6 +593,7 @@ academic_dashboard:
     featured_projects: Featured projects
     collections: Collections
     auto_update: Auto update
+    auto_update_on: "On"
   citations:
     title: Citation metrics
     total: Total citations
@@ -748,6 +777,15 @@ analytics:
     last_updated: Last updated
     last_updated_unknown: "Last updated: pending"
     cache_window: Data cached for 24 hours
+    current: Current results
+    stale: Cached results
+    stale_note: GA4 is unavailable. Showing the last successful cached results.
+    setup_needed: Setup needed
+    unavailable: Unavailable
+    empty: No results yet
+    view_data: View data table
+    chart_unavailable: Chart unavailable; use the data table below.
+    no_chart_data: No chart data available.
     top_posts: Top posts
     search_terms: Search queries
     visitor_trends: Visitor trends
@@ -785,3 +823,17 @@ package_install:
   copy: Copy
   copied: Copied!
   copy_error: Could not copy
+  gemfile: Gemfile
+  julia_repl: Julia REPL
+packages:
+  documentation: Documentation
+  prerelease: pre-release
+  yanked: yanked
+  index:
+    title: Packages
+    other: Other
+    package: Package
+    release: Release
+    install: Install
+    purpose: Purpose
+    empty: No packages yet.

data/_data/i18n/es.yml

@@ -1,6 +1,7 @@
 ---
 date:
   formats:
+    month: "%B"
     long: "%d de %B de %Y"
     datetime: "%d de %B de %Y %H:%M"
   months:
@@ -45,6 +46,14 @@ date:
     4: Jue
     5: Vie
     6: Sáb
+archive:
+  jump: Ir a la sección del archivo
+  count: "({{count}} artículos)"
+  show_all: "Mostrar todos ({{count}} más)"
+  series: Series
+  parts: "({{count}} partes)"
+  articles: Artículos
+  empty: Aún no hay artículos publicados.
 global:
   skip_to_main: Ir al contenido principal
   math_ready: El contenido matemático está disponible
@@ -147,6 +156,8 @@ navigation:
       julia: Julia
       javascript: JavaScript
 home:
+  features: Qué puedes publicar
+  explore_more: Explorar más
   latest_research: Notas de investigación recientes
   reading_time_one: Lectura de 1 min
   reading_time_many: "Lectura de {{minutes}} min"
@@ -162,6 +173,14 @@ article:
     authors: Autores
 corrections:
   summary: Informar de un error o sugerir una corrección
+  fallback:
+    subject: "Corrección: {{title}}"
+    article: Artículo
+    url: Dirección
+    prompt: "Describe el error y la corrección sugerida."
+    section: Sección
+    quote: Pasaje seleccionado
+    public_note: "Los informes mediante incidencias son públicos. No incluyas datos privados."
   intro: "¿Has visto un error en las matemáticas, los hechos, una cita, el código o la reproducibilidad? Di qué y dónde. El informe va al autor, no a la página."
   category: Qué tipo de problema
   section: Dónde
@@ -370,6 +389,16 @@ dynamic_services:
     aborted: La solicitud se canceló.
     retry_after: "Inténtalo de nuevo en {{seconds}} segundos."
     reference: "Referencia: {{id}}"
+citations:
+  and: "y"
+  et_al: et al.
+  no_date: s.f.
+  back: "Volver a la cita {{n}}"
+  locators:
+    p: p.
+    pp: pp.
+    chap: cap.
+    sec: secc.
 references:
   figure: Figura
   table: Tabla
@@ -390,6 +419,8 @@ post:
     evidence: Evidencia utilizada
     method: Método
     reviewed: Revisado
+    reviewed_on: "Revisado el {{date}}"
+    link: Cómo se hizo este artículo
   revisions:
     heading: Historial de revisiones
     corrected_on: "Corregido el {{date}}."
@@ -550,9 +581,6 @@ notebook:
     launch_binder: Abrir en Binder
     open_colab: Abrir en Colab
 academic_dashboard:
-  header:
-    title: Centro de integración académica
-    description: Supervise métricas de publicación, sincronice perfiles académicos y coordine envíos, financiación y mentorías.
   profiles:
     title: Perfiles académicos y sincronización
     view_profile: Ver perfil
@@ -565,6 +593,7 @@ academic_dashboard:
     featured_projects: Proyectos destacados
     collections: Colecciones
     auto_update: Actualización automática
+    auto_update_on: "Activada"
   citations:
     title: Métricas de citación
     total: Total de citas
@@ -748,6 +777,15 @@ analytics:
     last_updated: Última actualización
     last_updated_unknown: "Última actualización: pendiente"
     cache_window: Datos en caché por 24 horas
+    current: Resultados actuales
+    stale: Resultados en caché
+    stale_note: GA4 no está disponible. Se muestran los últimos resultados guardados.
+    setup_needed: Configuración necesaria
+    unavailable: No disponible
+    empty: Aún no hay resultados
+    view_data: Ver tabla de datos
+    chart_unavailable: Gráfico no disponible; consulta la tabla de datos de abajo.
+    no_chart_data: No hay datos para el gráfico.
     top_posts: Entradas destacadas
     search_terms: Consultas de búsqueda
     visitor_trends: Tendencias de visitantes
@@ -785,3 +823,17 @@ package_install:
   copy: Copiar
   copied: ¡Copiado!
   copy_error: No se pudo copiar
+  gemfile: Gemfile
+  julia_repl: REPL de Julia
+packages:
+  documentation: Documentación
+  prerelease: prelanzamiento
+  yanked: retirada
+  index:
+    title: Paquetes
+    other: Otros
+    package: Paquete
+    release: Versión
+    install: Instalación
+    purpose: Para qué sirve
+    empty: Todavía no hay paquetes.

data/_data/i18n/pt.yml

@@ -1,6 +1,7 @@
 ---
 date:
   formats:
+    month: "%B"
     long: "%d de %B de %Y"
     datetime: "%d de %B de %Y %H:%M"
   months:
@@ -45,6 +46,14 @@ date:
     4: Qui
     5: Sex
     6: Sáb
+archive:
+  jump: Ir para a secção do arquivo
+  count: "({{count}} artigos)"
+  show_all: "Mostrar todos (mais {{count}})"
+  series: Séries
+  parts: "({{count}} partes)"
+  articles: Artigos
+  empty: Ainda não há artigos publicados.
 global:
   skip_to_main: Ir para o conteúdo principal
   math_ready: Conteúdo matemático disponível
@@ -147,6 +156,8 @@ navigation:
       julia: Julia
       javascript: JavaScript
 home:
+  features: O que pode publicar
+  explore_more: Explorar mais
   latest_research: Notas de investigação recentes
   reading_time_one: Leitura de 1 min
   reading_time_many: "Leitura de {{minutes}} min"
@@ -162,6 +173,14 @@ article:
     authors: Autores
 corrections:
   summary: Comunicar um erro ou sugerir uma correção
+  fallback:
+    subject: "Correção: {{title}}"
+    article: Artigo
+    url: Endereço
+    prompt: "Descreva o erro e a correção sugerida."
+    section: Secção
+    quote: Passagem selecionada
+    public_note: "As comunicações por issue são públicas. Não inclua dados privados."
   intro: "Encontrou um erro na matemática, nos factos, numa citação, no código ou na reprodutibilidade? Diga o quê e onde. O relato vai para o autor, não para a página."
   category: Que tipo de problema
   section: Onde
@@ -370,6 +389,16 @@ dynamic_services:
     aborted: O pedido foi cancelado.
     retry_after: "Tente novamente em {{seconds}} segundos."
     reference: "Referência: {{id}}"
+citations:
+  and: e
+  et_al: et al.
+  no_date: s.d.
+  back: "Voltar à citação {{n}}"
+  locators:
+    p: p.
+    pp: pp.
+    chap: cap.
+    sec: sec.
 references:
   figure: Figura
   table: Tabela
@@ -390,6 +419,8 @@ post:
     evidence: Evidência utilizada
     method: Método
     reviewed: Revisto
+    reviewed_on: "Revisto a {{date}}"
+    link: Como este artigo foi feito
   revisions:
     heading: Histórico de revisões
     corrected_on: "Corrigido em {{date}}."
@@ -550,9 +581,6 @@ notebook:
     launch_binder: Abrir no Binder
     open_colab: Abrir no Colab
 academic_dashboard:
-  header:
-    title: Hub de integração académica
-    description: Monitorize métricas de publicação, sincronize perfis académicos e coordene submissões, financiamento e programas de mentoria.
   profiles:
     title: Perfis académicos e sincronização
     view_profile: Ver perfil
@@ -565,6 +593,7 @@ academic_dashboard:
     featured_projects: Projetos em destaque
     collections: Coleções
     auto_update: Atualização automática
+    auto_update_on: "Ativa"
   citations:
     title: Métricas de citação
     total: Total de citações
@@ -748,6 +777,15 @@ analytics:
     last_updated: Última atualização
     last_updated_unknown: "Última atualização: pendente"
     cache_window: Dados em cache por 24 horas
+    current: Resultados atuais
+    stale: Resultados em cache
+    stale_note: O GA4 está indisponível. Exibindo os últimos resultados armazenados.
+    setup_needed: Configuração necessária
+    unavailable: Indisponível
+    empty: Ainda não há resultados
+    view_data: Ver tabela de dados
+    chart_unavailable: Gráfico indisponível; consulte a tabela de dados abaixo.
+    no_chart_data: Não há dados para o gráfico.
     top_posts: Principais publicações
     search_terms: Consultas de pesquisa
     visitor_trends: Tendências de visitantes
@@ -785,3 +823,17 @@ package_install:
   copy: Copiar
   copied: Copiado!
   copy_error: Não foi possível copiar
+  gemfile: Gemfile
+  julia_repl: REPL do Julia
+packages:
+  documentation: Documentação
+  prerelease: pré-lançamento
+  yanked: retirada
+  index:
+    title: Pacotes
+    other: Outros
+    package: Pacote
+    release: Versão
+    install: Instalação
+    purpose: Para que serve
+    empty: Ainda não há pacotes.