monoholic 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 944d762c5b588ea620fe59093575adf3fe51488e84a04cbb31dd5b34619d9aed
-  data.tar.gz: 1ba6737b6d4e3b1e6e207f4cebadb2b51ea7f8608ff89cb139e89d1de8c25561
+  metadata.gz: 0b2feef2d72bb935b6e4e6bdb2d5c39034616dadd12f3c6ca9158a43cafe24d8
+  data.tar.gz: 354b3cc49d0afcbcfe40e21f2e0da506310c34b3ee44a06392a397d8e90360a4
 SHA512:
-  metadata.gz: 2051528bae7940745198bb450bf329d07f0e203230e05226735625a8da40d6b73bf726a58452f3d016fdefb4a052bd2d38e61655d07c828ec7d5c2adedef313a
-  data.tar.gz: 650a541107d5966c16485b3c483654ab3c5f9fa3ca7897401d92f00b423d8eadd4722107b8c97844bbf389879af30966c58a9649d625dc4dc082d52c5a3c3237
+  metadata.gz: 3acf3815b503469a52aab55448404d6c2f3869fb636c11831c4d698d962510558b1d6f282f749fe51b8e923c9c29ed9e9ed56705f1ea6d28c5a940f5f3c57a21
+  data.tar.gz: 929ca0d46b670294db583b75f4e633bbe2eabc990cd916b360694159ac357a689bcf3409fffc9f7e06b6d5cbc930e65e1b50010cc4dc6d16642022169eb2091f

data/README.md

@@ -40,10 +40,14 @@ $ bundle install
 
 ### Manual Installation (GitHub Pages)
 
-If you're running Jekyll without RubyGems or prefer to use GitHub Pages remote themes, update your `_config.yml`:
+For GitHub's built-in Jekyll build, add the following to `_config.yml`:
 
 ```yaml
-remote_theme: stiermid/monoholic
+title: "Your site"
+description: "A short description of your site."
+remote_theme: stiermid/monoholic@v1.4.0
+url: "https://<user>.github.io"
+baseurl: "/your-repo"
 plugins:
   - jekyll-remote-theme
   - jekyll-feed
@@ -51,16 +55,54 @@ plugins:
   - jekyll-sitemap
 ```
 
-`jekyll-remote-theme` fetches the theme on Pages; `jekyll-feed` and `jekyll-seo-tag` are required by the theme's `head.html` (`{% feed_meta %}`, `{% seo %}`), and `jekyll-sitemap` generates `sitemap.xml` referenced by the theme's `robots.txt`. For project sites, also set `baseurl` (e.g. `/your-repo`) and `url` (e.g. `https://<user>.github.io`). To pin a release: `remote_theme: stiermid/monoholic@v1.3.0`.
+Replace the user and repository placeholders. Use `baseurl: ""` for a user
+site or a custom domain served at its root. Pinning a release keeps theme
+updates explicit; omit `@v1.4.0` only if you want the repository's default
+branch instead.
 
-> **Pages note:** Native GitHub Pages builds run Jekyll 3.9. The `monoholic` RubyGem requires Jekyll 4.4, so on GitHub Pages use `remote_theme` only (not `theme:` + `gem "monoholic"`). SCSS intentionally uses `@import` for 3.9 compatibility.
+`jekyll-remote-theme` loads the theme. Feed and SEO tags require
+`jekyll-feed` and `jekyll-seo-tag`; `jekyll-sitemap` generates the sitemap
+and a default `robots.txt` when the site does not supply one.
 
-| Install method                                           | Jekyll        | How                         |
-| -------------------------------------------------------- | ------------- | --------------------------- |
-| RubyGems (`theme: monoholic`)                            | 4.4           | local / CI / non-Pages host |
-| GitHub Pages (`remote_theme: stiermid/monoholic@v1.3.0`) | 3.9 via Pages | Pages only                  |
+Create a homepage, such as `index.md`:
 
