jekyll-theme-modootoday 1.0.0

data/i18n/zh-TW.yml

@@ -0,0 +1,130 @@
+# jekyll-theme-modootoday interface strings (Traditional Chinese). Copy to _data/i18n/zh-TW.yml; keys are fixed, values are yours.
+language: 繁體中文
+direction: ltr
+skip: 跳至主要內容
+new_window: {hint: "在新視窗中開啟", open: "在新視窗中開啟"}
+callout: {note: 注意, tip: 提示, important: 重要, warning: 警告, caution: 小心}
+status: {available: 可用, partial: 部分支援, planned: 規劃中}
+task: {done: 已完成, open: 未完成}
+tabs: {label: 選項}
+toc: {label: 本頁內容}
+theme: {toggle: 深色模式}
+sidebar: {label: "文件"}
+page_actions: {label: "頁面操作", copy: "複製頁面", copy_ai: "複製給 AI", view: "以 Markdown 檢視", source: "來源"}
+breadcrumb: {label: 導覽路徑}
+nav: {label: 主選單, back_to_top: 回到頂端}
+pagination: {label: 換頁, prev: 上一頁, next: 下一頁}
+code: {copy: 複製, copied: 已複製, label: 程式碼, file: 檔案}
+table: {label: 表格}
+search: {label: 搜尋}
+page: {edit: 編輯此頁, updated: 最後更新}
+languages: {label: 語言}
+post: {date_format: "%Y年%-m月%-d日", author: 關於作者, related: 相關文章, share: 分享}
+fallback: {notice: 本頁尚未翻譯，以下顯示英文原文。}
+archive:
+  years: "年份"
+  tags: "標籤"
+  categories: "分類"
+  posts: "篇文章"
+  empty: "目前還沒有文章。"
+blog:
+  featured: "精選"
+  read_more: "閱讀全文"
+  reading_time: "閱讀約 [n] 分鐘"
+  by: "作者"
+  updated: "更新於"
+  newer: "較新文章"
+  older: "較舊文章"
+  related: "相關文章"
+  series: "系列"
+  series_part: "第 [n] 篇，共 [total] 篇"
+  share: "複製連結"
+  copied: "已複製連結"
+  feed: "訂閱源"
+  latest: "最新"
+  breaking: "快訊"
+  live: "直播"
+  correction: "更正"
+  sources: "來源"
+  more: "更多[section]"
+  authors: "作者"
+filetree: {label: 檔案結構}
+gallery: {close: 關閉}
+embed: {title: 嵌入內容}
+pricing: {recommended: 推薦}
+banner: {label: 公告}
+footnote: {back: 返回正文}
+progress: {label: 進度}
+subscribe: {email: 電子郵件地址, submit: 訂閱}
+params: {required: 必填}
+loading: {label: 載入中…}
+pages:
+  not_found: "找不到頁面"
+  not_found_text: "您要求的頁面不存在或已移動。"
+  gone: "頁面已移除"
+  gone_text: "此頁面已被刻意移除，不會再恢復。"
+  error: "發生問題"
+  error_text: "伺服器無法顯示此頁面。請稍後再試。"
+  home: "返回首頁"
+  moved: "此頁面已移動。"
+  moved_link: "前往新頁面"
+  search_hint: "輸入至少兩個字元開始搜尋。"
+layouts:
+  all: "全部"
+  filter: "篩選"
+  role: "角色"
+  client: "客戶"
+  year: "年份"
+  stack: "工具"
+  links: "連結"
+  location: "地點"
+  employment: "僱用類型"
+  salary: "薪資"
+  posted: "發布日期"
+  deadline: "截止日期"
+  apply: "應徵"
+  starts: "開始"
+  ends: "結束"
+  venue: "地點"
+  online: "線上"
+  agenda: "議程"
+  tickets: "取得門票"
+  calendar: "加入行事曆"
+  episode: "第 [n] 集"
+  season: "第 [n] 季"
+  duration: "長度"
+  listen: "收聽"
+  transcript: "逐字稿"
+  monthly: "月繳"
+  yearly: "年繳"
+  billing: "計費週期"
+  popular: "最受歡迎"
+  download: "下載"
+  version: "版本"
+  colors: "顏色"
+  assets: "素材"
+  send: "送出"
+  name: "姓名"
+  email: "電子郵件"
+  message: "訊息"
+  contact: "聯絡方式"
+  added: "新增"
+  changed: "變更"
+  fixed: "修正"
+  removed: "移除"
+  security: "安全性"
+  now: "現在"
+  next: "下一步"
+  later: "之後"
+  letters: "跳到字母"
+  lessons: "課程"
+  minutes: "[n] 分鐘"
+  module: "單元 [n]"
+  chapter: "第 [n] 章"
+  effective: "生效日期"
+  experience: "工作經歷"
+  education: "學歷"
+  skills: "技能"
+  present: "至今"
+  loading: "載入中…"
+  contents: "目錄"

