jekyll-theme-modootoday 1.0.0

data/lib/modootoday/check/page_syntax.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # Rules 0-1: front matter present, fence info strings, alerts, forbidden syntax, section headings.
+    module PageSyntax
+      KNOWN = %w[NOTE TIP IMPORTANT WARNING CAUTION].freeze
+      NESTED_ALERT = "alert nested in list/table/quote (GitHub renders only top-level alerts; this shows as a plain quote); start '> [!TYPE]' at column 0"
+
+      module_function
+
+      # Returns the number of top-level '## ' headings (used by the sections: rule).
+      def call(ctx, f, text, b, code)
+        front_matter(ctx, f, text)
+        fences(ctx, f, b)
+        alerts(ctx, f, code.lines)
+        html_free = Markdown.strip_comments(code)
+        forbidden(ctx, f, code, html_free)
+        headings(ctx, f, html_free)
+      end
+
+      # 0. every content page needs front matter (may be empty "---\n---"); without it,
+      #    GitHub Pages (jekyll-optional-front-matter) renders the page AND copies the raw .md to _site.
+      def front_matter(ctx, f, text)
+        ctx.errs << "#{ctx.rel(f)}: missing front matter (add an empty '---' / '---' block at the top)" unless (text.start_with?("---\n") && text =~ Markdown::FM) || ctx.source_mode?
+      end
+
+      # 1a. code fence info string: one language word only (kramdown 2.4 turns "sh {x}" into inline code)
+      def fences(ctx, f, b)
+        Markdown.strip_fences(b) do |n, info|
+          next if info.empty? || info.match?(/\A[\w#+.-]+\z/)
+          ctx.errs << "#{ctx.rel(f)}:#{n}: code fence info string must be a single language word (got #{info.inspect}); attributes like {title=…} break kramdown"
+        end
+      end
+
+      # 1b. alerts (GitHub extension): case-insensitive markers, registered types only
+      def alerts(ctx, f, lines)
+        errs, r = ctx.errs, ctx.rel(f)
+        lines.each_with_index do |l, i|
+          n = i + 1
+          errs << "#{r}:#{n}: tab after '>' (kramdown reads it as an indented code block); use a space" if l =~ /^ {0,3}>\t/
+          errs << "#{r}:#{n}: formatted alert marker (e.g. **[!NOTE]**) is not an alert anywhere; write > [!NOTE]" if l =~ /^ {0,3}> ?\*{1,2}\[!\w+\]/
+          ctx.warns << "#{r}:#{n}: '[! TYPE]' with a space is not an alert (renders as a plain quote)" if l =~ /^ {0,3}> ?\[! +\w+\]/
+          next unless (m = l.match(/^ {0,3}> ?\[!(\w+)\](.*)$/))
+          t, after = m[1], m[2]
+          next errs << "#{r}:#{n}: unregistered alert type [!#{t}] (allowed: #{KNOWN.join('/')}; any case)" unless KNOWN.include?(t.upcase)
+          errs << "#{r}:#{n}: text after [!#{t}] (custom titles are not supported; GitHub shows a plain quote)" unless after.strip.empty?
+          rest = lines[(i + 1)..].to_a.take_while { |x| x.strip != "" }
+          errs << "#{r}:#{n}: empty alert [!#{t}] (GitHub shows a plain quote); add body text" if rest.all? { |x| x.sub(/^ {0,3}>/, "").strip.empty? }
+        end
+      end
+
+      # Tool-generated region markers on their own line, e.g. <!-- spec:toc:begin --> / <!-- spec:toc:end -->
+      MARKER = /^[ \t]*<!--[ \t]*[a-z][a-z0-9-]*(?::[a-z0-9._-]+)*:(?:begin|end)[ \t]*-->[ \t]*$/
+
+      # 1c. forbidden syntax outside code
+      def forbidden(ctx, f, code, html_free)
+        r = ctx.rel(f)
+        ctx.errs << "#{r}: HTML comment <!-- --> (hidden on GitHub, emitted by kramdown); remove it" if code.gsub(MARKER, "").include?("<!--")
+        html_free.each_line.with_index(1) do |l, n|
+          linkless = l.gsub(/\]\([^)]*\)/, "]()").gsub(/<(https?:|mailto:)[^>]*>|<[^@\s>]+@[^>\s]+>/, "<>").sub(/^ {0,3}\[[^\]]+\]:\s*\S+/, "")
+          why = case l
+                when /<\/?[a-zA-Z][\w-]*[\s>\/]/ then "raw HTML (not portable: GitHub renders some tags, strips others; kramdown passes all through)"
+                when /\{%|\{\{/ then "Liquid"
+                when /\{:/ then "kramdown IAL/ALD"
+                when /\{#[\w-]+\}/ then "{#id} header id"
+                when /^:\s/ then "definition list"
+                when /^\*\[[^\]]+\]:/ then "abbreviation definition *[X]: (kramdown-only)"
+                when /^\s*([-*+]|\d+\.|\|).*\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]/i, /^\s*(>\s*){2,}\[!/ then NESTED_ALERT
+                end
+          why ||= "bare URL/e-mail autolink (kramdown does not link it); write <https://…> or [text](url)" if linkless =~ %r{(?<![<\w/@.])(https?://|www\.)\S|(?<![<\w.+-])[\w.+-]+@[\w-]+\.[a-z]{2,}}i
+          ctx.errs << "#{r}:#{n}: #{why}" if why
+        end
+      end
+
+      # Section headings: only column-0 '## ' starts a section; returns how many there are.
+      def headings(ctx, f, html_free)
+        h2 = 0
+        prev = ""
+        list = false # inside a list item (last column-0 block started with a list marker)
+        html_free.each_line.with_index(1) do |l, n|
+          list = l =~ /^([-*+]|\d+[.)])\s/ ? true : false if l =~ /^\S/
+          msg = case l
+                when /^##( |$)/ then (h2 += 1; nil)
+                when /^\s+##( |$)/
+                  if list then "'##' inside a list item is not a section (sections split only on column-0 '## '); use '###' or move it out of the list"
+                  elsif l =~ /^ {1,3}#/ then "indented '##' (kramdown: paragraph, GitHub: heading); start at column 0"
+                  end
+                when /^\s+> ?\[!\w+\]/ then list ? NESTED_ALERT : nil
+                when /^\s*(>\s*)+##( |$)/ then "'##' inside a quote/alert is not a section (sections split only on column-0 '## '; GitHub would show an h2 inside the box); use '###' or bold text"
+                when /^ {0,3}-+\s*$/
+                  if prev =~ /\S/ && prev !~ /^\s*([-*+>|#]|\d+\.)/
+                    n -= 1
+                    "setext heading (text underlined with ---) is not allowed; use '## '"
+                  end
+                end
+          ctx.errs << "#{ctx.rel(f)}:#{n}: #{msg}" if msg
+          prev = l
+        end
+        h2
+      end
+    end
+  end
+end

data/lib/modootoday/check/page_values.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # Rule 2: badge vocabularies in code spans (status:, tag:, kbd:; since: is rejected before 1.1) and image alt text.
+    module PageValues
+      STATUS = %w[available partial planned].freeze
+
+      module_function
+
+      def call(ctx, f, b)
+        errs, r = ctx.errs, ctx.rel(f)
+        text = Markdown.strip_fences(b)
+        text.scan(/`status:([^`\s]*)`/) do |(v)|
+          errs << "#{r}: unregistered status value `status:#{v}` (allowed: #{STATUS.join('/')})" unless STATUS.include?(v)
+        end
+        text.scan(/`tag:([^`]*)`/) do |(v)|
+          errs << "#{r}: `tag:#{v}` badge value must be one token [A-Za-z0-9._-]" unless v =~ /\A[A-Za-z0-9._-]+\z/
+        end
+        text.scan(/`since:([^`]*)`/) do |(v)|
+          errs << "#{r}: `since:#{v}` is not supported before 1.1 (the API is not released yet); remove it"
+        end
+        text.scan(/`kbd:([^`]*)`/) do |(v)|
+          errs << "#{r}: `kbd:#{v}` must be keys joined by '+' without spaces (e.g. `kbd:Ctrl+K`)" unless v =~ /\A[^\s+]+(\+[^\s+]+)*\z/
+        end
+        errs << "#{r}: image without alt text (![](...)); write ![description](...)" if text.gsub(/`[^`\n]*`/, "") =~ /!\[\s*\]\(/
+      end
+    end
+  end
+end

data/lib/modootoday/check/pages.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "page_syntax"
+require_relative "page_values"
+require_relative "component_rules"
+require_relative "page_sections"
+require_relative "a11y/content"
+require_relative "a11y/new_window"
+
+module Modootoday
+  module Check
+    # Per-page Markdown rules, run once per content page in this order.
+    module Pages
+      module_function
+
+      def call(ctx)
+        ctx.mds.each do |f|
+          text = File.read(f)
+          b = Markdown.body(text)
+          code = Markdown.strip_code(b)
+          h2 = PageSyntax.call(ctx, f, text, b, code)
+          PageValues.call(ctx, f, b)
+          ComponentRules.inline(ctx, ctx.rel(f), b)
+          PageSections.call(ctx, f, text, b, code, h2)
+          A11yContent.call(ctx, f, Markdown.strip_comments(code))
+          NewWindow.call(ctx, f, text, Markdown.strip_comments(code))
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/registry.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "slots"
+
+module Modootoday
+  module Check
+    # _data/components.yml: the registry's own shape (keys, slot rules, parts against api.md)
+    # and the i18n keys it declares.
+    module Registry
+      REG_KEYS = %w[params i18n slots parts].freeze
+      RULE_KEYS = %w[required min max].freeze
+
+      module_function
+
+      def call(ctx)
+        errs = ctx.errs
+        api_md = "#{ctx.src}/api.md"
+        api_codes = File.exist?(api_md) && (tbl = File.read(api_md)[/^## Component structure\n.*?(?=^## )/m]) ? tbl.scan(/`([^`]+)`/).flatten.map { |x| x.gsub("\\|", "|") } : nil
+        (ctx.comps.is_a?(Hash) ? ctx.comps : {}).each do |c, spec|
+          where = "_data/components.yml: #{c}"
+          next if spec.nil?
+          next errs << "#{where} must be a map (#{REG_KEYS.join(', ')})" unless spec.is_a?(Hash)
+          (spec.keys - REG_KEYS).each { |k| errs << "#{where}: unknown key '#{k}' (known: #{REG_KEYS.join(', ')})" }
+          slots(errs, where, spec["slots"]) if spec.key?("slots")
+          errs << "#{where}.params must be a map of param name -> {allowed, required}" if spec.key?("params") && !spec["params"].is_a?(Hash)
+          parts(errs, where, spec["parts"], api_codes) if spec.key?("parts")
+        end
+      end
+
+      def slots(errs, where, slots)
+        forms = slots.is_a?(Array) ? slots : [slots]
+        errs << "#{where}.slots: a list of alternative forms needs at least 2 maps" if slots.is_a?(Array) && forms.size < 2
+        forms.each_with_index do |form, fi|
+          fw = slots.is_a?(Array) ? "#{where}.slots[#{fi}]" : "#{where}.slots"
+          next errs << "#{fw} must be a map of slot name -> {required, min, max}" unless form.is_a?(Hash)
+          form.each do |name, rule|
+            next errs << "#{fw}: unknown slot '#{name}' (known: #{Slots.names.join(', ')})" unless Slots.known?(name)
+            next if rule.nil?
+            next errs << "#{fw}.#{name} must be a map of required, min, max" unless rule.is_a?(Hash)
+            (rule.keys - RULE_KEYS).each { |k| errs << "#{fw}.#{name}: unknown key '#{k}' (known: #{RULE_KEYS.join(', ')})" }
+            errs << "#{fw}.#{name}.required must be true or false" if rule.key?("required") && ![true, false].include?(rule["required"])
+            %w[min max].each { |k| errs << "#{fw}.#{name}.#{k} must be a whole number >= 0" if rule.key?(k) && !(rule[k].is_a?(Integer) && rule[k] >= 0) }
+            mn = rule["min"].is_a?(Integer) ? rule["min"] : (rule["required"] == true ? 1 : nil)
+            errs << "#{fw}.#{name}: min #{mn} is greater than max #{rule['max']}" if mn && rule["max"].is_a?(Integer) && mn > rule["max"]
+          end
+        end
+      end
+
+      def parts(errs, where, parts, api_codes)
+        return errs << "#{where}.parts must be a list of CSS selectors" unless parts.is_a?(Array) && parts.all? { |x| x.is_a?(String) && !x.strip.empty? }
+        parts.each do |sel|
+          errs << "#{where}.parts: '#{sel}' does not look like a CSS selector" unless sel.match?(/\A[\w\s.#\[\]=|"'>+~:()*-]+\z/)
+          errs << "#{where}.parts: '#{sel}' is not in the Component structure table of api.md" if api_codes && !api_codes.include?(sel)
+        end
+      end
+
+      # Every i18n key a component declares exists in every _data/i18n/<lang>.yml or the theme catalog for that language.
+      def i18n_keys(ctx)
+        return unless ctx.comps
+        dig = ->(h, key) { key.split(".").reduce(h) { |a, k| a.is_a?(Hash) ? a[k] : nil } }
+        ctx.comps.each do |name, spec|
+          Array(spec && spec["i18n"]).each do |key|
+            ctx.i18n.each { |lang, h| ctx.errs << "_data/i18n/#{lang}.yml: missing key '#{key}' (component #{name})" if dig[h, key].nil? && !I18n.theme_keys(lang).include?(key) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/site_config.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # The modootoday: settings in the site's _config.yml.
+    module SiteConfig
+      COMPONENTS = %w[callout badge hero cta card tabs code-copy nav sidebar page-actions pagination theme-toggle breadcrumb toc accordion steps figure timeline kbd search code footnotes progress embed banner filetree details faq params linkcards quote gallery pricing subscribe loading].freeze
+      SEMANTIC = %w[background foreground muted muted-foreground card card-foreground primary primary-foreground brand accent
+                    accent-foreground border ring note tip important warning caution status-available status-partial
+                    status-planned font-sans font-mono font-size line-height measure space radius].freeze
+
+      module_function
+
+      # twins: source needs Jekyll's raw copies of front-matter-less pages.
+      def source_mode(ctx)
+        return unless ctx.source_mode?
+        cfg = ctx.site_cfg
+        of = cfg["optional_front_matter"] || {}
+        ctx.errs << "_config.yml: modootoday.twins: source needs the raw copies; remove optional_front_matter.remove_originals" if of.is_a?(Hash) && of["remove_originals"] == true
+        ctx.errs << "_config.yml: modootoday.twins: source conflicts with require_front_matter: true" if cfg["require_front_matter"] == true
+      end
+
+      def call(ctx)
+        mtc, errs = ctx.mtc, ctx.errs
+        return errs << "_config.yml: modootoday: must be a map" if mtc && !mtc.is_a?(Hash)
+        return unless mtc.is_a?(Hash)
+        enums(mtc, errs)
+        if mtc.key?("archive")
+          a = mtc["archive"]
+          if !a.is_a?(Hash) || !(a.keys - %w[tags categories]).empty?
+            errs << "_config.yml: modootoday.archive must be a map with tags: and/or categories: (archive page URLs)"
+          else
+            a.each { |k, v| errs << "_config.yml: modootoday.archive.#{k} must be a site path like /#{k}/ (starts and ends with /)" unless v.to_s =~ %r{\A/(\S*/)?\z} }
+          end
+        end
+        errs << "_config.yml: modootoday.edit_url must be an http(s) URL ending in / (page.path is appended)" if mtc.key?("edit_url") && mtc["edit_url"].to_s !~ %r{\Ahttps?://\S+/\z}
+        ctx.warns << "_config.yml: modootoday.feed: true links /feed.xml; add jekyll-feed to plugins" if mtc["feed"] == true && !Array(ctx.site_cfg["plugins"]).map(&:to_s).include?("jekyll-feed")
+        %w[css_layers badges seo hreflang feed page_actions back_to_top loading].each { |k| errs << "_config.yml: modootoday.#{k} must be true or false" if mtc.key?(k) && ![true, false].include?(mtc[k]) }
+        errs << "_config.yml: modootoday.css must be split or bundle" if mtc.key?("css") && !%w[split bundle].include?(mtc["css"])
+        errs << "_config.yml: modootoday.banner must be a map with text: (and optional url:, link:)" if mtc.key?("banner") && !(mtc["banner"].is_a?(Hash) && mtc["banner"]["text"])
+        errs << "_config.yml: modootoday.sidebar must be auto, true or false" if mtc.key?("sidebar") && ![true, false, "auto"].include?(mtc["sidebar"])
+        if mtc.key?("components")
+          list = mtc["components"].is_a?(Array) ? mtc["components"] : (errs << "_config.yml: modootoday.components must be a list"; [])
+          (list.map(&:to_s) - COMPONENTS).each { |c| errs << "_config.yml: modootoday.components: unknown component '#{c}' (known: #{COMPONENTS.join(', ')})" }
+        end
+        tokens(ctx)
+      end
+
+      def enums(mtc, errs)
+        errs << "_config.yml: modootoday.twins must be true, false or source (got #{mtc['twins'].inspect})" if mtc.key?("twins") && ![true, false, "source"].include?(mtc["twins"])
+        errs << "_config.yml: modootoday.color_scheme must be auto, auto-dark, auto-light, light or dark (got #{mtc['color_scheme'].inspect})" if mtc.key?("color_scheme") && !%w[auto auto-dark auto-light light dark].include?(mtc["color_scheme"])
+        errs << "_config.yml: modootoday.csp must be strict or false (got #{mtc['csp'].inspect})" if mtc.key?("csp") && mtc["csp"] != "strict" && mtc["csp"] != false
+        errs << "_config.yml: modootoday.languages must be a list of language codes such as [en, ko]" if mtc.key?("languages") && !(mtc["languages"].is_a?(Array) && mtc["languages"].all? { |l| l.to_s =~ /\A[a-z]{2,3}(-[A-Za-z0-9]+)*\z/ })
+      end
+
+      def tokens(ctx)
+        mtc, errs = ctx.mtc, ctx.errs
+        %w[tokens tokens_dark].each do |k|
+          next unless mtc.key?(k)
+          next errs << "_config.yml: modootoday.#{k} must be a map" unless mtc[k].is_a?(Hash)
+          mtc[k].each do |name, val|
+            ctx.warns << "_config.yml: modootoday.#{k}.#{name}: not a semantic token (#{SEMANTIC.join(', ')})" unless SEMANTIC.include?(name.to_s)
+            v = val.to_s.strip
+            if v.empty? || v =~ /[;{}<>]/ || v !~ /\A[#\w\s.,%()"'+\-*\/]+\z/
+              errs << "_config.yml: modootoday.#{k}.#{name}: invalid CSS value #{val.inspect}"
+            elsif v.start_with?("#") && v !~ /\A#(\h{3}|\h{4}|\h{6}|\h{8})\z/
+              errs << "_config.yml: modootoday.#{k}.#{name}: invalid hex color #{val.inspect}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/slots.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # Slot contract: named, stable parts of a section's Markdown. Detection is structural and
+    # mirrors what modootoday/markdown/sections.html and the component scripts consume; markup does not change.
+    module Slots
+      DETECT = {
+        "lead" => ->(m) { m.split(/\n\s*\n/).reject { |p| p.strip.empty? }.take_while { |p| p !~ /\A\s*([-*+]\s|\d+[.)]\s|###|```|~~~|>)/ }.count { |p| p =~ /\S/ && p !~ /\A\s*(\[[^\]]+\]\([^)]*\)\s*)+\z/ } },
+        "items" => ->(m) { m.scan(/^([-*+]|\d+[.)])\s/).size },
+        "panels" => ->(m) { m.scan(/^###(?: |$)/).size },
+        "actions" => ->(m) { m.scan(/^(?:\[[^\]\n]+\]\([^)\n]*\)[ \t]*)+$/).size },
+        "code" => ->(_m, raw) { n = 0; Markdown.strip_fences(raw) { n += 1 }; n },
+        "rows" => ->(m) { [m.scan(/^\s*\|.*\|\s*$/).size - 2, 0].max },
+        "quotes" => ->(m) { m.split(/\n\s*\n/).count { |p| p =~ /\A\s*>/ } },
+        "figures" => ->(m) { m.scan(/^!\[[^\]\n]+\]\([^)\n]+\)/).size },
+      }.freeze
+
+      module_function
+
+      def known?(name) = DETECT.key?(name)
+      def names = DETECT.keys
+
+      # The problem with one slot of one section, or nil.
+      def count_problem(name, rule, md)
+        m, raw = md || ["", ""]
+        det = DETECT[name]
+        n = det.arity == 2 ? det.call(m, raw) : det.call(m)
+        rule = {} unless rule.is_a?(Hash)
+        min = rule["min"].is_a?(Integer) ? rule["min"] : (rule["required"] == true ? 1 : nil)
+        max = rule["max"].is_a?(Integer) ? rule["max"] : nil
+        return "slot '#{name}' has #{n} item(s), needs at least #{min}" if min && n < min
+        "slot '#{name}' has #{n} item(s), allows at most #{max}" if max && n > max
+      end
+
+      # slots: is a map (one form) or a list of maps (alternative forms; a section must satisfy one).
+      def check_section(errs, file, i, c, slots, md)
+        return if slots.nil?
+        forms = (slots.is_a?(Array) ? slots : [slots]).select { |f| f.is_a?(Hash) }
+        probs = forms.map { |form| form.select { |name, _| known?(name) }.filter_map { |name, rule| count_problem(name, rule, md) } }
+        return if probs.empty? || probs.any?(&:empty?)
+        if slots.is_a?(Array)
+          errs << "#{file}: sections[#{i}] #{c}: matches none of #{forms.size} slot forms (#{probs.each_with_index.map { |p, k| "form #{k + 1}: #{p.join(', ')}" }.join('; ')})"
+        else
+          probs[0].each { |p| errs << "#{file}: sections[#{i}] #{c}: #{p}" }
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/structured_data.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../schema/rules"
+
+module Modootoday
+  module Check
+    # 6. Built site: schema.org JSON-LD. At most one application/ld+json block per page; valid JSON with the
+    #    schema.org @context; every @type and property in the vocabulary; required properties per type
+    #    (recommended ones are warnings with --schema-recommended); absolute URLs; ISO 8601 dates; unique @id; the page node agrees
+    #    with og:url, og:title and og:image; inLanguage matches <html lang>.
+    module StructuredData
+      BLOCK = %r{<script type="application/ld\+json">(.*?)</script>}m
+      CONTEXT = %r{\Ahttps?://schema\.org/?\z}
+
+      module_function
+
+      def call(ctx)
+        Dir.glob("#{ctx.site}/**/*.html").sort.each { |f| page(ctx, f, File.read(f)) }
+      end
+
+      def page(ctx, f, html)
+        blocks = html.scan(BLOCK).flatten
+        return if blocks.empty?
+
+        ctx.errs << "#{f}: #{blocks.size} JSON-LD blocks (use one @graph per page)" if blocks.size > 1
+        blocks.each do |b|
+          data = begin
+            JSON.parse(b)
+          rescue JSON::ParserError => e
+            next ctx.errs << "#{f}: JSON-LD is not valid JSON (#{e.message[0, 80]})"
+          end
+          ctx.errs << "#{f}: JSON-LD @context is not https://schema.org" unless data["@context"].to_s =~ CONTEXT
+          nodes = data.key?("@graph") ? Array(data["@graph"]) : [data]
+          ids = nodes.filter_map { |n| n["@id"] if n.is_a?(Hash) }
+          ids.tally.each { |id, c| ctx.errs << "#{f}: JSON-LD @id #{id} used by #{c} nodes" if c > 1 }
+          nodes.each { |n| node(ctx, f, n, "@graph") }
+          meta(ctx, f, html, nodes)
+        end
+      end
+
+      # A node, then its nested nodes. Pure references ({"@id": ...}) need no @type.
+      def node(ctx, f, n, path)
+        return unless n.is_a?(Hash)
+
+        types = Array(n["@type"])
+        if types.empty?
+          ctx.errs << "#{f}: JSON-LD #{path} has no @type" unless n.keys == ["@id"] || path.end_with?("]")
+        end
+        types.each { |t| ctx.errs << "#{f}: JSON-LD @type #{t} is not in the schema.org vocabulary" unless Schema.type?(t) }
+        types.each { |t| required(ctx, f, n, t, path) }
+        n.each do |k, v|
+          next if %w[@context @type @graph].include?(k)
+
+          ctx.errs << "#{f}: JSON-LD #{path}.#{k} is not a schema.org property" unless k.start_with?("@") || Schema.property?(k)
+          values(ctx, f, k, v, "#{path}.#{k}")
+        end
+      end
+
+      def values(ctx, f, k, v, path)
+        Array(v).each_with_index do |x, i|
+          next node(ctx, f, x, v.is_a?(Array) ? "#{path}[#{i}]" : path) if x.is_a?(Hash)
+          next unless x.is_a?(String)
+
+          ctx.errs << "#{f}: JSON-LD #{path} is not an absolute URL (#{x[0, 60]})" if Schema::URL_KEYS.include?(k) && x !~ %r{\Ahttps?://}
+          ctx.errs << "#{f}: JSON-LD #{path} is not an ISO 8601 date (#{x[0, 40]})" if Schema::DATE_KEYS.include?(k) && x !~ Schema::ISO_8601
+        end
+      end
+
+      def required(ctx, f, n, type, path)
+        req, rec = Schema::RULES[type]
+        return unless req
+
+        has = ->(alt) { alt.split("|").any? { |p| !n[p].nil? && n[p] != "" && n[p] != [] } }
+        req.each { |p| ctx.errs << "#{f}: JSON-LD #{type} (#{path}) lacks required #{p.tr('|', '/')}" unless has.(p) }
+        return unless ctx.option?("--schema-recommended")
+
+        rec.each { |p| ctx.warns << "#{f}: JSON-LD #{type} (#{path}) lacks recommended #{p.tr('|', '/')}" unless has.(p) }
+      end
+
+      # The page node (#webpage) against Open Graph and <html lang>: one source of truth for title, URL and image.
+      def meta(ctx, f, html, nodes)
+        pg = nodes.find { |n| n.is_a?(Hash) && n["@id"].to_s.end_with?("#webpage") } or return
+        og = ->(p) { html[/<meta property="og:#{p}" content="([^"]*)"/, 1]&.then { |s| unescape(s) } }
+        { "url" => pg["url"], "title" => pg["name"], "image" => pg.dig("primaryImageOfPage", "url") }.each do |p, v|
+          o, v = og.(p)&.split&.join(" "), v&.split&.join(" ") if p == "title"
+          o ||= og.(p)
+          ctx.errs << "#{f}: JSON-LD #{p == 'title' ? 'name' : p} #{v.inspect} differs from og:#{p} #{o.inspect}" if o && v && o != v
+        end
+        lang = html[/<html[^>]*\blang="([^"]+)"/, 1]
+        ctx.errs << "#{f}: JSON-LD inLanguage #{pg['inLanguage']} differs from <html lang=\"#{lang}\">" if lang && pg["inLanguage"] && lang != pg["inLanguage"]
+      end
+
+      def unescape(s) = s.gsub("&quot;", '"').gsub("&#39;", "'").gsub("&lt;", "<").gsub("&gt;", ">").gsub("&amp;", "&")
+    end
+  end
+end

data/lib/modootoday/check/stylesheets.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # 5b/5c. Site sources: Sass portability on GitHub Pages (Ruby Sass 3.7: @use/@forward pass
+    # through silently, @supports selector() is a syntax error).
+    module Stylesheets
+      SASS_BAD = [[/^\s*@(use|forward)\b/, "@use/@forward (Ruby Sass on GitHub Pages copies it into the CSS untouched); use @import"],
+                  [/@supports\s+(not\s+)?selector\(/, "@supports selector() (Ruby Sass syntax error on GitHub Pages)"]].freeze
+
+      module_function
+
+      def call(ctx)
+        sass(ctx)
+      end
+
+      def sass(ctx)
+        src = ctx.src
+        Dir.glob(["#{src}/_sass/**/*.scss", "#{src}/assets/**/*.scss"]).reject { |f| ctx.skipped?(f) }.sort.each do |f|
+          File.read(f).gsub(%r{/\*.*?\*/}m) { |c| "\n" * c.count("\n") }.each_line.with_index(1) do |l, n|
+            l = l.sub(%r{//.*}, "")
+            SASS_BAD.each { |re, why| ctx.errs << "#{ctx.rel(f)}:#{n}: #{why}" if l =~ re }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/twins.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # 7. --twins: every Markdown page (except README.md and `twin: false`) has /<page>/index.md
+    #    (/index.md for index.md), byte-identical to its source body. It comes from a stub <name>.md.txt
+    #    (layout: twin; works on GitHub Pages) or from the opt-in plugin (plugins: [jekyll-theme-modootoday]).
+    #    With modootoday.twins: source, a page without front matter is its own twin at /<path>.md.
+    #    llms.txt / llms-full.txt exist at / and at each /<lang>/; llms-full.txt contains every page body.
+    module Twins
+      HINT = "add a stub %s (front matter `layout: twin`, `twin_of`, `permalink`) or enable `plugins: [jekyll-theme-modootoday]` (not on classic GitHub Pages)"
+
+      module_function
+
+      def call(ctx)
+        return unless ctx.option?("--twins")
+        bodies = Hash.new { |h, k| h[k] = [] }
+        ctx.mds.each { |f| page(ctx, f, bodies) }
+        llms(ctx, bodies)
+      end
+
+      def page(ctx, f, bodies)
+        errs, site, rf = ctx.errs, ctx.site, ctx.rel(f)
+        stub = "#{f}.txt"
+        if File.exist?(stub)
+          st = File.read(stub)
+          meta = (Markdown.fm(st) rescue {})
+          errs << "#{ctx.rel(stub)}: stub must set layout: twin" unless meta["layout"] == "twin"
+          errs << "#{ctx.rel(stub)}: stub body must be empty" unless Markdown.body(st).strip.empty?
+        end
+        return if File.basename(f) == "README.md" || (Markdown.fm(File.read(f)) rescue {})["twin"] == false
+        return if rf.split("/").include?("_posts") # posts: dated URLs, listed by the archive; no twin (documented limit)
+        r = rf.delete_suffix(".md")
+        if ctx.source_mode? && File.read(f) !~ Markdown::FM
+          # front-matter-less mode: rendered page + raw copy of the whole source at its own path
+          errs << "#{rf}.txt: redundant stub in twins: source mode (the source is already the twin); delete it" if File.exist?(stub)
+          raw = "#{site}/#{rf}"
+          html = ["#{site}/#{r}.html", "#{site}/#{r}/index.html"]
+          bodies[ctx.lang_of(r).to_s] << [rf, File.read(f)]
+          errs << "#{rf}: no rendered page (#{html.map { |h| h.delete_prefix("#{site}/") }.join(' or ')}); is jekyll-optional-front-matter enabled? (local builds: list it in plugins:)" unless html.any? { |h| File.exist?(h) }
+          return errs << "#{rf}: raw copy missing at #{raw} (optional_front_matter.remove_originals must not be true)" unless File.exist?(raw)
+          return errs << "#{raw}: raw copy is not byte-identical to #{rf}" unless File.binread(raw) == File.binread(f)
+          return
+        end
+        out = File.basename(r) == "index" ? "#{site}/#{r}.md" : "#{site}/#{r}/index.md"
+        b = Markdown.body(File.read(f))
+        bodies[ctx.lang_of(r).to_s] << [rf, b]
+        return errs << "#{rf}: twin missing at #{out}: #{format(HINT, "#{rf}.txt")}" unless File.exist?(out)
+        errs << "#{out}: twin is not byte-identical to the body of #{rf}" unless File.binread(out) == b.b
+      end
+
+      def llms(ctx, bodies)
+        langs = [""] + ctx.i18n.keys.select { |l| Dir.exist?("#{ctx.src}/#{l}") }
+        langs.each do |l|
+          %w[llms.txt llms-full.txt].each do |n|
+            p = [ctx.site, l, n].reject(&:empty?).join("/")
+            next ctx.errs << "#{p}: missing (per-language llms file; stub with `layout: #{n.delete_suffix('.txt')}` or the plugin)" unless File.exist?(p)
+            txt = File.read(p)
+            if n == "llms.txt"
+              ctx.errs << "#{p}: must start with an H1 (llmstxt.org)" unless txt.start_with?("# ")
+            else
+              bodies[l].each { |(name, b)| ctx.errs << "#{p}: does not contain the body of #{name}" unless b.strip.empty? || txt.include?(b.strip) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# md-components v1 checker (Ruby stdlib only; Nokogiri optional). This file only assembles the parts;
+# each rule group lives in check/<name>.rb and reports into one shared Context.
+require "yaml"
+require "date"
+require_relative "check/markdown"
+require_relative "check/context"
+require_relative "check/registry"
+require_relative "check/pages"
+require_relative "check/i18n"
+require_relative "check/built_parts"
+require_relative "check/build_output"
+require_relative "check/structured_data"
+require_relative "check/stylesheets"
+require_relative "check/site_config"
+require_relative "check/blog"
+require_relative "check/github_pages"
+require_relative "check/layouts"
+require_relative "check/twins"
+require_relative "check/gh_render"
+require_relative "check/cli"

data/lib/modootoday/schema/rules.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Modootoday
+  # schema.org rules the checker applies to built JSON-LD: the vocabulary (vocab.txt, from script/schema-vocab),
+  # required properties per type (schema.org and Google Search structured data guidelines) and recommended ones.
+  module Schema
+    VOCAB_FILE = File.expand_path("vocab.txt", __dir__)
+    # Not schema.org properties, but documented by Google/schema.org Actions for SearchAction.
+    EXTRA_PROPS = %w[query-input].freeze
+    ARTICLE = %w[Article BlogPosting NewsArticle TechArticle Report ScholarlyArticle SocialMediaPosting].freeze
+    PAGE = %w[WebPage AboutPage CollectionPage ContactPage FAQPage ProfilePage SearchResultsPage ItemPage QAPage].freeze
+    # type => [required, recommended]; one alternative per entry ("a|b": either).
+    RULES = {
+      "WebSite" => [%w[name url], %w[inLanguage publisher]],
+      "Organization" => [%w[name], %w[url logo]],
+      "Person" => [%w[name], %w[url]],
+      "BreadcrumbList" => [%w[itemListElement], []],
+      "ListItem" => [%w[position], %w[name item|url]],
+      "ItemList" => [%w[itemListElement], []],
+      "JobPosting" => [%w[title description datePosted hiringOrganization jobLocation|applicantLocationRequirements], %w[employmentType validThrough baseSalary]],
+      "Event" => [%w[name startDate location], %w[endDate eventStatus image description organizer offers]],
+      "Course" => [%w[name description], %w[provider offers hasCourseInstance]],
+      "PodcastEpisode" => [%w[name], %w[partOfSeries datePublished associatedMedia|audio]],
+      "SoftwareApplication" => [%w[name], %w[offers applicationCategory operatingSystem]],
+      "Offer" => [%w[price|priceSpecification priceCurrency|priceSpecification], %w[availability url]],
+      "DefinedTermSet" => [%w[name], %w[hasDefinedTerm]],
+      "DefinedTerm" => [%w[name], %w[description]],
+      "Question" => [%w[name acceptedAnswer|suggestedAnswer], []],
+      "Answer" => [%w[text], []],
+      "SearchAction" => [%w[target query-input], []],
+      "ImageObject" => [%w[url|contentUrl], []],
+    }.merge(ARTICLE.to_h { |t| [t, [%w[headline], %w[datePublished dateModified author image]]] })
+                 .merge(PAGE.to_h { |t| [t, [%w[name url], %w[inLanguage]]] })
+                 .merge("FAQPage" => [%w[name url mainEntity], []], "ProfilePage" => [%w[name url], %w[mainEntity]]).freeze
+    URL_KEYS = %w[@id url item logo image sameAs contentUrl embedUrl urlTemplate applicationUrl downloadUrl installUrl].freeze
+    DATE_KEYS = %w[datePublished dateModified dateCreated datePosted validThrough startDate endDate uploadDate].freeze
+    ISO_8601 = /\A\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?\z/
+
+    module_function
+
+    def vocab
+      @vocab ||= File.readlines(VOCAB_FILE, chomp: true).reject { |l| l.start_with?("#") }
+                     .each_with_object({ "t" => {}, "p" => {} }) { |l, h| k, n = l.split(" ", 2); h[k][n] = true }
+    end
+
+    def type?(name) = vocab["t"].key?(name)
+    def property?(name) = vocab["p"].key?(name) || EXTRA_PROPS.include?(name)
+  end
+end