-Or, simply fork this repository, adapt the `_config.yml` according to your needs, and you're good to go!
+```markdown
+---
+layout: home
+---
+
+Welcome to my site.
+```
+
+Also create `_data/menu.yml` in your site:
+
+```yaml
+entries:
+  - title: all posts
+    post_list: true
+```
+
+Native Jekyll 3.10 does not inherit a remote theme's `_data` directory, so
+your site must supply its own menu. Add your posts under `_posts/` and
+extend the menu using the options below.
+
+> **Pages note:** Native Pages currently uses Jekyll 3.10.0 and Sass converter
+> 1.5.2 with Ruby Sass. The `monoholic` gem requires Jekyll 4.4, so do not
+> combine it with the native Pages bundle. Use `remote_theme` instead of
+> `theme: monoholic` for that build. SCSS retains `@import` for this older
+> Sass compiler.
+
+| Method       | Jekyll | Build               |
+| ------------ | ------ | ------------------- |
+| RubyGem      | 4.4    | Local / custom CI   |
+| Remote theme | 3.10   | Native GitHub Pages |
+
+You can still deploy a Jekyll 4.4 gem-based site to Pages as static output
+from a custom build workflow. The version restriction applies to GitHub's
+built-in Jekyll build, not to static hosting.
+
+For a full source checkout instead, fork this repository and adapt
+`_config.yml` to your site.
 
 ## Usage
 
@@ -80,8 +122,35 @@ theme_config:
   date_format: "%Y-%m-%d" # Date format for post metadata
   monochrome_images: true # Apply grayscale filter to images (default: true)
   footer: true # Show/hide site footer (default: true)
+  skip_link_label: "Skip to content" # Keyboard skip-link text
+  site_sections_label: "Site sections" # Accessible name of the homepage navigation
 ```
 
+### Language and Interface Labels
+
+The document's `<html lang>` uses the page's `lang` front matter, then the site's `lang` setting, then `en`. Use BCP 47 language tags such as `de`, `en-GB`, or `zh-Hant-TW`. Surrounding whitespace is trimmed; missing, empty, whitespace-only, or `false` values fall back to the next setting.
+
+For example, configure a German site in `_config.yml`:
+
+```yaml
+lang: de
+theme_config:
+  skip_link_label: "Zum Inhalt"
+  site_sections_label: "Seitenbereiche"
+  back: "Zurück"
+```
+
+Override the document language for an individual page or post in its front matter:
+
+```yaml
+---
+layout: page
+lang: fr-CA
+---
+```
+
+Declaring `lang` helps browsers and assistive technology interpret your content; it does not translate the content or interface automatically. Interface labels above are site-wide and rendered as plain text, not HTML. Missing or blank labels retain their English defaults so the skip link and navigation keep accessible names. Existing scroll labels and hints can also be translated under [Responsive Content](#responsive-content).
+
 ### Fediverse Creator tag
 
 Monoholic supports `fediverse:creator` meta tag:
@@ -116,9 +185,12 @@ entries:
 
 - `title`: The section header.
 - `content`: Custom HTML or text for the menu section.
-- `content_file`: Path to an external markdown file (e.g., `about.md`) to load content from your root directory.
+- `content_include`: Path relative to `_includes/` for a Markdown fragment with Liquid support (recommended for reusable content).
+- `content_file`: Path to an existing Jekyll page (e.g., `about.md`) relative to your site root. Retained for compatibility; does not reliably evaluate Liquid.
 - `post_list`: Set to `true` to auto-generate a list of your Jekyll posts under this section.
 
+Use one content source per entry. If several are supplied, precedence is `content_include`, then `content_file`, then `content`.
+
 #### Nested Menu Sections
 
 Menu entries can contain nested `entries` to create recursive sub-sections:
@@ -147,7 +219,29 @@ Each titled section is labelled by its heading. Heading IDs include the ancestor
 
 #### Using External Content Files
 
-You can reference external markdown files instead of inline content:
+For reusable content containing Liquid, create a Markdown fragment in your site's `_includes/` directory, for example `_includes/fragments/about.md`:
+
+```liquid
+Welcome to **{{ site.title }}**.
+
+[Home]({{ '/' | relative_url }})
+```
+
+Reference it using `content_include`:
+
+```yaml
+entries:
+  - title: about
+    content_include: fragments/about.md
+```
+
+Jekyll renders Liquid first, then Monoholic converts the resulting Markdown to HTML once. Standard Liquid variables, filters, tags, and nested includes work without a custom plugin, including in safe mode. `page` refers to the page displaying the menu, not the fragment. Use `relative_url` for links that must work on project sites such as `/blog`.
+
+Fragments must **not** have YAML front matter. They do not generate standalone pages. Paths are relative to `_includes/`, even when the menu appears on a nested page; missing files and invalid paths fail the build with Jekyll's include error rather than silently omitting content. Only include trusted, author-controlled files.
+
+##### Existing `content_file` references
+
+Existing page references remain supported:
 
 ```yaml
 entries:
