monoholic 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ee37aea1bd4ecf60b33567d582c4363961f49364bd2176f42e8b0de8aaa12ce
-  data.tar.gz: a00389e09ed54a0d268694fc002614cd0eca0820555d6f888d4442d22e353a34
+  metadata.gz: 0b2feef2d72bb935b6e4e6bdb2d5c39034616dadd12f3c6ca9158a43cafe24d8
+  data.tar.gz: 354b3cc49d0afcbcfe40e21f2e0da506310c34b3ee44a06392a397d8e90360a4
 SHA512:
-  metadata.gz: 47a614360018402b6e397fb4e8f6d16cb267919176a479dbb3c6ac58c68d4c605af839e84379fc84eca2ffb36ab77ab77c546521cd5e77cb3366ac1e561fa868
-  data.tar.gz: cd0c4518e8d0e39ddfe00c56a8311c63d375c5ee749313e15be1ad4a29316ec36321fd4219b2900b7475b9287a5e57811e8f2c685a4f3d2fbfeec85a8ffde0be
+  metadata.gz: 3acf3815b503469a52aab55448404d6c2f3869fb636c11831c4d698d962510558b1d6f282f749fe51b8e923c9c29ed9e9ed56705f1ea6d28c5a940f5f3c57a21
+  data.tar.gz: 929ca0d46b670294db583b75f4e633bbe2eabc990cd916b360694159ac357a689bcf3409fffc9f7e06b6d5cbc930e65e1b50010cc4dc6d16642022169eb2091f

data/README.md

@@ -40,26 +40,69 @@ $ 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
   - jekyll-seo-tag
+  - 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 %}`). 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.2.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.2.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
 
@@ -67,6 +110,8 @@ Or, simply fork this repository, adapt the `_config.yml` according to your needs
 
 Once installed, build your site using the provided layouts (`default`, `home`, `page`, `post`).
 
+On pages using the `home` layout, page content appears before the sections defined in `_data/menu.yml`.
+
 ### Configuration
 
 Override the default settings in your `_config.yml`. Key theme configuration options:
@@ -77,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:
@@ -113,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:
@@ -133,9 +208,40 @@ entries:
 
 Nesting can go as deep as needed — `menu.html` includes itself recursively for each `entries` array it encounters.
 
+Top-level titles use `h2`. Each titled parent advances its children by one heading level, capped at `h6`. Entries with missing, empty, or whitespace-only titles are unlabelled groups: they render no heading and do not advance the heading level. Later siblings always retain their own level, regardless of the depth of earlier branches.
+
+Each titled section is labelled by its heading. Heading IDs include the ancestor path and sibling index, so repeated titles remain distinct. When including multiple copies of a menu on the same page, give each copy a distinct `id_prefix` to avoid overlapping IDs:
+
+```liquid
+{% include menu.html collection=site.data.menu.entries level=2 id_prefix='primary' %}
+{% include menu.html collection=site.data.menu.entries level=2 id_prefix='secondary' %}
+```
+
 #### 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:
@@ -143,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
 
@@ -171,6 +287,27 @@ Note: the theme uses `@import` (not `@use`) to stay compatible with GitHub Pages
 
 To override CSS custom properties (colors, spacing, fonts) without touching SCSS, redeclare the variables in your own stylesheet — they are exposed under `:root` in `_sass/_variables.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.
+
+Table captions are used as accessible names when available. Existing author-provided labels, descriptions, and tab indices are preserved. You can translate the default labels and hint in `_config.yml`:
+
+```yaml
+theme_config:
+  table_scroll_label: "Table"
+  code_scroll_label: "Code block"
+  scroll_hint: "Scroll horizontally to see more."
+```
+
+Without JavaScript, tables use fixed-layout, wrapping cells, and code blocks still scroll. For especially wide tables that should scroll even without JavaScript, supply a `.table-scroll` wrapper with `tabindex="0"`, `role="region"`, and an accessible name (`aria-label` or `aria-labelledby`). The enhancement reuses that wrapper rather than nesting another one.
+
 ### Per-Page JavaScript
 
 To load custom JavaScript files on a specific page, add a `custom_js` list to the page's front matter:
