jekyll-theme-modootoday 1.0.0

data/lib/modootoday/check/github_pages.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # 6. --github-pages[=VERSION]: the lockfile pins github-pages VERSION (default 232 or $MODOOTODAY_GITHUB_PAGES).
+    module GithubPages
+      module_function
+
+      def call(ctx)
+        return unless (gp = ctx.argv.find { |a| a == "--github-pages" || a.start_with?("--github-pages=") })
+        want = gp.include?("=") ? gp.split("=", 2)[1] : ENV.fetch("MODOOTODAY_GITHUB_PAGES", "232")
+        lock = "#{ctx.src}/Gemfile.lock" # the site's own lockfile wins; else the active bundle's lockfile
+        lock = "#{ENV['BUNDLE_GEMFILE']}.lock" if !File.exist?(lock) && ENV["BUNDLE_GEMFILE"] && File.exist?("#{ENV['BUNDLE_GEMFILE']}.lock")
+        if File.exist?(lock) && (v = File.read(lock)[/^    github-pages \((\d+)\)/, 1])
+          ctx.errs << "#{lock}: github-pages #{v} != #{want}" unless v == want
+        else
+          ctx.errs << "--github-pages: no Gemfile.lock with github-pages found (#{lock}); run `bundle lock` (the file may stay gitignored) " \
+                     "or point BUNDLE_GEMFILE at a Gemfile whose .lock pins github-pages, or drop --github-pages"
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/i18n.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Modootoday
+  module Check
+    # Interface catalogs: site _data/i18n/<lang>.yml against the default language and the theme's
+    # built-in catalogs (i18n/<code>.yml in the gem), --i18n-init and --i18n.
+    module I18n
+      THEME = File.expand_path("../../../i18n", __dir__)
+
+      module_function
+
+      def leaves(h, pre = nil) = h.is_a?(Hash) ? h.flat_map { |k, v| leaves(v, [pre, k].compact.join(".")) } : [[pre, h]]
+      def keys(h) = leaves(h).map(&:first)
+      def theme_codes = Dir.glob("#{THEME}/*.yml").map { |f| File.basename(f, ".yml") } - %w[languages glossary]
+
+      # Keys the theme ships for a language (exact code, else its base subtag; never ur -> ur-Latn).
+      def theme_keys(lang)
+        f = "#{THEME}/#{lang}.yml"
+        f = Dir.glob("#{THEME}/#{lang.split('-').first}-*.yml").reject { |x| x.end_with?("/ur-Latn.yml") }.min unless File.file?(f)
+        f ? keys(YAML.safe_load(File.read(f))) : []
+      end
+
+      def base_lang(ctx)
+        b = ctx.site_cfg["lang"].to_s.split("-").first
+        b.to_s.empty? ? "en" : b
+      end
+
+      def call(ctx)
+        Dir.glob("#{ctx.src}/_data/i18n/*.yaml").each { |f| ctx.errs << "#{ctx.rel(f)}: catalogs use .yml; rename to #{File.basename(f, '.yaml')}.yml" }
+        init(ctx) if ctx.argv.any? { |a| a.start_with?("--i18n-init") }
+        follow_default(ctx)
+        registry(ctx) if ctx.option?("--i18n") && File.exist?("#{THEME}/en.yml")
+      end
+
+      def init(ctx)
+        ini = ctx.argv.find { |a| a.start_with?("--i18n-init") }
+        want = ini.split("=", 2)[1].to_s.split(",").map(&:strip).reject(&:empty?)
+        want = theme_codes if want.empty? || want == ["all"]
+        FileUtils.mkdir_p("#{ctx.src}/_data/i18n")
+        want.each do |l|
+          from, to = "#{THEME}/#{l}.yml", "#{ctx.src}/_data/i18n/#{l}.yml"
+          next ctx.errs << "--i18n-init: no starter catalog for '#{l}' (have: #{theme_codes.sort.join(' ')})" unless File.exist?(from)
+          next (FileUtils.cp(from, to); puts "created #{to}") unless File.exist?(to)
+          ref = YAML.safe_load(File.read(from))
+          (keys(ref) - keys(YAML.safe_load(File.read(to)) || {})).each { |k| puts "#{to}: missing #{k}: #{k.split('.').reduce(ref) { |a, x| a[x] }.inspect}" }
+        end
+      end
+
+      # Translations follow the default language: a translated key must exist in the default file or the
+      # theme registry; a key the default file has that a translation lacks (and the theme does not ship
+      # for that language) is a warning; a page under <lang>/ needs a default-language page.
+      def follow_default(ctx)
+        bl = base_lang(ctx)
+        return unless (base = ctx.i18n[bl])
+
+        base_keys = keys(base) | theme_keys("en")
+        ctx.i18n.each do |lang, h|
+          next if lang == bl
+
+          (keys(h) - base_keys).each { |k| ctx.errs << "_data/i18n/#{lang}.yml: key '#{k}' is not in _data/i18n/#{bl}.yml (#{bl} is canonical; add it there first)" }
+          (keys(base) - keys(h) - theme_keys(lang)).each { |k| ctx.warns << "_data/i18n/#{lang}.yml: missing key '#{k}' (falls back to #{bl})" }
+          ctx.mds.each do |f|
+            r = ctx.rel(f)
+            next unless r.start_with?("#{lang}/")
+
+            en = r.delete_prefix("#{lang}/")
+            ctx.warns << "#{r}: no #{bl} page at #{en} (translations follow the canonical page)" unless File.exist?("#{ctx.src}/#{en}")
+          end
+        end
+      end
+
+      def registry(ctx)
+        reg = leaves(YAML.safe_load(File.read("#{THEME}/en.yml"))).to_h
+        site_en = leaves(ctx.i18n[base_lang(ctx)] || {}).to_h
+        ph = ->(v) { v.to_s.scan(/%\{(\w+)\}/).flatten.sort }
+        ctx.i18n.each do |lang, h|
+          leaves(h).each do |k, v|
+            next if %w[title description].include?(k) # site-level strings, not theme keys
+
+            next ctx.errs << "_data/i18n/#{lang}.yml: unknown key '#{k}' (not in the theme registry or #{base_lang(ctx)}.yml)" unless reg.key?(k) || site_en.key?(k)
+
+            ref = reg.key?(k) ? reg[k] : site_en[k]
+            ctx.errs << "_data/i18n/#{lang}.yml: '#{k}' placeholders #{ph[v].inspect} differ from English #{ph[ref].inspect}" unless ph[v] == ph[ref]
+          end
+        end
+        ctx.mds.each { |f| ctx.warns << "#{ctx.rel(f)}: translation: pending (served as the labeled English fallback)" if (Markdown.fm(File.read(f)) rescue {})["translation"] == "pending" }
+      end
+    end
+  end
+end