@@ -155,7 +249,17 @@ entries:
     content_file: about.md
 ```
 
-This will load and render the content from `about.md` in your site's root directory.
+The referenced file must be a Jekyll page with YAML front matter (an empty `---` block is sufficient) and must not be excluded from the build. Its Markdown content is embedded without its layout; the page can also generate its own standalone URL. Missing page references are silently omitted, preserving existing behavior.
+
+`content_file` does not run a separate Liquid rendering pass. Results for Liquid expressions can depend on page rendering order, so use `content_include` whenever the content contains Liquid.
+
+To migrate, move reusable content from `about.md` to `_includes/fragments/about.md`, remove its YAML front matter, and replace `content_file: about.md` with `content_include: fragments/about.md`. If you still need a standalone About page, keep `about.md` with its front matter and include the fragment in its body:
+
+```liquid
+{% include fragments/about.md %}
+```
+
+Use a Markdown page for this wrapper so Jekyll converts the included Markdown normally. Remove an old standalone page only if you no longer need its URL.
 
 ### Favicon
 
@@ -185,6 +289,10 @@ To override CSS custom properties (colors, spacing, fonts) without touching SCSS
 
 ### Responsive Content
 
+Body text defaults to `1rem`, following the browser's default font size
+instead of fixing it at 16 pixels. When overriding `--font-size-base`, use
+a relative value such as `1rem` or `1.125rem` to preserve that preference.
+
 Long words, URLs, and inline code wrap when necessary. Plain and highlighted code blocks preserve indentation and source lines, scrolling horizontally inside the block instead of expanding the page.
 
 The small, dependency-free `assets/js/content-scroll.js` script progressively enhances tables with scroll containers while preserving native table semantics. Overflowing tables and code blocks receive a keyboard tab stop, an accessible name, and a visible scrolling hint. These are updated when the viewport, content dimensions, or fonts change; fitting content does not add automatic tab stops.
@@ -226,24 +334,87 @@ npx playwright install --with-deps chromium firefox webkit
 bundle exec ruby _tests/release_workflow_test.rb
 bundle exec ruby _tests/release_tag_test.rb
 bundle exec ruby _tests/home_layout_test.rb
+bundle exec ruby _tests/localization_test.rb
+JEKYLL_SAFE=1 bundle exec ruby _tests/localization_test.rb
 bundle exec ruby _tests/menu_layout_test.rb
 JEKYLL_SAFE=1 bundle exec ruby _tests/menu_layout_test.rb
+bundle exec ruby _tests/menu_content_test.rb
+JEKYLL_SAFE=1 bundle exec ruby _tests/menu_content_test.rb
 npm run test:browser
 ```
 
 Browser tests build and serve an isolated fixture site. They cover Chromium, Firefox, and WebKit at 320px, 375px, 768px, and 1280px, including long text, plain and highlighted code, Markdown and HTML tables, keyboard scrolling, resizing, and JavaScript-disabled layouts. External fonts are blocked so the tests do not depend on Google Fonts being available.
 