data/lib/jekyll-theme-modootoday.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# md-components v1 — optional generator for Jekyll builds that can load plugins
+# (Jekyll 4 / GitHub Actions; NOT the classic GitHub Pages build, which only runs whitelisted plugins).
+# Enable with `plugins: [jekyll-theme-modootoday]`. For every Markdown page without a stub it adds the
+# same virtual page a hand-written stub would be:
+#   <name>.md.txt  {layout: twin, twin_of: <name>.md, permalink: /<name>/index.md}
+#   llms.txt / llms-full.txt at the root and in each /<lang>/ directory (layouts llms / llms-full)
+# so output is identical to the stub-based (GitHub Pages) setup. Existing pages/stubs always win.
+require "jekyll"
+
+module JekyllThemeModootoday
+  class Stub < Jekyll::PageWithoutAFile
+    def initialize(site, dir, name, data)
+      super(site, site.source, dir, name)
+      self.content = ""
+      self.data.merge!(data)
+      self.data["sitemap"] = false
+    end
+  end
+
+  class Generator < Jekyll::Generator
+    safe true
+    priority :lowest
+
+    def generate(site)
+      cfg = site.config["modootoday"] || {}
+      urls = site.pages.map(&:url).to_h { |u| [u, true] }
+      add = lambda do |dir, name, data|
+        page = Stub.new(site, dir, name, data)
+        next if urls[page.url]
+
+        urls[page.url] = true
+        site.pages << page
+      end
+      md = site.pages.select { |p| p.is_a?(Jekyll::Page) && !p.is_a?(Stub) && p.ext == ".md" && p.name != "README.md" }
+      raw = site.static_files.to_h { |f| [f.relative_path.sub(%r{\A/}, ""), true] }
+      if cfg.fetch("twins", true)
+        md.each do |p|
+          next if p.data["twin"] == false
+          next if raw[p.relative_path.sub(%r{\A/}, "")] # front-matter-less mode: the source itself is the twin
+
+          url = p.url.end_with?("/") ? "#{p.url}index.md" : p.url.sub(/\.html\z/, ".md")
+          d = File.dirname(p.path)
+          add.call(d == "." ? "" : d, "#{p.name}.txt", "layout" => "twin", "twin_of" => p.name, "permalink" => url)
+        end
+      end
+      return unless cfg.fetch("llms", true)
+
+      langs = (site.data["i18n"] || {}).keys.select { |l| Dir.exist?(File.join(site.source, l)) }
+      ([""] + langs).each do |l|
+        url = l.empty? ? "/" : "/#{l}/"
+        extra = l.empty? ? {} : { "lang" => l }
+        add.call(l, "llms.txt", { "layout" => "llms", "permalink" => "#{url}llms.txt" }.merge(extra))
+        add.call(l, "llms-full.txt", { "layout" => "llms-full", "permalink" => "#{url}llms-full.txt" }.merge(extra))
+      end
+    end
+  end
+end

