markdowndocs 0.10.0 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ca89d7b3d1decf28b07cfaccfd1e2e0e0924f8ef7d56d1374e3cb600cbd4933
-  data.tar.gz: 036b99af3190b230d1ceb327171300758b76d09392a4d28b32a9a0129b9cdaf3
+  metadata.gz: eb123f5ef96df8917be85966728453e124ae2f418acb7458a583c3d42254b068
+  data.tar.gz: e672f4cf03ee6a4fbb37a5cd2d924be8fb903256de7834adf36bfcf4e8877541
 SHA512:
-  metadata.gz: 80f8fb1ad69d4e83407943a1655a7da909d3704ce950ccb3e01a01a515aa3b7a96804e3ae93ceea7ed2cace9497267d750010a2c6fd05b56db27abc89f597432
-  data.tar.gz: 7b7a5ba65d0e5e549811734b03aed0bcc5d52b0c13b768f5e06599162b367998f7d4f7294fe7af2a37d82924ce1826e7e65fbfa39b616bf97828f6b68f83fe2a
+  metadata.gz: 7a7f53ed3821883f3f858b50039a1ca03ba4bbfafdbf9302dedfb9a0c150ab1f25e198c3ca602e13cec493a469135bdc5b0fb28b9157182e1278409136928171
+  data.tar.gz: 15f9aa8cda587f9239ec84290d2fb1e3f3d6cf28c9b208b33d6081af842a5ce15eb5dcfa2a131905f41a228a03d19ea1dacd97fb3e80d35aa4a79f722cf4795a

data/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.11.1] - 2026-07-13
+
+### Accessibility (follow-up review)
+
+- **Caption-less tables get a numbered, localized accessible name.** v0.11.0
+  labelled every un-captioned table the hardcoded English `"Table"`, so a
+  page of tables was undifferentiated to a screen reader and unlocalized.
+  They are now `"Table 1"`, `"Table 2"`, … via the new
+  `markdowndocs.table_label` I18n key (`"Table %{number}"`).
+
+## [0.11.0] - 2026-07-13
+
+### Accessibility
+
+- **Keyboard-scrollable tables (WCAG 2.1.1).** A wide GFM table overflows and
+  becomes horizontally scrollable via the host's typography CSS. The renderer
+  now marks every `<table>` with `tabindex="0"` so keyboard-only users can
+  scroll it with the arrow keys (axe `scrollable-region-focusable`). The
+  table's implicit `role="table"` is preserved — no `role="region"` is added,
+  which would strip row/column semantics — and an un-captioned table gets a
+  minimal `aria-label="Table"` so the focus stop is announced. `tabindex` is
+  now in the sanitizer's base attribute allow-list.
+- **44px chrome target sizes (WCAG 2.5.5 AAA).** Sidebar table-of-contents
+  links, related-documentation links, breadcrumb links, and the audience
+  mode-switcher buttons now meet the 44×44 minimum target size (they measured
+  ~20–28px). Purely additive utility classes; no visual change beyond the
+  taller hit area.
+
 ## [0.10.0] - 2026-06-24
 
 ### Added

data/app/services/markdowndocs/markdown_renderer.rb

@@ -48,7 +48,7 @@ module Markdowndocs
         options = markdown_render_options
         doc = Commonmarker.parse(markdown, options: options)
         html = doc.to_html(options: options)
-        html = apply_syntax_highlighting(html)
+        html = post_process_html(html)
         sanitize_html(html)
       rescue => e
         # Bare rescue is intentional: third-party errors from commonmarker,
@@ -66,7 +66,7 @@ module Markdowndocs
         %(<pre class="markdowndocs-render-error">#{escaped}</pre>)
       end
 
-      def apply_syntax_highlighting(html)
+      def post_process_html(html)
         # HTML5 parsing preserves case-sensitive SVG/MathML foreign-content
         # attributes (e.g. viewBox) that Nokogiri::HTML would lowercase.
         doc = Nokogiri::HTML5.fragment(html)
@@ -84,9 +84,44 @@ module Markdowndocs
           end
         end
 
+        mark_tables_keyboard_accessible(doc)
+
         doc.to_html
       end
 
+      # A wide GFM table overflows its column and becomes horizontally
+      # scrollable — via the host's typography/prose CSS, which the engine
+      # does not control and cannot inspect at render time. A scrollable
+      # region that isn't keyboard-focusable strands keyboard-only users
+      # (WCAG 2.1.1; axe `scrollable-region-focusable`).
+      #
+      # `tabindex="0"` directly on the <table> makes it focusable so a
+      # keyboard user can scroll it with the arrow keys, whether the host CSS
+      # scrolls the table itself or a wrapper. We deliberately do NOT add
+      # `role="region"`: on a <table> that would override the implicit
+      # `role="table"` and strip row/column semantics from screen readers.
+      # A <caption> already names the table for AT; when absent we add a
+      # minimal aria-label so the focus stop is announced. The focus ring is
+      # the user-agent default (no engine CSS suppresses it).
+      #
+      # Trade-off: every table becomes a tab stop, not only the ones that
+      # actually overflow — scroll state is unknowable without a browser, and
+      # a static (JS-free) engine fix is worth that small amount of extra tab
+      # travel.
+      def mark_tables_keyboard_accessible(doc)
+        doc.css("table").each_with_index do |table, index|
+          table["tabindex"] = "0"
+          next if table.at_css("caption") || table["aria-label"]
+
+          # A caption-less table still needs an accessible name for its focus
+          # stop — but a page of identically-named "Table" regions is
+          # undifferentiated to a screen reader tabbing through. Number them,
+          # and route the label through I18n so non-English docs localize it.
+          table["aria-label"] = I18n.t("markdowndocs.table_label", number: index + 1,
+            default: "Table %{number}")
+        end
+      end
+
       def lexer_exists?(language)
         Rouge::Lexer.find(language).present?
       rescue
@@ -131,6 +166,7 @@ module Markdowndocs
         href title src alt align class lang
         role aria-label aria-labelledby aria-describedby aria-hidden
         open
+        tabindex
       ].freeze
 
       # Curated structural SVG subset. Deliberately excludes script,