+Text-sizing checks enlarge the root font to 200% at each viewport width,
+with and without JavaScript. A Firefox-specific test also changes the
+actual browser default-font preference to 32 pixels. These are focused
+regression checks, not a complete WCAG conformance audit.
+
 Menu rendering checks cover branching recursion, deep nesting, untitled groups, repeated titles, unique IDs, escaped labels, and independent menu instances in normal and Jekyll safe mode. Browser tests also verify native heading and section semantics with JavaScript disabled.
 
+Menu content checks build root and `/blog` sites in normal and safe mode. They cover Liquid-before-Markdown rendering, nested includes and host pages, recursive sections, literal Liquid examples, legacy content sources, and invalid include paths.
+
+Localization checks cover language inheritance across all four layouts, page overrides, blank-value fallbacks, escaped attributes, translated labels, and unchanged skip-link destinations in normal and safe mode.
+
 To run one browser, use `npm run test:browser -- --project=chromium`. You can also set `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` to use a locally installed Chromium binary. Generated sites, screenshots, and traces are ignored by Git; CI retains failure diagnostics for seven days.
 
-### Release Validation
+### Native GitHub Pages Checks
 
-Both pull requests and release-tag pushes run the build and test checks. Publishing depends on all checks succeeding and is restricted to pushed `v*` tags; pull requests never publish. The tag must be `v` followed by the exact gem version in `monoholic.gemspec`, including any RubyGems prerelease suffix. Update the version metadata and lockfiles together before tagging.
+The Pages tests use a separate Gemfile and lockfile so the theme's Jekyll 4.4
+dependency cannot affect the native Pages graph. CI runs them on Ruby 3.3.
+Install and run them with:
 
