monoholic 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ee37aea1bd4ecf60b33567d582c4363961f49364bd2176f42e8b0de8aaa12ce
-  data.tar.gz: a00389e09ed54a0d268694fc002614cd0eca0820555d6f888d4442d22e353a34
+  metadata.gz: 944d762c5b588ea620fe59093575adf3fe51488e84a04cbb31dd5b34619d9aed
+  data.tar.gz: 1ba6737b6d4e3b1e6e207f4cebadb2b51ea7f8608ff89cb139e89d1de8c25561
 SHA512:
-  metadata.gz: 47a614360018402b6e397fb4e8f6d16cb267919176a479dbb3c6ac58c68d4c605af839e84379fc84eca2ffb36ab77ab77c546521cd5e77cb3366ac1e561fa868
-  data.tar.gz: cd0c4518e8d0e39ddfe00c56a8311c63d375c5ee749313e15be1ad4a29316ec36321fd4219b2900b7475b9287a5e57811e8f2c685a4f3d2fbfeec85a8ffde0be
+  metadata.gz: 2051528bae7940745198bb450bf329d07f0e203230e05226735625a8da40d6b73bf726a58452f3d016fdefb4a052bd2d38e61655d07c828ec7d5c2adedef313a
+  data.tar.gz: 650a541107d5966c16485b3c483654ab3c5f9fa3ca7897401d92f00b423d8eadd4722107b8c97844bbf389879af30966c58a9649d625dc4dc082d52c5a3c3237

data/README.md

@@ -48,16 +48,17 @@ 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`.
+`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`.
 
 > **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.
 
 | 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                  |
+| GitHub Pages (`remote_theme: stiermid/monoholic@v1.3.0`) | 3.9 via Pages | Pages only                  |
 
 Or, simply fork this repository, adapt the `_config.yml` according to your needs, and you're good to go!
 
@@ -67,6 +68,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:
@@ -133,6 +136,15 @@ 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:
@@ -171,6 +183,23 @@ 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
+
+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 +217,52 @@ 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/menu_layout_test.rb
+JEKYLL_SAFE=1 bundle exec ruby _tests/menu_layout_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.
+
+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.
+
+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
+
+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.
+
+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.
+
+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.
+
+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,32 +42,34 @@
       | 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 -%}
+    {%- endif -%}
     {%- if item.content_file -%}
       {%- assign _menu_page = site.pages
         | where: 'path', item.content_file
@@ -77,7 +83,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

@@ -16,6 +16,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,8 @@
 ---
 layout: default
 ---
+{{ content }}
+
 <nav aria-label="Site sections">
   {%- 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/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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: monoholic
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Agil Mammadov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-16 00:00:00.000000000 Z
+date: 2026-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -66,6 +66,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 +110,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