data/lib/modootoday/check/layouts/detail.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    module Layouts
+      # Detail layouts (project, case-study, job, event, episode): the front matter each one reads for its facts,
+      # call to action and JSON-LD (_includes/modootoday/detail/).
+      module Detail
+        LAYOUTS = %w[project case-study job event episode].freeze
+        EMPLOYMENT = %w[full-time part-time contractor temporary intern volunteer per-diem other].freeze
+
+        module_function
+
+        def call(errs, where, fm, _ctx)
+          links(errs, where, fm)
+          send(fm["layout"].tr("-", "_"), errs, where, fm) if respond_to?(fm["layout"].tr("-", "_"))
+        end
+
+        def links(errs, where, fm)
+          Shape.list(errs, where, "links", fm["links"], any: %w[label]) { |l, i| errs << "#{where}: links[#{i}].url is required" unless Shape.url?(l["url"]) }
+          errs << "#{where}: stack must be a list" unless fm["stack"].nil? || fm["stack"].is_a?(Array)
+          cta = fm["cta"]
+          errs << "#{where}: cta must be a map of label and url" unless cta.nil? || (cta.is_a?(Hash) && Shape.text?(cta["label"]) && Shape.url?(cta["url"]))
+        end
+
+        def job(errs, where, fm)
+          Shape.need_date(errs, where, "date", fm["date"])
+          Shape.need_date(errs, where, "deadline", fm["deadline"], optional: true)
+          Shape.one_of(errs, where, "employment", fm["employment"], EMPLOYMENT)
+          errs << "#{where}: set location: (a place) or remote: (the country applicants must live in)" unless Shape.text?(fm["location"]) || Shape.text?(fm["remote"])
+          errs << "#{where}: apply must be a site path, full URL or mailto: link" unless fm["apply"].nil? || Shape.url?(fm["apply"])
+          s = fm["salary"]
+          errs << "#{where}: salary must be text or a map of min, max, currency, unit" unless s.nil? || s.is_a?(String) || (s.is_a?(Hash) && s["min"].is_a?(Numeric) && Shape.text?(s["currency"]))
+        end
+
+        def event(errs, where, fm)
+          Shape.need_date(errs, where, "starts", fm["starts"])
+          Shape.need_date(errs, where, "ends", fm["ends"], optional: true)
+          errs << "#{where}: set venue: (a place) or online: (an https URL)" unless Shape.text?(fm["venue"]) || fm["online"].to_s.start_with?("https://")
+          errs << "#{where}: tickets must be a site path or full URL" unless fm["tickets"].nil? || Shape.url?(fm["tickets"])
+        end
+
+        def episode(errs, where, fm)
+          errs << "#{where}: episode must be a number" unless fm["episode"].is_a?(Integer)
+          errs << "#{where}: season must be a number" unless fm["season"].nil? || fm["season"].is_a?(Integer)
+          errs << "#{where}: duration must be minutes (a number)" unless fm["duration"].nil? || fm["duration"].is_a?(Integer)
+          %w[audio transcript].each { |k| errs << "#{where}: #{k} must be a site path or full URL" unless fm[k].nil? || Shape.url?(fm[k]) }
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/layouts/directory.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    module Layouts
+      # directory and its presets: items: (or data: <file in _data>), preset:, filter: <item field> or false.
+      module Directory
+        PRESETS = %w[cards portfolio team jobs events sponsors integrations].freeze
+        LAYOUTS = %w[directory portfolio team jobs events sponsors integrations].freeze
+
+        module_function
+
+        def call(errs, where, fm, ctx)
+          Shape.one_of(errs, where, "preset", fm["preset"], PRESETS)
+          errs << "#{where}: filter must be an item field name or false" unless fm["filter"].nil? || fm["filter"] == false || fm["filter"].is_a?(String)
+          items = items(errs, where, fm, ctx)
+          return if items.nil?
+          events = fm["layout"] == "events" || fm["preset"] == "events"
+          Shape.list(errs, where, "items", items, any: %w[title name]) do |it, i|
+            Shape.need_date(errs, where, "items[#{i}].date", it["date"], optional: !events)
+            Shape.need_date(errs, where, "items[#{i}].end", it["end"], optional: true)
+          end
+        end
+
+        def items(errs, where, fm, ctx)
+          return fm["items"] if fm.key?("items")
+          return errs << "#{where}: set items: (a list) or data: (a file in _data)" && nil unless fm["data"]
+          f = Dir.glob("#{ctx.src}/_data/#{fm['data']}.{yml,yaml,json}").first
+          return errs << "#{where}: data: #{fm['data']} has no file in _data" && nil unless f
+          d = YAML.safe_load(File.read(f), permitted_classes: [Date, Time])
+          d.is_a?(Hash) ? d["items"] : d
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/layouts/docs_extra.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    module Layouts
+      # Docs-extra layouts (reference, changelog, roadmap, glossary, hub, course, book) and the documents legal and resume.
+      module DocsExtra
+        LAYOUTS = %w[reference changelog roadmap glossary hub course book legal resume].freeze
+        CATS = %w[added changed fixed removed security].freeze
+        STATUS = %w[now next later].freeze
+
+        module_function
+
+        def url(errs, where, key, v) = (errs << "#{where}: #{key} must be a site path or a full URL" unless v.nil? || Shape.url?(v))
+
+        def call(errs, w, fm, _ctx)
+          send(fm["layout"], errs, w, fm)
+        end
+
+        def reference(errs, w, fm) = Shape.list(errs, w, "members", fm["members"], any: %w[name], optional: false)
+
+        def changelog(errs, w, fm)
+          Shape.list(errs, w, "releases", fm["releases"], any: %w[version], optional: false) do |r, i|
+            Shape.need_date(errs, w, "releases[#{i}].date", r["date"], optional: true)
+            CATS.each { |c| errs << "#{w}: releases[#{i}].#{c} must be a list" unless r[c].nil? || r[c].is_a?(Array) }
+            extra = r.keys - CATS - %w[version date url]
+            errs << "#{w}: releases[#{i}] has unknown keys #{extra.join(', ')} (use #{CATS.join(', ')})" unless extra.empty?
+          end
+        end
+
+        def roadmap(errs, w, fm)
+          Shape.list(errs, w, "items", fm["items"], optional: false) do |it, i|
+            Shape.one_of(errs, w, "items[#{i}].status", it["status"] || "(none)", STATUS)
+            url(errs, w, "items[#{i}].url", it["url"])
+          end
+        end
+
+        def glossary(errs, w, fm)
+          Shape.list(errs, w, "terms", fm["terms"], any: %w[term], optional: false) do |t, i|
+            errs << "#{w}: terms[#{i}].text is required" unless Shape.text?(t["text"])
+          end
+          names = Array(fm["terms"]).filter_map { |t| t["term"].to_s.downcase if t.is_a?(Hash) }
+          names.tally.each { |n, c| errs << "#{w}: term '#{n}' is listed #{c} times" if c > 1 }
+        end
+
+        def hub(errs, w, fm)
+          Shape.list(errs, w, "cards", fm["cards"], optional: false) { |c, i| errs << "#{w}: cards[#{i}].url is required" unless Shape.url?(c["url"]) }
+        end
+
+        def course(errs, w, fm)
+          errs << "#{w}: description is required (Course structured data)" unless Shape.text?(fm["description"])
+          Shape.list(errs, w, "modules", fm["modules"], optional: false) do |m, i|
+            Shape.list(errs, w, "modules[#{i}].lessons", m["lessons"]) do |l, j|
+              errs << "#{w}: modules[#{i}].lessons[#{j}].minutes must be a number" unless l["minutes"].nil? || l["minutes"].is_a?(Integer)
+              url(errs, w, "modules[#{i}].lessons[#{j}].url", l["url"])
+            end
+          end
+        end
+
+        def book(errs, w, fm)
+          errs << "#{w}: pages must be a number" unless fm["pages"].nil? || fm["pages"].is_a?(Integer)
+          errs << "#{w}: isbn must be 10 or 13 digits" unless fm["isbn"].nil? || fm["isbn"].to_s.delete("- ").match?(/\A(\d{9}[\dX]|\d{13})\z/)
+          Shape.list(errs, w, "chapters", fm["chapters"]) { |c, i| url(errs, w, "chapters[#{i}].url", c["url"]) }
+        end
+
+        def legal(errs, w, fm)
+          Shape.need_date(errs, w, "effective", fm["effective"])
+          Shape.need_date(errs, w, "updated", fm["updated"], optional: true)
+        end
+
+        def resume(errs, w, fm)
+          errs << "#{w}: set name: (or a title)" unless Shape.text?(fm["name"]) || Shape.text?(fm["title"])
+          Shape.list(errs, w, "experience", fm["experience"], any: %w[role]) do |e, i|
+            Shape.need_date(errs, w, "experience[#{i}].start", e["start"], optional: true)
+            Shape.need_date(errs, w, "experience[#{i}].end", e["end"], optional: true)
+          end
+          Shape.list(errs, w, "education", fm["education"], any: %w[school])
+          Shape.list(errs, w, "skills", fm["skills"], any: %w[group]) { |s, i| errs << "#{w}: skills[#{i}].items must be a list" unless s["items"].is_a?(Array) }
+          Shape.list(errs, w, "links", fm["links"], any: %w[label]) { |l, i| url(errs, w, "links[#{i}].url", l["url"]) }
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/layouts/marketing.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    module Layouts
+      # Marketing layouts (feature, pricing, download, brand, links, contact): the lists each one reads from front matter.
+      module Marketing
+        LAYOUTS = %w[feature pricing download brand links contact].freeze
+        HEX = /\A#(\h{3}|\h{6})\z/
+        FIELDS = %w[name email message].freeze
+
+        module_function
+
+        def call(errs, where, fm, _ctx)
+          w = where
+          link_list(errs, w, "actions", fm["actions"])
+          case fm["layout"]
+          when "feature" then Shape.list(errs, w, "features", fm["features"])
+          when "pricing" then pricing(errs, w, fm)
+          when "download"
+            Shape.list(errs, w, "downloads", fm["downloads"], any: %w[label], optional: false) { |d, i| need_url(errs, w, "downloads[#{i}].url", d["url"]) }
+          when "brand" then brand(errs, w, fm)
+          when "links" then link_list(errs, w, "links", fm["links"], optional: false)
+          when "contact" then contact(errs, w, fm)
+          end
+        end
+
+        def need_url(errs, where, key, v) = (errs << "#{where}: #{key} must be a site path or a full URL" unless Shape.url?(v))
+
+        def link_list(errs, where, key, val, optional: true)
+          Shape.list(errs, where, key, val, any: %w[label], optional: optional) { |l, i| need_url(errs, where, "#{key}[#{i}].url", l["url"]) }
+        end
+
+        def pricing(errs, where, fm)
+          plans = fm["plans"]
+          Shape.list(errs, where, "plans", plans, any: %w[name], optional: false) do |p, i|
+            errs << "#{where}: plans[#{i}].monthly is required" if p["monthly"].nil?
+            errs << "#{where}: plans[#{i}].features must be a list" unless p["features"].nil? || p["features"].is_a?(Array)
+          end
+          return unless plans.is_a?(Array)
+          y = plans.count { |p| p.is_a?(Hash) && !p["yearly"].nil? }
+          errs << "#{where}: set yearly on every plan or on none (#{y} of #{plans.size})" unless [0, plans.size].include?(y)
+          errs << "#{where}: only one plan can be recommended" if plans.count { |p| p.is_a?(Hash) && p["recommended"] } > 1
+        end
+
+        def brand(errs, where, fm)
+          Shape.list(errs, where, "colors", fm["colors"], any: %w[name]) do |c, i|
+            errs << "#{where}: colors[#{i}].hex must be #rgb or #rrggbb" unless c["hex"].is_a?(String) && c["hex"].match?(HEX)
+          end
+          Shape.list(errs, where, "assets", fm["assets"], any: %w[label]) { |a, i| need_url(errs, where, "assets[#{i}].url", a["url"]) }
+        end
+
+        def contact(errs, where, fm)
+          Shape.list(errs, where, "contacts", fm["contacts"], any: %w[label])
+          f = fm["form"]
+          return if f.nil?
+          return errs << "#{where}: form must be a map with action (an https URL)" unless f.is_a?(Hash) && f["action"].to_s.start_with?("https://")
+          fl = f["fields"].is_a?(String) ? f["fields"].split(",") : f["fields"]
+          (Array(fl) - FIELDS).each { |x| errs << "#{where}: form.fields has unknown field '#{x}' (known: #{FIELDS.join(', ')})" }
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/layouts/shape.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    module Layouts
+      # Shape helpers shared by the layout contracts: lists of maps, required keys, dates and URLs.
+      module Shape
+        module_function
+
+        def text?(v) = v.is_a?(String) && !v.strip.empty?
+        def url?(v) = v.is_a?(String) && v.match?(%r{\A(/|https?://|mailto:|tel:|#)})
+        def date?(v) = v.is_a?(Date) || v.is_a?(Time) || (v.is_a?(String) && (Time.parse(v) rescue false))
+
+        # A list of maps; each map needs one of `any` keys (e.g. title or name). Yields (item, index) for more checks.
+        def list(errs, where, key, val, any: %w[title], optional: true)
+          return errs << "#{where}: #{key} is required" if val.nil? && !optional
+          return if val.nil?
+          return errs << "#{where}: #{key} must be a list" unless val.is_a?(Array)
+          val.each_with_index do |it, i|
+            next errs << "#{where}: #{key}[#{i}] must be a map" unless it.is_a?(Hash)
+            errs << "#{where}: #{key}[#{i}] needs #{any.join(' or ')}" unless any.empty? || any.any? { |k| text?(it[k]) || it[k].is_a?(Numeric) }
+            %w[url image].each { |k| errs << "#{where}: #{key}[#{i}].#{k} must be a site path or a full URL" if it.key?(k) && !url?(it[k]) }
+            yield it, i if block_given?
+          end
+        end
+
+        def one_of(errs, where, key, val, allowed)
+          errs << "#{where}: #{key} must be one of #{allowed.join(', ')} (got #{val.inspect})" unless val.nil? || allowed.include?(val)
+        end
+
+        def need_date(errs, where, key, val, optional: false)
+          return if val.nil? && optional
+          errs << "#{where}: #{key} must be a date (YYYY-MM-DD or YYYY-MM-DD HH:MM)" unless date?(val)
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/layouts/shells.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    module Layouts
+      # Page shells: error status, redirect target, home hero; and the search fallback in _config.yml.
+      module Shells
+        STATUSES = [404, 410, 500].freeze
+
+        module_function
+
+        def error(errs, where, fm, _ctx)
+          s = fm.fetch("status", 404)
+          errs << "#{where}: status must be one of #{STATUSES.join(', ')} (got #{s.inspect})" unless STATUSES.include?(s)
+        end
+
+        def redirect(errs, where, fm, _ctx)
+          to = fm["redirect_to"]
+          errs << "#{where}: redirect_to is required (a site path starting with / or a full URL)" unless to.is_a?(String) && to.match?(%r{\A(/|https?://)})
+        end
+
+        def home(errs, where, fm, _ctx)
+          hero = fm["hero"]
+          return if hero.nil?
+          return errs << "#{where}: hero must be a map of title, text, actions, image" unless hero.is_a?(Hash)
+          (hero.keys - %w[title text actions image]).each { |k| errs << "#{where}: hero has unknown key '#{k}' (known: title, text, actions, image)" }
+          errs << "#{where}: hero.title is required when hero is set" unless Shape.text?(hero["title"])
+          actions(errs, where, "hero.actions", hero["actions"])
+        end
+
+        def actions(errs, where, key, acts)
+          return if acts.nil?
+          return errs << "#{where}: #{key} must be a list of {label, url}" unless acts.is_a?(Array)
+          acts.each_with_index do |a, i|
+            errs << "#{where}: #{key}[#{i}] needs label and url" unless a.is_a?(Hash) && a["label"].is_a?(String) && a["url"].is_a?(String)
+          end
+        end
+
+        def fallback(errs, fb)
+          return if fb.nil? || fb == false
+          return errs << "_config.yml: modootoday.search.fallback must be false or a map of url, param" unless fb.is_a?(Hash)
+          errs << "_config.yml: modootoday.search.fallback.url must be an https URL" if fb.key?("url") && !fb["url"].to_s.start_with?("https://")
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/layouts.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "layouts/shape"
+require_relative "layouts/shells"
+require_relative "layouts/directory"
+require_relative "layouts/detail"
+require_relative "layouts/marketing"
+require_relative "layouts/docs_extra"
+
+module Modootoday
+  module Check
+    # Front matter contracts of the theme layouts: each layout name maps to the check of the keys it reads
+    # (lib/modootoday/check/layouts/). Pages with other layouts are left alone.
+    module Layouts
+      def self.contracts
+        @contracts ||= {
+          "error" => Shells.method(:error), "redirect" => Shells.method(:redirect), "home" => Shells.method(:home),
+        }.merge(Directory::LAYOUTS.to_h { |l| [l, Directory.method(:call)] })
+          .merge(Detail::LAYOUTS.to_h { |l| [l, Detail.method(:call)] })
+          .merge(Marketing::LAYOUTS.to_h { |l| [l, Marketing.method(:call)] })
+          .merge(DocsExtra::LAYOUTS.to_h { |l| [l, DocsExtra.method(:call)] })
+      end
+
+      def self.register(names, check) = names.each { |n| contracts[n] = check }
+
+      def self.call(ctx)
+        ctx.mds.each do |f|
+          fm = Markdown.fm(File.read(f))
+          check = contracts[fm["layout"]]
+          check&.call(ctx.errs, "#{ctx.rel(f)}: layout #{fm['layout']}", fm, ctx)
+        end
+        Shells.fallback(ctx.errs, ctx.mtc.is_a?(Hash) && ctx.mtc["search"].is_a?(Hash) ? ctx.mtc["search"]["fallback"] : nil)
+      end
+    end
+  end
+end

data/lib/modootoday/check/markdown.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # Markdown text helpers shared by the rules: front matter, fenced code, code spans, comments.
+    module Markdown
+      FM = /\A---\r?\n(.*?\r?\n)?---\r?\n/m
+      FENCE_OPEN = /^( {0,3})(`{3,}|~{3,})(.*)$/
+
+      module_function
+
+      def fm(t) = (m = t[FM]) ? (YAML.safe_load(m.sub(/\A---\r?\n/, "").sub(/---\r?\n\z/, ""), permitted_classes: [Date, Time]) || {}) : {}
+      def body(t) = t.sub(FM, "")
+
+      # Blank out fenced code (CommonMark: closing fence = same char, length >= opener), keep line count.
+      # Yields [line_no, info_string] for every opening fence.
+      def strip_fences(t)
+        out = []
+        close = nil
+        t.each_line.with_index(1) do |l, n|
+          if close
+            close = nil if l =~ /^ {0,3}#{Regexp.escape(close[0])}{#{close.size},}\s*$/
+            out << "\n"
+          elsif (m = l.match(FENCE_OPEN)) && !(m[2].start_with?("`") && m[3].include?("`"))
+            close = m[2]
+            yield n, m[3].strip if block_given?
+            out << "\n"
+          else
+            out << l
+          end
+        end
+        out.join
+      end
+
+      def strip_code(t) = strip_fences(t).gsub(/(`+)(?!`).+?(?<!`)\1(?!`)/) { "``" }
+      def strip_comments(t) = t.gsub(/<!--.*?-->/m) { |m| "\n" * m.count("\n") }
+    end
+  end
+end

data/lib/modootoday/check/page_sections.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # Rules 3-4: the sections: list matches the '## ' headings, and each section's component
+    # (from _data/components.yml) gets known, allowed and required params and its slot contract.
+    module PageSections
+      module_function
+
+      THEME = File.expand_path("../../..", __dir__)
+
+      def call(ctx, f, text, b, code, h2)
+        errs, r = ctx.errs, ctx.rel(f)
+        meta = begin Markdown.fm(text) rescue (errs << "#{r}: front matter YAML error"; {}) end
+        secs = meta["sections"]
+        return unless secs
+        return errs << "#{r}: sections: must be a list" unless secs.is_a?(Array)
+        code.scan(/<!--.*?-->/m) { |c| errs << "#{r}: '##' inside an HTML comment is not a heading" if c =~ /^##/ }
+        errs << "#{r}: sections: has #{secs.size} item(s) but body has #{h2} top-level '## ' heading(s)" if secs.size != h2
+        sec_md = section_markdown(b, code)
+        secs.each_with_index { |s, i| ComponentRules.section(ctx, r, i, s, sec_md[i]) if s.is_a?(Hash) }
+        components(ctx, r, secs, sec_md) if ctx.comps
+        hero = meta["hero"]
+        errs << "#{r}: hero: must be a map such as {visual: name}" if hero && !hero.is_a?(Hash)
+        visuals(ctx, r, secs, hero.is_a?(Hash) ? hero : nil)
+      end
+
+      # visual: <name> on a section item or on hero: needs _includes/sections/<name>.html in the site or the theme (showcase).
+      def visuals(ctx, r, secs, hero)
+        items = secs.each_with_index.map { |s, i| [s, "sections[#{i}]"] }
+        items << [hero, "hero"] if hero
+        items.each do |s, where|
+          next unless s.is_a?(Hash) && s.key?("visual")
+          v = s["visual"].to_s
+          next ctx.errs << "#{r}: #{where}.visual must be an include name [a-z0-9_-] (got #{s['visual'].inspect})" unless v =~ /\A[a-z0-9][a-z0-9_-]*\z/
+          ctx.errs << "#{r}: #{where}.visual: _includes/sections/#{v}.html not found" unless [ctx.src, THEME].any? { |d| File.exist?(File.join(d, "_includes/sections/#{v}.html")) }
+        end
+      end
+
+      # Markdown of each top-level ## section (index i = sections[i]): [code spans/fences blanked, raw]
+      def section_markdown(b, code)
+        bl = b.lines
+        cl = code.lines
+        starts = cl.each_index.select { |k| cl[k] =~ /^##(?: |$)/ }
+        starts.each_with_index.map do |st, k|
+          raw = bl[st + 1...(starts[k + 1] || bl.size)].to_a.join
+          [cl[st + 1...(starts[k + 1] || cl.size)].to_a.join, raw]
+        end
+      end
+
+      def components(ctx, r, secs, sec_md)
+        errs = ctx.errs
+        secs.each_with_index do |s, i|
+          next unless s.is_a?(Hash) && s["c"]
+          spec = ctx.comps[s["c"]]
+          next errs << "#{r}: sections[#{i}] unknown component '#{s['c']}' (not in _data/components.yml)" unless spec
+          params = spec["params"] || {}
+          Slots.check_section(errs, r, i, s["c"], spec["slots"], sec_md[i])
+          (ctx.part_uses[s["c"]] ||= []) << r if spec.is_a?(Hash) && spec["parts"].is_a?(Array)
+          (s.keys - %w[c name visual]).each do |k|
+            next errs << "#{r}: sections[#{i}] #{s['c']}: unknown param '#{k}'" unless params.key?(k)
+            allowed = params[k].is_a?(Hash) && params[k]["allowed"]
+            errs << "#{r}: sections[#{i}] #{s['c']}.#{k}=#{s[k].inspect} not in #{allowed.inspect}" if allowed && !allowed.include?(s[k])
+          end
+          params.each do |k, p|
+            errs << "#{r}: sections[#{i}] #{s['c']}: missing required param '#{k}'" if p.is_a?(Hash) && p["required"] && !s.key?(k)
+          end
+        end
+      end
+    end
+  end
+end