-CI builds the gem once and installs it into a temporary gem home. A clean consumer site uses that installed package with the existing lockfile dependencies, without downloading gems or falling back to repository theme files. The checks build root and `/blog` sites and verify layouts, compiled CSS, scripts, favicons, feeds, and URLs. Negative tests reject broken packages and invalid versions.
+```sh
+BUNDLE_GEMFILE=_tests/pages/Gemfile bundle install
+BUNDLE_GEMFILE=_tests/pages/Gemfile bundle exec \
+  ruby _tests/pages/consumer_test.rb
+```
+
+This bundle pins GitHub Pages 232, Jekyll 3.10.0, Sass converter 1.5.2, and
+the other published Pages dependencies. The test invokes the real Pages
+build command with its safe-mode configuration and default plugins. It
+checks root and `/blog` sites, layouts, menu data, nested Liquid includes,
+recursive headings, language settings, compiled CSS, scripts, favicons,
+feeds, sitemap URLs, and rejection of a broken theme archive.
+
+Only the theme-download HTTP response is supplied locally, using a ZIP of
+the checkout. The real `jekyll-remote-theme` plugin downloads, extracts, and
+loads it. No live GitHub requests or installed `monoholic` gem are used.
+The generated lockfile retains Bundler's checksum format.
+
+Review the [published dependency matrix](https://pages.github.com/versions/)
+when updating this bundle. Update its Gemfile, lockfile, and expected versions
+in `_tests/pages/consumer_test.rb` together.
+
+### Release Validation
 
-After validation, tag runs upload the gem and its SHA-256 manifest as a seven-day artifact. The publishing job downloads those same bytes, verifies the checksum and package name/version, and pushes the same gem to GitHub Packages and RubyGems—without checking out or rebuilding the source. Rerunning validation replaces the artifact only after checks succeed; if it has expired, rerun validation rather than just the publishing job.
+Pull requests and release-tag pushes run gem checks on Ruby 3.3 and 3.4,
+plus the separate native Pages check on Ruby 3.3. Publishing requires all
+three jobs to succeed and is restricted to pushed `v*` tags; pull requests
+never publish. The tag must be `v` followed by the exact gem version in
+`monoholic.gemspec`, including any RubyGems prerelease suffix. Update the
+version metadata and lockfiles together before tagging.
+
+Each gem-validation job builds the gem once and installs it into a temporary
+gem home. A clean consumer's Gemfile declares only `monoholic`; Bundler resolves
+its runtime dependencies from installed gems without downloading gems or
+falling back to repository theme files. The checks run
+`bundle exec jekyll build` for root and `/blog` sites and verify layouts,
+compiled CSS, scripts, favicons, feeds, and URLs. Negative tests reject broken
+packages and invalid versions. ERB must be declared as a runtime dependency,
+even on hosts that provide it as a default gem; this is checked on both Rubies.
+
+Consumer builds use resolved Ruby and gem executable paths, with no Jekyll
+wrapper available on `PATH`. This also covers vendored CI installations
+without relying on globally installed gem executables.
+
+After validation, the Ruby 3.3 gem job uploads its gem and SHA-256 manifest
+as a seven-day artifact; the other jobs do not upload a competing release
+artifact. Once both gem jobs and native Pages pass, publishing downloads
+those same bytes, verifies the checksum and package name/version, and pushes
+the same gem to GitHub Packages and RubyGems—without checking out or rebuilding
+the source. Rerunning validation replaces the artifact only after checks
+succeed; if it has expired, rerun validation rather than just publishing.
 
 Publishing keeps the existing authentication: `GITHUB_TOKEN` with package-write permission for GitHub Packages, and the repository's `RUBYGEMS_API_KEY` secret for RubyGems. Validation has read-only repository permissions; registry credentials are used only by publishing steps.
 

data/_includes/menu.html

@@ -70,7 +70,12 @@
         </h2>
       {%- endif -%}
     {%- endif -%}
-    {%- if item.content_file -%}
+    {%- if item.content_include -%}
+      {%- capture _menu_content -%}
+        {%- include {{ item.content_include }} -%}
+      {%- endcapture -%}
+      {{ _menu_content | markdownify }}
+    {%- elsif item.content_file -%}
       {%- assign _menu_page = site.pages
         | where: 'path', item.content_file
         | first

data/_layouts/default.html

@@ -1,8 +1,16 @@
+{%- assign _page_lang = page.lang | default: '' | strip -%}
+{%- assign _site_lang = site.lang | default: '' | strip -%}
+{%- assign _skip_link_label = site.theme_config.skip_link_label
+  | default: ''
+  | strip
+-%}
 <!doctype html>
-<html lang="{{ page.lang | default: "en" }}">
+<html lang="{{ _page_lang | default: _site_lang | default: 'en' | escape }}">
   {%- include head.html -%}
   <body class="{% if site.theme_config.monochrome_images != false %}images-monochrome{% endif %}">
-    <a class="skip-link" href="#main">Skip to content</a>
+    <a class="skip-link" href="#main">
+      {{- _skip_link_label | default: 'Skip to content' | escape -}}
+    </a>
     <div class="wrapper">
       {%- unless page.layout == 'post' -%}
         {%- include header.html -%}

data/_layouts/home.html

@@ -3,6 +3,10 @@ layout: default
 ---
 {{ content }}
 
-<nav aria-label="Site sections">
+{%- assign _site_sections_label = site.theme_config.site_sections_label
+  | default: ''
+  | strip
+-%}
+<nav aria-label="{{ _site_sections_label | default: 'Site sections' | escape }}">
   {%- include menu.html collection=site.data.menu.entries level=2 -%}
 </nav>

data/_sass/_variables.scss

@@ -7,7 +7,7 @@
 
   // Typography
   --font-family: "JetBrains Mono", monospace;
-  --font-size-base: 16px;
+  --font-size-base: 1rem;
   --font-size-sm: 0.85rem;
   --font-size-section: 1.1rem;
   --font-size-site-title: 2rem;

metadata

@@ -1,15 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: monoholic
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Agil Mammadov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-15 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: erb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: jekyll
   requirement: !ruby/object:Gem::Requirement