@@ -188,6 +325,115 @@ Each entry is a filename (without `.js`) relative to `assets/js/`. The example a
 
 ## Contributing
 
+### Running Tests
+
+```sh
+bundle install
+npm ci
+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.
+
+### Native GitHub Pages Checks
+
+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:
+
+```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
+
+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.
+
+To exercise package checks locally without publishing (publisher verification requires Bash and `sha256sum` from GNU coreutils, matching the Linux CI runner):
+
+```sh
+mkdir -p _tests/.release
+bundle exec gem build monoholic.gemspec --output _tests/.release/monoholic.gem
+bundle exec ruby _tests/package_consumer_test.rb _tests/.release/monoholic.gem
+bundle exec ruby _tests/package_consumer_negative_test.rb _tests/.release/monoholic.gem
+(
+  cd _tests/.release
+  sha256sum monoholic.gem > monoholic.gem.sha256
+)
+bundle exec ruby _tests/package_integrity_test.rb _tests/.release/monoholic.gem _tests/.release/monoholic.gem.sha256
+```
+
+`package_integrity_test.rb` exercises the actual publisher verification recipe with valid, tampered, missing, and malformed inputs, plus a mismatched release tag. It never runs registry publishing commands. Release outputs are ignored by Git, and temporary package installations are removed after the checks finish.
+
 Bug reports and pull requests are welcome on GitHub at [https://github.com/stiermid/monoholic](https://github.com/stiermid/monoholic). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](https://www.contributor-covenant.org/) code of conduct.
 
 ## License

data/_includes/menu.html

@@ -1,21 +1,25 @@
-{%- assign _level = include.level | default: 2 | plus: 0 -%}
-{%- if _level < 2 -%}
-  {%- assign _level = 2 -%}
-{%- elsif _level > 6 -%}
-  {%- assign _level = 6 -%}
-{%- endif -%}
-{%- assign _next_level = _level | plus: 1 -%}
-{%- if _next_level > 6 -%}
-  {%- assign _next_level = 6 -%}
-{%- endif -%}
 {%- for item in include.collection -%}
+  {%- comment -%}
+    Liquid assigns are shared across recursive includes. Recompute each entry
+    from the scoped include parameters before rendering its heading or children.
+  {%- endcomment -%}
+  {%- assign _level = include.level | default: 2 | plus: 0 -%}
+  {%- if _level < 2 -%}
+    {%- assign _level = 2 -%}
+  {%- elsif _level > 6 -%}
+    {%- assign _level = 6 -%}
+  {%- endif -%}
   {%- assign _title_stripped = item.title | strip -%}
   {%- assign _has_title = true -%}
-  {%- if item.title == nil or _title_stripped == empty -%}
+  {%- if item.title == null or _title_stripped == empty -%}
     {%- assign _has_title = false -%}
   {%- endif -%}
+  {%- assign _next_level = _level -%}
+  {%- if _has_title and _level < 6 -%}
+    {%- assign _next_level = _level | plus: 1 -%}
+  {%- endif -%}
   {%- assign _title_slug = item.title | slugify -%}
-  {%- if _title_slug == empty or _title_slug == nil -%}
+  {%- if _title_slug == empty or _title_slug == null -%}
     {%- assign _title_slug = 'section' -%}
   {%- endif -%}
   {%- if include.parent_id -%}
@@ -38,33 +42,40 @@
       | append: forloop.index
     -%}
   {%- endif -%}
-  {%- if _has_title -%}
-    <section aria-labelledby="{{ _heading_id }}">
+  <section
+    {% if _has_title %}
+      aria-labelledby="{{ _heading_id | escape }}"
+    {% endif %}
+  >
+    {%- if _has_title -%}
       {%- if _level == 3 -%}
-        <h3 class="section-title" id="{{ _heading_id }}">
+        <h3 class="section-title" id="{{ _heading_id | escape }}">
           {{ item.title | escape }}
         </h3>
       {%- elsif _level == 4 -%}
-        <h4 class="section-title" id="{{ _heading_id }}">
+        <h4 class="section-title" id="{{ _heading_id | escape }}">
           {{ item.title | escape }}
         </h4>
       {%- elsif _level == 5 -%}