data/lib/modootoday/check/a11y/content.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # Authoring-side screen-reader rules (WCAG 1.1.1, 1.3.1, 2.4.4, 4.1.1-style ids) on one page's Markdown,
+    # code already blanked. Errors: images with no alt, empty links, duplicate ids. Warnings: heading skips,
+    # vague link text, empty Markdown alt (decorative is allowed but should be deliberate).
+    module A11yContent
+      # English list mirrors Lighthouse SEO "link-text" (a hit there costs the SEO score).
+      VAGUE = /\A(click here|click this|here|right here|more|read more|learn more|see more|more info|more information|information|go|start|this|continue|link|여기|여기를 클릭|더 보기|こちら|ここ|詳しくはこちら)\z/i
+
+      module_function
+
+      def call(ctx, f, code)
+        r = ctx.rel(f)
+        images(ctx, r, code)
+        links(ctx, r, code)
+        headings(ctx, r, code)
+        ids(ctx, r, code)
+      end
+
+      def each_line(code, re)
+        code.each_line.with_index(1) { |l, n| l.scan(re) { yield n, Regexp.last_match } }
+      end
+
+      def images(ctx, r, code)
+        each_line(code, /<img\b(?![^>]*\balt=)[^>]*>/i) { |n, _| ctx.errs << "#{r}:#{n}: <img> without alt (screen readers read the file name); add alt=\"…\" or alt=\"\" if decorative" }
+        each_line(code, /!\[\s*\]\(/) { |n, _| ctx.warns << "#{r}:#{n}: image with empty alt ![](…) is treated as decorative; describe it unless it adds no information" }
+      end
+
+      def links(ctx, r, code)
+        each_line(code, /(?<!!)\[([^\]]*)\]\([^)]*\)/) do |n, m|
+          t = m[1].gsub(/[*_`]/, "").strip
+          next ctx.errs << "#{r}:#{n}: empty link text [](…) (announced as just \"link\"); write what it opens" if t.empty?
+          ctx.warns << "#{r}:#{n}: vague link text \"#{t}\"; name the destination so it makes sense out of context" if t.match?(VAGUE)
+        end
+        each_line(code, %r{<a\b[^>]*>\s*</a>}i) { |n, _| ctx.errs << "#{r}:#{n}: empty <a></a> link" }
+      end
+
+      # The layout supplies the page <h1> (title); content starts at ## and must not skip levels.
+      def headings(ctx, r, code)
+        prev = 1
+        code.each_line.with_index(1) do |l, n|
+          next unless (m = l.match(/^ {0,3}(#{"#"}{1,6})\s+\S/))
+          lv = m[1].size
+          ctx.warns << "#{r}:#{n}: heading jumps from h#{prev} to h#{lv}; screen-reader users navigate by level, do not skip" if lv > prev + 1
+          prev = lv
+        end
+      end
+
+      def ids(ctx, r, code)
+        seen = Hash.new(0)
+        each_line(code, /\bid=["']([^"']+)["']/) { |n, m| ctx.errs << "#{r}:#{n}: duplicate id=\"#{m[1]}\" (breaks labels, skip links and anchors)" if (seen[m[1]] += 1) == 2 }
+      end
+    end
+  end
+end

data/lib/modootoday/check/a11y/new_window.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "date"
+
+module Modootoday
+  module Check
+    # Links that open a new window, and sample links in demo pages.
+    # Source: raw <a target="_blank"> without rel="noopener" (error) or without the theme hint (warning; use
+    #   {: .mt-new-window} or new_window: true); a non-boolean new_window: (error); in a demo page (front matter
+    #   noindex: true) a link or url: that leaves the sample (root path, other site) or is empty (warning).
+    # Built site: target="_blank" without rel="noopener" (error) or without aria-describedby (warning); a demo page
+    #   link that resolves to the site root (warning: write "#").
+    module NewWindow
+      BLANK = /<a\b[^>]*\btarget=["']_blank["'][^>]*>/i
+
+      module_function
+
+      def call(ctx, f, text, code)
+        r = ctx.rel(f)
+        code.each_line.with_index(1) do |l, n|
+          l.scan(BLANK) do |a|
+            next if a.include?("mt-new-window") || a.include?("data-mt-new-window")
+            next ctx.errs << "#{r}:#{n}: target=\"_blank\" without rel=\"noopener\"; add it or use [text](url \"new-window\")" unless a =~ /\brel=["'][^"']*noopener/
+            ctx.warns << "#{r}:#{n}: new-window link without the spoken hint; use [text](url \"new-window\") or new_window: true"
+          end
+        end
+        fm = front(text)
+        text[/\A---\s*\n.*?\n---/m].to_s.scan(/\bnew_window:\s*([^,}\s]+)/) { ctx.errs << "#{r}: new_window: must be true or false (got #{$1})" unless %w[true false].include?($1) }
+        demo(ctx, r, text, code) if fm["noindex"] == true
+      end
+
+      def front(text)
+        m = text.match(/\A---\s*\n(.*?)\n---/m)
+        m ? (YAML.safe_load(m[1], permitted_classes: [Date, Time]) || {}) : {}
+      rescue Psych::Exception
+        {}
+      end
+
+      def demo(ctx, r, text, code)
+        urls = code.scan(/(?<!!)\[[^\]]*\]\(([^)]*)\)/).flatten + text.scan(/"url":\s*"([^"]*)"|\burl:\s*"?([^",}\s]*)/).flatten.compact
+        urls.each do |u|
+          next ctx.warns << "#{r}: demo link with no target; write \"#\" for a sample link" if u.strip.empty?
+          next unless u.start_with?("/") || u =~ %r{\A\w+://}
+          ctx.warns << "#{r}: demo link #{u} leaves the sample; write \"#\" unless it is the real destination"
+        end
+      end
+
+      def built(ctx)
+        Dir.glob("#{ctx.site}/**/*.html").each do |f|
+          t = File.read(f).gsub(%r{<pre\b.*?</pre>}m, "")
+          t.scan(BLANK) do |a|
+            next ctx.errs << "#{f}: target=\"_blank\" without rel=\"noopener\"" unless a =~ /\brel=["'][^"']*noopener/
+            ctx.warns << "#{f}: new-window link without aria-describedby hint" unless a.include?("aria-describedby")
+          end
+          next unless t.include?('name="robots" content="noindex"') && !t.include?('http-equiv="refresh"')
+          t.scan(/<main\b.*<\/main>/m).join.gsub(%r{<nav[^>]*breadcrumb.*?</nav>}m, "").scan(/<a\b[^>]*\bhref="([^"]*)"/) do |(h)|
+            ctx.warns << "#{f}: demo link #{h} resolves to the site root; write \"#\" for a sample link" if h =~ %r{\A(/[\w.-]+)?/#?\z}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/blog.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # Blog and news: modootoday.blog / modootoday.news settings, _data/authors.yml and post or listing front matter.
+    module Blog
+      VARIANTS = %w[list grid magazine].freeze
+      LISTING = %w[blog news author].freeze
+      POST = %w[post news-article].freeze
+
+      module_function
+
+      def call(ctx)
+        settings(ctx)
+        authors = load_authors(ctx)
+        ctx.mds.each { |f| page(ctx, f, authors) }
+      end
+
+      def settings(ctx)
+        mtc, errs = ctx.mtc, ctx.errs
+        return unless mtc.is_a?(Hash)
+        if mtc.key?("blog")
+          b = mtc["blog"]
+          k0 = "_config.yml: modootoday.blog"
+          return errs << "#{k0} must be a map" unless b.is_a?(Hash)
+          (b.keys - %w[variant per_page excerpt reading_time related share]).each { |k| errs << "#{k0}: unknown key '#{k}'" }
+          errs << "#{k0}.variant must be one of #{VARIANTS.join(', ')}" if b.key?("variant") && !VARIANTS.include?(b["variant"].to_s)
+          %w[per_page related].each { |k| errs << "#{k0}.#{k} must be a whole number" if b.key?(k) && !(b[k].is_a?(Integer) && b[k] >= 0) }
+          %w[excerpt reading_time share].each { |k| errs << "#{k0}.#{k} must be true or false" if b.key?(k) && ![true, false].include?(b[k]) }
+        end
+        return unless mtc.key?("news")
+        n = mtc["news"]
+        ok = n.is_a?(Hash) && (n.keys - %w[sections]).empty? && (!n.key?("sections") || n["sections"].is_a?(Array))
+        errs << "_config.yml: modootoday.news must be a map with sections: [category names]" unless ok
+      end
+
+      def load_authors(ctx)
+        f = "#{ctx.src}/_data/authors.yml"
+        return nil unless File.exist?(f)
+        data = (YAML.safe_load(File.read(f)) rescue (ctx.errs << "_data/authors.yml: YAML error"; nil))
+        return nil unless data
+        return (ctx.errs << "_data/authors.yml must map author ids to {name:, url:, page:, bio:}"; nil) unless data.is_a?(Hash)
+        data.each do |id, a|
+          next ctx.errs << "_data/authors.yml: #{id} must be a map with name:" unless a.is_a?(Hash) && a["name"].to_s != ""
+          ctx.errs << "_data/authors.yml: #{id}.url must be an http(s) URL" if a["url"] && a["url"].to_s !~ %r{\Ahttps?://\S+\z}
+          ctx.errs << "_data/authors.yml: #{id}.page must be a site path starting with /" if a["page"] && !a["page"].to_s.start_with?("/")
+        end
+        data
+      end
+
+      def page(ctx, f, authors)
+        fm = (Markdown.fm(File.read(f)) rescue nil)
+        return unless fm.is_a?(Hash)
+        r = ctx.rel(f)
+        layout = fm["layout"].to_s
+        post = r.split("/").include?("_posts") || POST.include?(layout)
+        if LISTING.include?(layout)
+          ctx.errs << "#{r}: variant must be one of #{VARIANTS.join(', ')}" if fm.key?("variant") && !VARIANTS.include?(fm["variant"].to_s)
+          ctx.errs << "#{r}: news_sections must be a list of category names" if fm.key?("news_sections") && !fm["news_sections"].is_a?(Array)
+        end
+        ctx.errs << "#{r}: layout: author needs author: <id from _data/authors.yml>" if layout == "author" && fm["author"].to_s.empty?
+        ids = Array(fm["authors"] || fm["author"]).map(&:to_s)
+        if authors && (post || layout == "author")
+          ids.each { |id| ctx.warns << "#{r}: author '#{id}' is not in _data/authors.yml (shown as plain text)" unless authors.key?(id) }
+        end
+        return unless post
+        %w[breaking live featured].each { |k| ctx.errs << "#{r}: #{k} must be true or false" if fm.key?(k) && ![true, false].include?(fm[k]) }
+        ctx.errs << "#{r}: sources must be a list" if fm.key?("sources") && !fm["sources"].is_a?(Array)
+      end
+    end
+  end
+end

data/lib/modootoday/check/build_output.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # 5. Built site: unconverted Markdown markers in HTML, and CSS that GitHub Pages' Ruby Sass
+    #    passes through or leaves undefined.
+    module BuildOutput
+      MARKS = /\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]/i
+
+      module_function
+
+      def residue(ctx)
+        Dir.glob("#{ctx.site}/**/*.html").each do |f|
+          t = File.read(f)
+          t = t.gsub(%r{<pre\b.*?</pre>}m, "").gsub(%r{<code\b.*?</code>}m) { |c| c.include?("status:") ? c : "" }
+          t.scan(MARKS) { ctx.errs << "#{f}: unconverted alert marker [!#{$1}]" }
+          ctx.errs << "#{f}: unconverted status badge (<code>status:)" if t =~ /<code[^>]*>status:/
+        end
+      end
+
+      def css(ctx)
+        errs = ctx.errs
+        files = Dir.glob("#{ctx.site}/**/*.css").sort
+        defined = {}
+        files.each do |f|
+          t = File.read(f)
+          errs << "#{f}: @use/@forward left in built CSS (Ruby Sass passes them through); use @import" if t =~ /@(use|forward)\s/
+          errs << "#{f}: @supports selector() in built CSS" if t =~ /@supports\s+(not\s+)?selector\(/
+          errs << "#{f}: custom property with a literal Sass variable (write --x: \#{$var})" if t =~ /--[\w-]+:\s*\$/
+          t.scan(/(--mt-[\w-]+)\s*:/) { defined[$1] = true }
+        end
+        Dir.glob("#{ctx.site}/**/*.html").each { |f| File.read(f).scan(%r{<style[^>]*>(.*?)</style>}m) { $1.scan(/(--mt-[\w-]+)\s*:/) { defined[$1] = true } } }
+        files.each do |f|
+          File.read(f).scan(/var\((--mt-[\w-]+)/).flatten.uniq.each { |v| errs << "#{f}: var(#{v}) is never defined" unless defined[v] }
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/built_parts.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # 4b. Registered parts exist in the built HTML of the pages that use the component (needs
+    # Nokogiri; skipped without it). Attributes that component scripts add at runtime (role=, aria-*)
+    # are checked after scripts run by docs QA.
+    module BuiltParts
+      RUNTIME_PART = /\[(role|aria-)/
+
+      module_function
+
+      def nokogiri?
+        require "nokogiri"
+        true
+      rescue LoadError
+        false
+      end
+
+      def call(ctx)
+        return unless ctx.comps.is_a?(Hash) && nokogiri?
+        docs = {}
+        ctx.part_uses.each do |c, pages|
+          secs = pages.uniq.flat_map do |pg|
+            r = pg.delete_suffix(".md")
+            cand = File.basename(r) == "index" ? ["#{ctx.site}/#{r}.html"] : ["#{ctx.site}/#{r}.html", "#{ctx.site}/#{r}/index.html"]
+            h = cand.find { |x| File.exist?(x) }
+            h ? (docs[h] ||= Nokogiri::HTML(File.read(h))).css(%(section[data-c="#{c}"])).to_a : []
+          end
+          next if secs.empty? # page not built under its source path (custom permalink): nothing to compare
+          ctx.comps[c]["parts"].each do |sel|
+            next unless sel.is_a?(String) && !sel.match?(RUNTIME_PART)
+            found = secs.any? { |sec| (sec.matches?(sel) rescue false) || !(sec.css(sel) rescue []).empty? }
+            ctx.errs << "_data/components.yml: #{c}.parts: '#{sel}' not found in the built HTML of #{pages.uniq.sort.join(', ')}" unless found
+          end
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/cli.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # Command line: usage, --help/--version, running the rule groups in order, reporting.
+    module CLI
+      USAGE = "usage: modootoday-check SRC SITE [--twins] [--github-pages[=VERSION]] [--gh] [--strict] [--schema-recommended] [--i18n] [--i18n-init=LANG,...]"
+      # Single source for --help and the README "Commands" table (script/readme-commands, test/project/readme_test.rb).
+      OPTIONS = [
+        ["SRC SITE", "always: front matter, forbidden syntax, alerts, fence info strings, `status:`/`tag:`/`kbd:` values (`since:` is rejected), `sections:` count, `_data/i18n/<lang>.yml` keys against the default language and translated pages against default-language pages, `_data/components.yml` (keys, slot contract counts per section, `parts` against `api.md` and the built HTML), Sass/CSS rules, unconverted markers in the build, schema.org JSON-LD in the build (valid JSON, vocabulary, required properties per type, absolute URLs, ISO 8601 dates, one graph per page, agreement with Open Graph)"],
+        ["--twins", "every page has a byte-identical Markdown twin, per-language `llms.txt` and `llms-full.txt`"],
+        ["--github-pages[=VERSION]", "`Gemfile.lock` pins `github-pages` VERSION (default 232)"],
+        ["--schema-recommended", "also warn about schema.org properties Google Search recommends (author, image, dates, ...) that a JSON-LD node lacks"],
+        ["--strict", "warnings fail the run"],
+        ["--i18n", "`_data/i18n/<lang>.yml` against the theme registry (`i18n/en.yml` in the gem): unknown keys, `%{name}` placeholder mismatches, and pages marked `translation: pending`"],
+        ["--i18n-init=LANG,...", "copy the theme's catalogs (`i18n/<lang>.yml`, 23 languages) into `SRC/_data/i18n/` as a starting point for overrides (optional; the theme already uses them), and list keys an existing catalog lacks"],
+        ["--gh", "also render each page with `gh api markdown` (network, `gh` login)"],
+        ["--help, -h", "print usage and options (`--help=markdown` prints the README table)"],
+        ["--version", "print the rules version"],
+      ].freeze
+      # Rule groups in report order.
+      RULES = [Registry, SiteConfig.method(:source_mode), Pages, Layouts, I18n, Registry.method(:i18n_keys), BuiltParts,
+               BuildOutput.method(:residue), NewWindow.method(:built), StructuredData, Stylesheets, BuildOutput.method(:css), SiteConfig, Blog, GithubPages, Twins, GhRender].freeze
+
+      module_function
+
+      def run(argv)
+        return help(argv.find { |a| a == "-h" || a.start_with?("--help") }) if argv.any? { |a| a == "-h" || a.start_with?("--help") }
+        return (puts "modootoday-check (md-components v1)"; 0) if argv.include?("--version")
+
+        pos = argv.reject { |a| a.start_with?("--") }
+        src, site = pos[0]&.chomp("/"), pos[1]&.chomp("/")
+        abort USAGE unless src && site
+        ctx = Context.new(src, site, argv)
+        RULES.each { |r| r.call(ctx) }
+        report(ctx)
+      end
+
+      def help(h)
+        if h == "--help=markdown"
+          puts "| Option | Checks |", "|---|---|"
+          OPTIONS.each { |o, d| puts "| `#{o}` | #{d.gsub("|", "\\|")} |" }
+        else
+          puts USAGE, "", "options:"
+          OPTIONS.each { |o, d| puts format("  %-26s %s", o, d.delete("`")) }
+          puts "", "exit status: 0 no problems, 1 problems found or bad usage"
+        end
+        0
+      end
+
+      def report(ctx)
+        errs, warns = ctx.errs, ctx.warns
+        errs.concat(warns.map { |w| "#{w} [strict]" }) if ctx.option?("--strict")
+        warns.each { |w| warn "warning: #{w}" } unless ctx.option?("--strict")
+        puts errs
+        puts errs.empty? ? "md-components check: OK (#{ctx.mds.size} pages)" : "md-components check: #{errs.size} problem(s)"
+        errs.empty? ? 0 : 1
+      end
+    end
+  end
+end

data/lib/modootoday/check/component_rules.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # Values the transforms need (Rule 2b): inline `file:`, `progress:`, `embed:` code spans, and per-section
+    # content rules for c: gallery, quote, pricing and subscribe that slot counts cannot express.
+    module ComponentRules
+      SKELETONS = %w[text card image avatar row].freeze
+
+      module_function
+
+      def inline(ctx, r, b)
+        errs, lines = ctx.errs, Markdown.strip_fences(b).lines
+        text = lines.join
+        text.scan(/`progress:([^`]*)`/) do |(v)|
+          errs << "#{r}: `progress:#{v}` must be a whole number from 0 to 100" unless v =~ /\A(100|[1-9]?\d)\z/
+        end
+        text.scan(/`skeleton:([^`]*)`/) do |(v)|
+          errs << "#{r}: `skeleton:#{v}` must be one of #{SKELETONS.join(', ')}" unless SKELETONS.include?(v)
+        end
+        text.scan(/`embed:([^`]*)`/) do |(v)|
+          errs << "#{r}: `embed:#{v}` must be an https:// URL, optionally followed by a title" unless v =~ %r{\Ahttps://[^\s"<>]+( [^"<>]+)?\z}
+        end
+        rl = b.lines
+        rl.each_with_index do |l, i|
+          next unless (fm = l.strip.match(/\A`file:([^`]*)`\z/))
+          nxt = rl[(i + 1)..].to_a.find { |x| x.strip != "" }.to_s
+          errs << "#{r}: `file:#{fm[1]}` must be alone in a paragraph right before a fenced code block" unless nxt =~ /\A\s*(```|~~~)/ && fm[1] !~ /\s/
+        end
+      end
+
+      def section(ctx, r, i, s, md)
+        errs, (m, _raw) = ctx.errs, md || ["", ""]
+        w = "#{r}: sections[#{i}] #{s['c']}"
+        case s["c"]
+        when "gallery"
+          imgs = m.scan(/^[-*+]\s+(.*)$/).flatten
+          errs << "#{w}: each list item must be one image ![alt](src) with alt text" unless imgs.all? { |x| x.strip =~ /\A!\[[^\]\n]*\S[^\]\n]*\]\([^)\s]+\)\z/ }
+          errs << "#{w}: write the image list without blank lines between items" if m =~ /^[-*+]\s.*\n\s*\n[-*+]\s/
+        when "quote"
+          errs << "#{w}: needs a > quote whose last line is the attribution (> — Name)" unless m =~ /^>\s*— \S/
+        when "pricing"
+          n = m.scan(/^###(?: |$)/).size
+          rec = s["recommended"]
+          errs << "#{w}: recommended: must be a plan number from 1 to #{n}" if s.key?("recommended") && !(rec.is_a?(Integer) && rec.between?(1, n))
+        when "subscribe"
+          act = ctx.mtc.is_a?(Hash) && ctx.mtc.dig("subscribe", "action")
+          ctx.warns << "#{w}: no form is shown until _config.yml sets modootoday.subscribe.action" unless act
+          errs << "#{w}: modootoday.subscribe.action must be an https:// URL" if act && act.to_s !~ %r{\Ahttps://\S+\z}
+        end
+      end
+    end
+  end
+end

data/lib/modootoday/check/context.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Modootoday
+  module Check
+    # What every rule reads (source and site paths, options, parsed config and data) and the
+    # error/warning lists every rule writes to. Loaded once per run.
+    class Context
+      SKIP = %r{(^|/)(_site|_includes|_layouts|_data|vendor|node_modules)/}
+
+      attr_reader :src, :site, :argv, :errs, :warns, :mds, :comps, :i18n, :site_cfg, :mtc
+      attr_accessor :part_uses
+
+      def initialize(src, site, argv)
+        @src, @site, @argv = src, site, argv
+        @errs, @warns = [], []
+        @part_uses = {} # component -> source pages that use it (parts are looked up in their built HTML)
+        comps_file = "#{src}/_data/components.yml"
+        @comps = File.exist?(comps_file) ? (YAML.safe_load(File.read(comps_file)) || {}) : nil
+        @i18n = Dir.glob("#{src}/_data/i18n/*.yml").to_h { |f| [File.basename(f, ".yml"), YAML.safe_load(File.read(f)) || {}] }
+        cfg_file = "#{src}/_config.yml"
+        @site_cfg = (File.exist?(cfg_file) && ((YAML.safe_load(File.read(cfg_file), permitted_classes: [Date, Time]) rescue nil) || {})) || {}
+        @mtc = @site_cfg["modootoday"] || {}
+        # directories listed in the site's exclude: are not pages (e.g. a nested example site)
+        excl = Array(@site_cfg["exclude"]).map { |e| e.to_s.chomp("/") }.select { |e| File.directory?("#{src}/#{e}") }
+        @mds = Dir.glob("#{src}/**/*.md").reject { |f| f.delete_prefix(src) =~ SKIP }.sort
+        @mds.reject! { |f| excl.any? { |e| f.start_with?("#{src}/#{e}/") } }
+      end
+
+      def option?(name) = argv.include?(name)
+      def rel(f) = f.delete_prefix("#{src}/")
+      def skipped?(f) = f.delete_prefix(src) =~ SKIP
+
+      # modootoday.twins: source = front-matter-less mode: a page without front matter is rendered by
+      # jekyll-optional-front-matter AND copied raw to its own path, which then is its twin.
+      def source_mode? = mtc.is_a?(Hash) && mtc["twins"] == "source"
+
+      # The language of a page path ("ko/guide" -> "ko") when that language has an i18n file.
+      def lang_of(r) = (r.split("/").first if r.include?("/") && i18n.key?(r.split("/").first))
+    end
+  end
+end

data/lib/modootoday/check/gh_render.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Modootoday
+  module Check
+    # --gh: render each page with `gh api markdown` (needs gh auth and network).
+    module GhRender
+      module_function
+
+      def call(ctx)
+        return unless ctx.option?("--gh")
+        ctx.mds.each do |f|
+          out, st = Open3.capture2("gh", "api", "markdown", "-f", "mode=gfm", "-f", "text=#{Markdown.body(File.read(f))}")
+          next ctx.errs << "#{ctx.rel(f)}: gh api failed" unless st.success?
+          ctx.errs << "#{ctx.rel(f)}: GitHub shows ': ' definition marker" if out =~ /<p>: /
+        end
+      end
+    end
+  end
+end