@@ -159,7 +195,7 @@ module Markdowndocs
         transform opacity text-anchor dominant-baseline
         font-size font-family font-weight
         marker-start marker-end markerWidth markerHeight refX refY orient
-        id xmlns focusable tabindex
+        id xmlns focusable
       ].freeze
 
       def sanitize_html(html)

data/app/views/markdowndocs/docs/_breadcrumb.html.erb

@@ -19,7 +19,8 @@
         <% if item[:current] %>
           <span class="font-medium text-gray-900 dark:text-slate-100" aria-current="page"><%= item[:name] %></span>
         <% elsif item[:path] %>
-          <%= link_to item[:name], item[:path], class: "hover:text-indigo-700 dark:hover:text-indigo-300 transition-colors" %>
+<%# inline-flex min-h-11 (44px) meets WCAG 2.5.5 AAA target size. %>
+          <%= link_to item[:name], item[:path], class: "hover:text-indigo-700 dark:hover:text-indigo-300 transition-colors inline-flex min-h-11 items-center" %>
         <% else %>
           <span class="text-gray-700 dark:text-slate-300"><%= item[:name] %></span>
         <% end %>

data/app/views/markdowndocs/docs/_mode_switcher.html.erb

@@ -21,7 +21,9 @@
           aria-pressed="<%= current_mode == mode %>"
           data-mode="<%= mode %>"
           data-action="click->docs-mode#rememberFocus"
-          class="px-3 py-1.5 text-sm font-medium rounded-md border transition-colors <%= (current_mode == mode) ? 'border-cyan-500 bg-cyan-50 text-cyan-900 dark:bg-cyan-900/40 dark:border-cyan-400 dark:text-cyan-100' : 'border-slate-200 text-slate-700 hover:bg-slate-50 dark:border-slate-700 dark:text-slate-300 dark:hover:bg-slate-700' %>"
+<%# inline-flex min-h-11 (44px) meets WCAG 2.5.5 AAA target size — the
+              toggle buttons measured ~28px tall. %>
+          class="inline-flex min-h-11 items-center justify-center px-3 py-1.5 text-sm font-medium rounded-md border transition-colors <%= (current_mode == mode) ? 'border-cyan-500 bg-cyan-50 text-cyan-900 dark:bg-cyan-900/40 dark:border-cyan-400 dark:text-cyan-100' : 'border-slate-200 text-slate-700 hover:bg-slate-50 dark:border-slate-700 dark:text-slate-300 dark:hover:bg-slate-700' %>"
         >
           <%= t("markdowndocs.modes.#{mode}", default: mode.titleize) %>
         </button>

data/app/views/markdowndocs/docs/_navigation.html.erb

@@ -7,7 +7,10 @@
         <ul class="space-y-2">
           <% toc_items.each do |item| %>
             <li class="<%= 'ml-4' if item[:level] == 3 %>">
-              <a href="#<%= item[:slug] %>" class="text-sm text-gray-700 dark:text-slate-300 hover:text-indigo-700 dark:hover:text-indigo-300 transition-colors block py-1">
+<%# min-h-11 (44px) meets WCAG 2.5.5 AAA target size — sidebar TOC links
+                  measured ~20px. flex + items-center keeps the label vertically
+                  centered in the taller hit area. %>
+              <a href="#<%= item[:slug] %>" class="text-sm text-gray-700 dark:text-slate-300 hover:text-indigo-700 dark:hover:text-indigo-300 transition-colors flex min-h-11 items-center">
                 <%= item[:text] %>
               </a>
             </li>
@@ -23,7 +26,8 @@
       <ul class="space-y-3">
         <% related_docs.each do |related_doc| %>
           <li>
-            <%= link_to related_doc.title, markdowndocs.doc_path(related_doc.slug), class: "text-sm text-indigo-700 dark:text-indigo-300 hover:text-indigo-800 dark:hover:text-indigo-200 font-medium transition-colors" %>
+<%# inline-flex min-h-11 (44px) meets WCAG 2.5.5 AAA target size. %>
+            <%= link_to related_doc.title, markdowndocs.doc_path(related_doc.slug), class: "text-sm text-indigo-700 dark:text-indigo-300 hover:text-indigo-800 dark:hover:text-indigo-200 font-medium transition-colors inline-flex min-h-11 items-center" %>
             <p class="text-xs text-gray-700 dark:text-slate-300 mt-1"><%= related_doc.description %></p>
           </li>
         <% end %>

data/config/locales/en.yml

@@ -1,6 +1,7 @@
 en:
   markdowndocs:
     back_to_documentation: "Back to Documentation"
+    table_label: "Table %{number}"
     navigation_sidebar: "Navigation & Related Docs"
     viewing_mode: "Viewing Mode"
     select_viewing_mode: "Select documentation viewing mode"

data/lib/markdowndocs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Markdowndocs
-  VERSION = "0.10.0"
+  VERSION = "0.11.1"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: markdowndocs
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.1
 platform: ruby
 authors:
 - Dave Chmura
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -115,7 +114,6 @@ metadata:
   homepage_uri: https://github.com/dschmura/markdowndocs
   source_code_uri: https://github.com/dschmura/markdowndocs
   changelog_uri: https://github.com/dschmura/markdowndocs/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -130,8 +128,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A drop-in markdown documentation site for Rails apps
 test_files: []