-        <h5 class="section-title" id="{{ _heading_id }}">
+        <h5 class="section-title" id="{{ _heading_id | escape }}">
           {{ item.title | escape }}
         </h5>
       {%- elsif _level >= 6 -%}
-        <h6 class="section-title" id="{{ _heading_id }}">
+        <h6 class="section-title" id="{{ _heading_id | escape }}">
           {{ item.title | escape }}
         </h6>
       {%- else -%}
-        <h2 class="section-title" id="{{ _heading_id }}">
+        <h2 class="section-title" id="{{ _heading_id | escape }}">
           {{ item.title | escape }}
         </h2>
       {%- endif -%}
-  {%- else -%}
-    <section>
-  {%- endif -%}
-    {%- if item.content_file -%}
+    {%- endif -%}
+    {%- 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
@@ -77,7 +88,8 @@
     {%- endif -%}
     {%- if item.post_list -%}{%- include post_list.html -%}{%- endif -%}
     {%- if item.entries -%}
-      {%- include menu.html
+      {%-
+        include menu.html
         collection=item.entries
         level=_next_level
         parent_id=_heading_id

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 -%}
@@ -16,6 +24,14 @@
       {%- include footer.html -%}
     {%- endunless -%}
 
+    <script
+      defer
+      src="{{ '/assets/js/content-scroll.js' | relative_url }}"
+      data-table-label="{{ site.theme_config.table_scroll_label | default: 'Table' | escape }}"
+      data-code-label="{{ site.theme_config.code_scroll_label | default: 'Code block' | escape }}"
+      data-scroll-hint="{{ site.theme_config.scroll_hint | default: 'Scroll horizontally to see more.' | escape }}"
+    ></script>
+
     {% if page.custom_js %}
       {% for js_file in page.custom_js %}
         <script

data/_layouts/home.html

@@ -1,6 +1,12 @@
 ---
 layout: default
 ---
-<nav aria-label="Site sections">
+{{ content }}
+
+{%- 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/_base.scss

@@ -8,6 +8,8 @@ body {
   font-family: var(--font-family);
   font-size: var(--font-size-base);
   line-height: 1.5;
+  // Break unusually long words and URLs only when they cannot fit.
+  overflow-wrap: anywhere;
   min-height: 100vh;
   margin: 0;
   padding: 0;

data/_sass/_content.scss

@@ -4,20 +4,22 @@
   color: var(--bg-color);
 }
 
-div.highlighter-rouge {
-  code {
-    display: block;
-    overflow-x: auto;
-    white-space: pre-wrap;
-  }
+.page-content pre {
+  max-width: 100%;
+  overflow-x: auto;
+  // Keep indentation and source lines intact; scroll the block, not the page.
+  white-space: pre;
+  overflow-wrap: normal;
+}
 
-  pre.highlight {
-    padding: var(--space-md);
-  }
+div.highlighter-rouge pre.highlight {
+  padding: var(--space-md);
 }
 
 table {
   width: 100%;
+  // Readable wrapping is the fallback when scripts are unavailable.
+  table-layout: fixed;
   margin-bottom: var(--space-md);
 
   &,
@@ -29,6 +31,26 @@ table {
   }
 }
 
+.table-scroll {
+  max-width: 100%;
+  overflow-x: auto;
+  margin-bottom: var(--space-md);
+
+  table {
+    // Keep native table layout and semantics inside the scroll container.
+    table-layout: auto;
+    overflow-wrap: normal;
+    margin-bottom: 0;
+  }
+}
+
+.scroll-hint {
+  color: var(--meta-color);
+  font-size: var(--font-size-sm);
+  margin-top: calc(-1 * var(--space-sm));
+  margin-bottom: var(--space-md);
+}
+
 blockquote {
   font-style: italic;
   border: thin solid var(--border-color);

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;

data/assets/js/content-scroll.js

@@ -0,0 +1,109 @@
+(() => {
+  const settings = document.currentScript?.dataset || {};
+  const updates = [];
+  let hintIndex = 0;
+
+  const updateAll = () => updates.forEach((update) => update());
+  const observer =
+    typeof ResizeObserver === "function" ? new ResizeObserver(updateAll) : null;
+  const contentObserver =
+    typeof MutationObserver === "function"
+      ? new MutationObserver(updateAll)
+      : null;
+
+  function enhance(region, content, hintAnchor, label, labelledBy) {
+    // Also respect author-provided wrappers and repeated script inclusion.
+    if (region.hasAttribute("data-scroll-enhanced")) return;
+    region.setAttribute("data-scroll-enhanced", "");
+    const originalAttributes = new Set(region.getAttributeNames());
+    const hint = document.createElement("p");
+    do {
+      hint.id = `monoholic-scroll-hint-${++hintIndex}`;
+    } while (document.getElementById(hint.id));
+    hint.className = "scroll-hint";
+    hint.textContent =
+      settings.scrollHint || "Scroll horizontally to see more.";
+    hint.hidden = true;
+    hintAnchor.after(hint);
+
+    function setAutomaticAttribute(name, value) {
+      if (originalAttributes.has(name)) return;
+      if (value === null) region.removeAttribute(name);
+      else region.setAttribute(name, value);
+    }
+
+    function update() {
+      const overflows = region.scrollWidth > region.clientWidth + 1;
+      hint.hidden = !overflows;
+      setAutomaticAttribute("tabindex", overflows ? "0" : null);
+      setAutomaticAttribute("role", overflows ? "region" : null);
+      if (
+        !originalAttributes.has("aria-label") &&
+        !originalAttributes.has("aria-labelledby")
+      ) {
+        setAutomaticAttribute(
+          labelledBy ? "aria-labelledby" : "aria-label",
+          overflows ? labelledBy || label : null,
+        );
+      }
+
+      // Preserve descriptions supplied by the author or other scripts.
+      const descriptions = new Set(
+        (region.getAttribute("aria-describedby") || "")
+          .split(/\s+/)
+          .filter(Boolean),
+      );
+      if (overflows) descriptions.add(hint.id);
+      else descriptions.delete(hint.id);
+      if (descriptions.size) {
+        region.setAttribute("aria-describedby", [...descriptions].join(" "));
+      } else {
+        region.removeAttribute("aria-describedby");
+      }
+    }
+
+    updates.push(update);
+    update();
+    observer?.observe(region);
+    if (content !== region) observer?.observe(content);
+    contentObserver?.observe(content, {
+      childList: true,
+      characterData: true,
+      subtree: true,
+    });
+  }
+
+  document.querySelectorAll(".page-content table").forEach((table) => {
+    let wrapper = table.parentElement;
+    if (!wrapper.classList.contains("table-scroll")) {
+      wrapper = document.createElement("div");
+      wrapper.className = "table-scroll";
+      table.before(wrapper);
+      wrapper.append(table);
+    }
+    const label =
+      table.getAttribute("aria-label") ||
+      table.caption?.textContent.trim() ||
+      settings.tableLabel ||
+      "Table";
+    enhance(
+      wrapper,
+      table,
+      wrapper,
+      label,
+      table.getAttribute("aria-labelledby"),
+    );
+  });
+
+  document.querySelectorAll(".page-content pre").forEach((block) => {
+    const hintAnchor = block.closest("div.highlighter-rouge") || block;
+    enhance(block, block, hintAnchor, settings.codeLabel || "Code block");
+  });
+
+  window.addEventListener("resize", updateAll);
+  // A font swap can change overflow without resizing the container itself.
+  if (document.fonts) {
+    document.fonts.ready.then(updateAll);
+    document.fonts.addEventListener("loadingdone", updateAll);
+  }
+})();

data/robots.txt

@@ -0,0 +1,8 @@
+---
+layout: null
+sitemap: false
+---
+User-agent: *
+Allow: /
+
+Sitemap: {{ site.url }}{{ site.baseurl }}/sitemap.xml

metadata

@@ -1,15 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: monoholic
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Agil Mammadov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-16 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
@@ -66,6 +86,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: jekyll-sitemap
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
 description:
 email:
 - mammadovagil@proton.me
@@ -96,6 +130,8 @@ files:
 - assets/favicon.ico
 - assets/favicon.svg
 - assets/js/.keep
+- assets/js/content-scroll.js
+- robots.txt
 homepage: https://github.com/stiermid/monoholic
 licenses:
 - GPL-3.0-only