jekyll-theme-modootoday 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b931dde6d0122d8fb5097470c94364baa602729b9b3efc16f44b8a54c659fca
+  data.tar.gz: 21ce8fd5dcc6cd840baf3982caf652dd01cdc8d2385e1903031c7d14d3825a88
+SHA512:
+  metadata.gz: bac73d7449a1a71b3b202286f4c27107280262d9919bb8f0de64d4439a16749d1f76ef9aa3bb5f155d8fcd6c0e48f0a46f5adeff43643b34801e2fc16b378823
+  data.tar.gz: 73b2d9bb5bc3198989ecd6b883cb73b707a957aac39c24d0c8d02df9cd08af1c345699d06a7ac168163a66d257586e67548925575b917df1905e5494ef255ea1

data/CHANGELOG.md

@@ -0,0 +1,182 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+The content rules have their own version header (`md-components v1`) in [RULES.md](RULES.md).
+
+## [1.0.0] - Unreleased
+
+First public release. Nothing was published on RubyGems before 1.0.0. The changes directly below were made last; [Pre-release history](#pre-release-history) lists the earlier development milestones (0.1 to 0.5), which were internal and never released.
+
+### Added
+- **Links that open a new window:** `new_window: true` or `target: _blank` on nav items, cards, buttons, link cards, directory items, pricing calls to action and footer links, `[text](url "new-window")` on Markdown links (portable; kramdown `{: .mt-new-window}` also works), and `modootoday.external_links.new_window: true` for every external link. Each gets `rel="noopener noreferrer"`, a translated hidden hint (`new_window.hint`, in all 23 catalogs) through `aria-describedby`, and a CSS-only arrow (`external_links.icon: false` hides it). No script, so a strict CSP keeps working. Bare `#` sample links now stay `#` instead of pointing at the site root.
+- **Blog and news demos:** blog index, blog post, news front page, news article and yearly archive (`layout: archive` with `archive: years`) demo pages in en/ko/ja, each with an Open in new window link. Demo pages are `noindex` and left out of the sitemap, search and sidebar.
+- **Screen readers:** search results are announced (`aria-live`). `modootoday-check` reports `<img>` without `alt`, empty links and duplicate ids as errors, and empty Markdown alt, vague link text ("click here") and skipped heading levels as warnings. The [Accessibility page](docs/accessibility.md) has an authoring checklist (images, links, headings, tables, ids, language).
+- **Accessibility:** safe areas on notched phones (`viewport-fit=cover` with `--mt-safe-top|right|bottom|left` padding the header, side gutters and footer; `modootoday.viewport_fit: auto` opts out), `theme-color` meta tags matching the light and dark background (`modootoday.theme_color`), 44 px touch targets and 16 px search text on touch screens, forced-colors borders on icon buttons and search. Keyboard: `/` and `Ctrl`/`Cmd`+`K` focus search, arrow keys and `Esc` in results, wide code blocks and tables become labelled focusable regions, focus rings drawn inside tabs and scroll regions. Labels `code.label` and `table.label` ship in all 23 catalogs. See the [Accessibility page](docs/accessibility.md).
+- **Docs site structure:** pages are grouped by context into Guides, Components, Layouts, Recipes and Reference, each with an index page. The sidebar collapses groups you are not reading and shows at most three levels. Old page addresses such as `/install/` now live under their section, such as `/guides/install/`.
+- **Structured data:** every page gets one schema.org JSON-LD `@graph` (WebSite, publisher, WebPage subtype per layout, main entity, BreadcrumbList) with stable `@id`s, `inLanguage`, ISO 8601 dates and absolute URLs, printed only when `url:` is set. Configure with `modootoday.schema` (`publisher`, `search_url`, `layouts`), extend per page with front matter `schema:`, turn off with `schema: false`. `modootoday-check` validates the blocks offline against the schema.org vocabulary and Google's required properties (`--schema-recommended` for recommended ones). See the Structured data docs page.
+- **Per-component stylesheets:** the CSS is split into a core sheet (under 24 KiB) plus context sheets (`doc`, `search`, `loading`; the blog bundle stays separate) and one sheet per section component (each under 2 KiB). A page links only what it uses. `modootoday.css: bundle` links one combined sheet instead.
+- **Content components:** file tree, details, FAQ (with FAQPage data), parameter table, link cards, quote, gallery (`:target` lightbox, no script), pricing (`recommended`), subscribe form; inline code titles (`file:`), progress (`progress:`), embeds (`embed:`), accessible footnote back-links; site banner and back-to-top link. Each has en/ko/ja docs examples, i18n keys in all 23 catalogs, a checker rule and a slot entry.
+- **Loading and skeleton UI:** CSS-only spinner, thin top bar and skeletons (text, card, image, avatar, row) with `role="status"` and a translated label, reserved aspect-ratio placeholders (`.mt-ratio-*`, embeds, gallery thumbnails, sized images), reduced-motion, forced-colors and RTL support, in an optional `loading` sheet.
+- Tabs and accordion scripts load only on pages that use them.
+- **Page shells:** layouts `minimal`, `wide`, `home`, `error` (`status: 404 | 410 | 500`), `redirect` (`redirect_to:`) and `search` (no-JS fallback form, `modootoday.search.fallback`). They load the optional `modootoday-pages.css` bundle through `mt_bundle`; core CSS and JS do not grow. Labels in all 23 catalogs; `modootoday-check` checks their front matter. See [Layouts](docs/layouts/shells.md).
+- **Detail layouts:** `project`, `case-study`, `job`, `event` and `episode` on one `detail` engine: header with kicker and lead, a facts list from front matter, the body and one call to action (Apply, Tickets with an `.ics` file, or `cta:`); episodes get the browser's own audio player. JSON-LD main entity from the same front matter: `CreativeWork`, `Article`, `JobPosting` (hiring organization = publisher, `employmentType`, `validThrough`, place or remote with `applicantLocationRequirements`, `baseSalary`), `Event` (place and/or `VirtualLocation`, attendance mode, offers) and `PodcastEpisode`; `schema:` overrides any property. Styles are the optional `modootoday-detail.css` bundle; `modootoday-check` checks the front matter. See [Detail pages](docs/layouts/detail/index.md).
+- **Marketing layouts:** `feature`, `pricing`, `download`, `brand`, `links` and `contact` with the optional `modootoday-marketing.css` bundle and no JavaScript. Pricing reuses the pricing component cards with a CSS-only Monthly/Yearly radio switch; brand swatches are SVG fills (no inline style under CSP); `links` drops the site chrome and prints a `ProfilePage` whose Person/Organization `sameAs` lists the links; `contact` prints a `ContactPage` and a labelled form posting to an external https `form.action`. A new `mt_css:` layout list lets a layout load component sheets. `modootoday-check` checks plans, colors, downloads, links and the form. See [Marketing pages](docs/layouts/marketing/index.md).
+- **Docs extras:** `reference` (member list with signatures and anchors, TechArticle), `changelog` (releases with Added/Changed/Fixed/Removed/Security in the page language), `roadmap` (now/next/later columns), `glossary` (sorted terms with a letter bar, DefinedTermSet), `hub` (card grid, CollectionPage with `hasPart`), `course` (modules, lessons and total time, Course with provider and `timeRequired`) and `book` (cover, author, ISBN, chapters, Book). Styles are the optional `modootoday-docs-extra.css` bundle; `modootoday-check` checks statuses, terms, cards, minutes, pages and ISBNs. See [Docs extras](docs/layouts/docs-extra/index.md).
+- **Documents:** `legal` (required `effective` date, `updated`, `version`, contents list; `datePublished`/`dateModified`; in the pages bundle) and `resume` (print-first CV in its own `modootoday-resume.css` bundle with `@page` margins and h-card markup; ProfilePage whose Person gets `worksFor`, `alumniOf` and `knowsAbout`). Both hide the site chrome when printed. See [Documents](docs/layouts/documents/index.md).
+- **Recipes by site type:** product, company, documentation, personal, community and system page sets in en/ko/ja under `docs/recipes/`.
+- **Directory layouts:** `directory` with presets `portfolio`, `team`, `jobs`, `events`, `sponsors` and `integrations`: a card grid from `items:` or `data:` (a file in `_data`), with a filter made of radio buttons that needs no JavaScript (`filter: <field> | false`, up to 12 values), round team photos, event date tiles with an `.ics` file in a `data:` link, and schema.org `ItemList` of `Person` or `Event` (online events get `VirtualLocation`). Styles are the optional `modootoday-directory.css` bundle; `modootoday-check` checks the items. See [Directory layouts](docs/layouts/directory/index.md).
+- **Doc sidebar:** `doc` pages get a sidebar built from the nav groups (`modootoday.sidebar: auto | true | false`, default `auto` = on when the nav has groups; `sidebar: false` in front matter). From 64rem it is a sticky column; below, a collapsed menu above the page shows the current group, replacing the horizontally scrolling link row. With a sidebar the header drops the flat group links.
+- **Page actions:** on pages with a Markdown twin, a menu offers View as Markdown, Copy page and Copy for AI (source URL, then the Markdown). `modootoday.page_actions: false`, front matter `page_actions: false`, or leaving `page-actions` out of `components` removes it. Labels (`page_actions.*`, `sidebar.label`) ship in all 23 catalogs.
+- `color_scheme: auto-dark` and `auto-light` start in that scheme and keep the toggle; the start is printed as `data-theme` in the HTML, so there is no flash and no `head-custom.html` script.
+- **Blog and news layouts:** `blog` (paginated index of post cards with `variant: list | grid | magazine`, featured first, per-language), `news` (front page with lead, secondary stories and `news_sections` blocks), `news-article` (dateline, deck, breaking/live badges, correction, sources), `author` (profile and posts) and `feed` (per-language Atom). The `post` layout gains a byline from `_data/authors.yml` (`author:` or `authors:`), published/updated dates, reading time, cover image, series box, previous/next, related posts, a share button, `BlogPosting`/`NewsArticle` JSON-LD and OG `article:*` tags. Settings live under `modootoday.blog` and `modootoday.news`; labels are translated in all 23 catalogs. Liquid only (classic GitHub Pages and Jekyll 4). The styles (`modootoday-blog.css`) and `share.js` are a separate optional bundle loaded only by these layouts, with their own size budgets; the core bundles are unchanged. `modootoday-check` validates the settings, `_data/authors.yml` and post front matter. See [Blog and news](docs/layouts/blog-news.md).
+- **Result container for CTA sections:** when a `c: cta` section holds an element with `data-mt-result`, the `.mt-cta` box (centering, gradient, border) goes on that element instead of the whole section. Sections without one render exactly as before. The docs Components page uses it, so the Buttons example card matches the other cards and only its result is framed.
+- `visual: <name>` on a `sections:` item and `hero: {visual: <name>}` render a site-provided `_includes/sections/<name>.html`; `modootoday-check` fails when it is missing.
+- `full_width: true` front matter removes the reading-column width of `main` (`.mt-main-full`).
+- Breadcrumb: the home crumb uses the home page `short_title:` when set.
+- `modootoday-check` accepts tool region markers alone on a line (`<!-- spec:toc:begin -->` / `<!-- spec:toc:end -->`); other HTML comments are still errors.
+- `modootoday.hreflang` keeps `hreflang` alternates when `seo: false`.
+- **Icons:** `modootoday/brand/icon.html` renders inline SVG icons (`name`, `size`, `label`, `class`) in `currentColor`, decorative unless labelled, with directional icons mirrored in RTL. Every former text, emoji or CSS-drawn icon (language globe, theme sun/moon, search, nav chevron and external link, breadcrumb separators, alert types, copy/check, edit link, previous/next, tag and category badges) now uses it. See the [API page](docs/reference/api.md#stable-names).
+- **Logo and favicon:** `modootoday.logo: brand | <path>` shows the modootoday mark (or your image) before the site title through the overridable `modootoday/brand/logo.html`; `modootoday.favicon: brand | <path>` links an SVG, 32 px PNG and Apple touch icon. The docs site uses both.
+- **Built-in translations:** set `lang:` and the theme's labels (skip link, navigation, callouts, status badges, table of contents, pagination, code copy, search, language menu) are localized for 23 languages with nothing to copy, on GitHub Pages and Jekyll 4. A site `_data/i18n/<lang>.yml` overrides individual keys; unknown languages use English. `modootoday/t.html` prints a label by key. `modootoday-check --i18n-init` copies a catalog to edit, and `--i18n` checks keys and placeholders; `.yaml` catalogs are rejected.
+- **Language switcher:** `modootoday.language_switcher: header | footer` renders a theme-level switcher from `languages` (the same alternates as `hreflang`), linking to the translation of the current page or that language's home page. In the header it is a globe button with a `<details>` dropdown (localized accessible name, `aria-current`, `lang`/`hreflang` on each link) that keeps the same width however many languages there are; in the footer, a list. Nothing renders with fewer than two languages. `modootoday/lang-switch.html` can be included from a custom footer. The docs site uses the header menu in place of its footer list.
+- `menu.js` (small, CSP-safe): Esc closes a `<details class="mt-menu">` and returns focus, arrow keys move between items, an outside click or opening another menu closes it. Used by the language menu and the nav "More" group.
+- On screens under 30rem, search takes its own row under the site title.
+- **Tag and category archives:** the `archive` layout (`archive: tags | categories`) and the `modootoday/archive.html` include list terms with post counts and one anchored section per term, filtered by language (`archive_lang: all` for every post). With `modootoday.archive: {tags: /tags/, categories: /categories/}` the `post` layout adds a footer linking each tag and category. Liquid only, so it works on classic GitHub Pages; one page per taxonomy, not per term. `modootoday-check` validates `modootoday.archive` and skips twins for `_posts/`. The post and archive styles ship in the optional `modootoday-blog.css` bundle (loaded by the `post`, `archive` and blog/news layouts; `blog_css: true` opts any other page in, for example one that uses the `modootoday/archive.html` include). See the [API page](docs/api.md#posts-and-archives).
+- Slot contract: `slots:` in `_data/components.yml` declares the named parts of a section (`lead`, `items`, `panels`, `actions`, `code`, `figures`) with `required`/`min`/`max`; `modootoday-check` counts them per section. Markup is unchanged. See the [API page](docs/api.md#slot-contract).
+- Slot contract: `slots:` can be a list of alternative forms (a section passes when it satisfies one; `steps` and `timeline` accept a list or `###` panels), and `parts:` declares the stable selectors of a component, checked against the component structure table of `api.md` when the site has one. See the [API page](docs/api.md#slot-contract).
+- **Right-to-left:** `dir="rtl"` from `lang` for RTL languages, `direction:` front matter override, logical properties in component CSS, LTR code inside RTL text, RTL-aware tab arrow keys, and an RTL kitchen sink checked in docs QA.
+- [Math and diagrams](docs/recipes/math-diagrams.md) guide (en, ko, ja): KaTeX and Mermaid under a strict CSP, rendered at build time or self-hosted. The theme bundles neither.
+- Japanese documentation on the docs site (`/ja/`), with hreflang, Markdown twins, `llms.txt` and a footer language switcher on the docs site.
+- Guide pages in Korean and Japanese on the example site, with twins and `llms.txt` entries.
+
+### Fixed
+- Pages no longer flash on load: the header search box and light/dark toggle are drawn from the first paint instead of popping in when their scripts run (the header used to jump, most visibly after clicking the logo), and the toggle icon matches the colour scheme immediately. QA checks the first frames after a logo click.
+- Tabs: the tab list no longer shows a vertical scrollbar (the active-tab underline overflowed it by 1px); it scrolls sideways only, and the focus ring sits inside each tab. QA fails on any tabs scrollbar at 360/768/1280px.
+- Search on a page whose language has no other pages (the RTL sample) now prefers the site's default language instead of every language.
+- The table of contents sits a fixed gap after the text at wide widths instead of being pushed to the far edge; the narrow-screen menu row fades at its end to show it scrolls; inline code in cards no longer breaks inside a file name; figures are dimmed slightly in dark mode.
+- The header site title links to the current language's home (`/<lang>/`, with `baseurl`) instead of the default-language root, for every language in `languages` including right-to-left ones; it falls back to the site root when that language has no home page.
+
+### Changed
+- **Previous/next follows the nav:** pagination walks `_data/nav` in order, a group's own page and then its items, instead of top-level entries only.
+- Doc-only includes live under `_includes/modootoday/doc/` (`pagination.html`, `sidebar.html`, `page-actions.html`, `twin.html`); the page-actions script is part of `code-copy.js`.
+- **One prefix, no aliases:** every class and custom property is `mt-*` / `--mt-*`; the `md-*` classes, `--md-*` properties, `$mt-md-aliases` and the checker's alias warnings are gone (they were never released). The skip-link target is `#mt-main`.
+- Theme includes and scripts live under `modootoday/`: `_includes/modootoday/markdown/{components,sections,raw-body,llms-pages}.html` and `assets/js/modootoday/tabs.js` (were `_includes/md-*.html` and `assets/js/md-tabs.js`); tab ids are `mt-tabs-*`.
+- `since:` version badges are not part of 1.0: they are no longer rendered and `modootoday-check` reports any `` `since:…` `` code span as an error.
+- The docs site and the README quick start build CSS with `sass: {style: compressed}` (Ruby Sass 3.7 and Dart Sass): the stylesheet is about 10 % smaller with identical rendering. `qa/css-sizes.rb` reports the size of the core and each component.
+- Header, navigation, search, theme toggle and code copy use logical properties, so they mirror in right-to-left pages; the code Copy button sits at the inline end and never covers code. The docs navigation lists the math and diagrams guide.
+- `modootoday-check` validates `_data/components.yml` itself: unknown keys in a component entry (allowed: `params`, `i18n`, `slots`, `parts`) or a slot rule (allowed: `required`, `min`, `max`), non-integer or negative counts and `min` greater than `max` are errors, reported once per registry instead of once per section. Registries that use only these keys are unaffected.
+- `modootoday-check` also looks up each `parts:` selector in the built HTML of the pages that use the component (inside its `section[data-c]`), when Nokogiri is available as it is under `github-pages`; parts added by component scripts (`role=`, `aria-*`) are checked after the scripts run by the docs site QA. The kitchen sink now shows `timeline` in both forms.
+- The `caution` token is now rose (`#b8174a` light, `#ff7b9c` dark) instead of red, so caution alerts no longer read as the orange-red brand link colour. New primitives `--mt-p-rose-400/600`.
+- Search results show the current language first, title matches before body matches, and a muted text snippet; on narrow screens the results panel spans the header width.
+- Footnotes are rendered after the last section instead of inside it (they no longer land in a call-to-action card).
+- On screens under 48rem, code blocks with a Copy button start below the button so it never covers the first line.
+- The rules are final: `RULES.md` and every file header now say `md-components v1` instead of `md-components v1 (draft)`. No rule changed.
+- The public API is documented on the docs site; changes are listed in this CHANGELOG.
+- `modootoday-check` also warns on `md-*` classes and `var(--md-*)` in the site's own includes, layouts, CSS and pages (code is ignored), not only in Sass.
+
+### Pre-release history
+
+Internal development milestones, never released. They are all part of 1.0.0.
+
+#### Release readiness
+
+##### Changed
+- Layout: header, content and footer share one alignment line; footer text no longer truncates; kitchen sink sections are separated by rules; aside TOC lists h2 only; dark `muted`/`card` raised to `#1a212b` for contrast; footnotes styled.
+
+##### Added
+- Brand colour: `primary` and `ring` use the 모두의오늘 brand red (light `#b94022`, dark `#e96346`); new semantic `brand` token (`#d94925`) for the logo mark. Nav entries with `items:` render as a dropdown group at 64rem and up and as flat links below.
+- Head metadata on by default: canonical URL (when `url` is set), `hreflang` from `modootoday.languages`, Open Graph and Twitter card tags; `modootoday.seo: false` turns them off for sites that use jekyll-seo-tag. Sitemap and feed stay opt-in plugins (`modootoday.feed: true` adds the feed link).
+- `modootoday.csp: strict` loads the pre-paint script from `assets/js/modootoday/theme-init.js`, so no inline script is needed; CSP guide.
+- Optional "Last updated" (`last_modified_at`) and edit link (`modootoday.edit_url`, `edit: false` per page).
+- Checker validates `seo`, `feed`, `csp`, `languages` and `edit_url`, and warns on `md-*` names in site Sass.
+- Docs: public API, migrate/upgrade guide, CSP guide, roadmap with non-goals (RTL, math, Mermaid), 404 page; the docs site uses sitemap, `hreflang` and edit links.
+- SECURITY.md (private vulnerability reporting), CODE_OF_CONDUCT.md (Contributor Covenant 2.1), issue and pull request templates, Dependabot for Actions, Bundler and npm, RELEASING.md.
+- CI job for the Jekyll 3.9 floor.
+
+
+#### Milestone 0.5
+
+##### Added
+- Front-matter-less twin mode (`modootoday.twins: source`): on classic GitHub Pages, `jekyll-optional-front-matter` renders a page without front matter and copies the raw file to its own path, which becomes the twin without a stub. The `default` layout and `llms.txt` link to it; the generator skips such pages; the checker verifies the rendered page and the byte-identical raw copy and rejects `remove_originals`, `require_front_matter` and redundant stubs. Example site in `example/source-mode/`, built in CI on github-pages and Jekyll 4.
+- Checker: `modootoday.twins` value check; directories listed in `exclude:` are skipped.
+- Visual refresh: wide container (`container` 76rem) with a sticky, blurred header and a right-hand sticky table of contents from 64rem (a collapsible "On this page" below that); site footer; Rouge syntax-highlighting colors (`code-*` tokens); tinted, rounded alerts; white shadowed cards with hover; neutral secondary buttons; gradient CTA box; soft status badges; styled page meta line (last updated, edit link); polished tabs, accordion, steps, timeline, pagination, kbd and tables.
+- Tokens: `line-height`, `container`, `header-height`, `space-section`, `radius-lg`, `shadow-sm`, `shadow`, `code-keyword|string|comment|function|constant`; primitives `radius-lg`, `orange-400/600`, `teal-400/600`, `space-10`, `space-16`.
+
+##### Fixed
+- An alert (or any paragraph with text) inside a hero no longer turns into a CTA row with its text hidden; only paragraphs made of links alone become action rows (`modootoday/actions.html`).
+- Feature cards no longer show a stray "—" before the description.
+- Header nav no longer wraps into several lines on narrow screens; it scrolls horizontally instead.
+
+##### Changed
+- QA CSS budget raised from 20 KB to 32 KB (uncompressed, as built); the built CSS is about 28 KB (5.7 KB gzip).
+
+#### Milestone 0.4
+
+##### Added
+- P2 components: timeline (`c: timeline`), keyboard keys (`` `kbd:Ctrl+K` ``), client search (`modootoday/search.json` include + `search.js`, under 1 KB compressed), `post` layout.
+- Read-only DTCG `tokens.json` generated in CI from the Sass maps (`script/tokens-json`), with a consistency test against the built CSS.
+- Checker: `kbd:` value format.
+- Example site: i18n keys `theme.toggle`, `breadcrumb.label`, `toc.label`, `search.label`, `post.date_format` (en/ko/ja).
+
+##### Deferred
+- `_data/components.yml` slot contract.
+
+#### Milestone 0.3
+
+##### Added
+- P1 components: theme toggle (localStorage `mt-theme`, pre-paint script), breadcrumb, table of contents, accordion (`c: accordion`), steps (`c: steps`), figure/figcaption, `tag:` badges. All on by default; `modootoday.components` narrows them.
+- Checker: `tag:` value format, images without alt text.
+
+##### Changed
+- Status/tag badges are also turned off when `badge` is not in `modootoday.components`.
+
+
+#### Milestone 0.2
+
+##### Added
+- Three-layer design tokens: primitives `--mt-p-*`, shadcn-style semantic tokens (`--mt-background`, `--mt-primary`, …), component tokens (`--mt-callout-accent`, `--mt-badge-*`, `--mt-card-padding`); `data-theme="light|dark"` forcing.
+- Sass split into `_sass/modootoday/{_settings,_core}.scss`, `tools/`, `tokens/`, `components/<name>.scss`; `@import` only, compiles on Ruby Sass 3.7 and Dart Sass.
+- `modootoday:` config: `color_scheme`, `css_layers` (`@layer mt.*`, off by default), `components` (all P0 components on by default), `nav`, `tokens`, `tokens_dark` (inlined `<style id="mt-tokens">`). Defaults in `_includes/modootoday/config.html`.
+- Components: navigation (`_data/nav/*.yml`, `aria-current`), prev/next pagination, code-copy button (`assets/js/modootoday/code-copy.js`); `mt-*` classes for callout, badge, hero, CTA, card (features), tabs.
+- `_includes/footer-custom.html` hook; i18n keys `nav.label`, `pagination.*`, `code.*`.
+- Checker: rejects `@use`/`@forward`/`@supports selector()` in Sass and built CSS, `--x: $var` literals, undefined `var(--mt-*)`, invalid `modootoday:` settings and token values.
+- Tests: theme CSS built with all/minimal/layers configs on both engines (`test/css_test.rb`).
+- CI: github-pages job on Ruby 3.3.4 with the production gem set (github-pages 232, jekyll-include-cache 0.2.1, jekyll-octicons 14.2, nokogiri 1.16.7); `remote_theme:` site built by `actions/jekyll-build-pages@v1` and checked; Jekyll 4 on Ruby 3.2 and 3.4.
+
+##### Changed
+- `required_ruby_version` is now `>= 3.2`.
+- `badges: false` in `modootoday:` is honoured (it was swallowed by `default: true`).
+
+
+##### Removed
+- `_sass/modootoday/{_tokens,_base,_components}.scss` (replaced by the new partials; `_sass/modootoday.scss` still imports everything).
+
+#### Milestone 0.1
+
+##### Added
+- Gem-based Jekyll theme layout: `_layouts/{default,doc,twin,llms,llms-full}.html`, `_includes/{md-components,md-sections,head-custom}.html`, `_sass/`, `assets/`.
+- Default stylesheet with CSS custom-property design tokens, light and dark (`prefers-color-scheme`) themes, callouts, status badges, sections, CTA buttons, tabs, focus-visible styles and a responsive doc layout.
+- `assets/js/md-tabs.js`: Home/End keys, focusable panels (`tabindex="0"`), ids unique across several tab groups.
+- `modootoday-check` executable (from the kit's `bin/check`): missing-front-matter error, unregistered alert type error, github-pages lockfile check now opt-in (`--github-pages[=VERSION]`), `--help`.
+- Neutral example site (en/ko/ja) with agent-readable Markdown twins.
+- Ruby tests (`test/check_test.rb`), jsdom tests (`test/tabs.test.js`), CI for the GitHub Pages stack and Jekyll 4, release workflow with RubyGems trusted publishing.
+
+- md-components v1 amendments from the standards audit (66 fixtures in `test/fixtures/md`, built in-process by `test/build_test.rb`):
+  - Alerts: case-insensitive types; standalone `<p>[!TYPE]</p>` (blank `>` line, body starting with code, list or heading); `[!TYPE]<br />` (trailing spaces).
+  - Checker: case-insensitive markers, unregistered/empty/titled/formatted alerts and tab after `>` are errors, `<pre>`/`<code>` ignored when scanning build output; fence info string must be one language word; bare URL/e-mail autolinks, abbreviations and HTML comments forbidden; setext, nested, indented and commented `##` are errors; footnotes explicitly allowed.
+  - `default` layout: `rel="alternate" type="text/markdown"` link to the twin and `rel="describedby"` link to the nearest `llms.txt`; example `llms.txt` files use llmstxt.org H2 link lists.
+
+- Automatic twins and llms files: opt-in generator `plugins: [jekyll-theme-modootoday]` (`lib/`, Jekyll 3.9+/4, skipped by GitHub Pages safe mode) adds `<name>.md.txt`-equivalent twin pages and `llms.txt`/`llms-full.txt` per language; layouts `llms` and `llms-full` (with includes `md-raw-body`, `md-llms-pages`) generate those files from front-matter-only stubs on GitHub Pages. Example uses them.
+- Checker `--twins`: stubs no longer required when the twin exists (plugin); clearer missing-twin hint; `twin: false`; `llms.txt` must start with an H1; `llms-full.txt` must contain every page body.
+- `test/consumer_test.rb`: builds real consumer sites (theme gem with stubs, `--baseurl`, stub-less site with the plugin); CI builds the example with `remote_theme` pinned to the pushed commit.
+
+##### Fixed
+- Sections split only on top-level `<h2>`; an `h2` inside a quote, list or alert no longer injects `</section><section>` into it.
+- Docs: alerts are a GitHub extension outside the GFM spec; the raw-HTML ban is about portability (GitHub renders `details`/`kbd`, strips others; kramdown passes all through), not "GitHub sanitising".
+- Checker messages for `##` and alerts nested in quotes/lists explain why and what to use instead.
+- `required_ruby_version` raised to 3.0 (the checker uses endless methods).
+- Example: `sass.silence_deprecations: [import]` for Dart Sass; `llms.txt` per language generated instead of hand-written.
+- Raw `<name>.md` copies in `_site` on GitHub Pages: caused by content files without front matter (rendered by `jekyll-optional-front-matter` and also copied). Front matter is now required and checked.
+
+[1.0.0]: https://github.com/modootoday/jekyll-theme-modootoday/tree/main

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 modootoday (모두의오늘)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.ko.md

@@ -0,0 +1,115 @@
+# jekyll-theme-modootoday
+
+페이지 본문은 평범한 GitHub Markdown으로 두고, 레이아웃·include·CSS로 꾸미는 Jekyll 테마입니다.
+
+[![CI](https://github.com/modootoday/jekyll-theme-modootoday/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/modootoday/jekyll-theme-modootoday/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/jekyll-theme-modootoday)](https://rubygems.org/gems/jekyll-theme-modootoday)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+[문서](https://modootoday.github.io/jekyll-theme-modootoday/ko/) · [English](README.md)
+
+> [!NOTE]
+> 이 문서는 [README.md](README.md)의 번역입니다. 내용이 다르면 영어 문서가 우선합니다.
+
+## 왜
+
+- **페이지에는 표준 Markdown만.** GFM과 GitHub 알림만 쓰므로 같은 파일이 github.com에서도 잘 읽힙니다.
+- **GitHub Pages에서 동작.** 레이아웃과 include가 Liquid만 쓰므로 기본 빌드의 `remote_theme`도 되고, Jekyll 4도 됩니다.
+- **마크업 없는 컴포넌트.** 알림, 상태 배지, 카드, 탭, 버튼, 아코디언, 단계, 타임라인 등이 평범한 Markdown 패턴에서 나옵니다.
+- **에이전트가 읽기 쉬움.** 페이지마다 바이트 단위로 같은 Markdown 버전과 `llms.txt`, `llms-full.txt`를 둘 수 있습니다.
+- **접근성.** 키보드 단축키, 보이는 포커스, 휴대폰 안전 영역, 44 px 터치 대상, 고대비와 동작 줄이기가 기본으로 들어 있습니다.
+- **검사기.** `modootoday-check`가 원문과 빌드 결과를 검사합니다.
+
+## 설치
+
+gem 방식(`theme:`):
+
+```ruby
+# Gemfile
+gem "jekyll-theme-modootoday", "~> 1.0"
+```
+
+```yaml
+# _config.yml
+theme: jekyll-theme-modootoday
+```
+
+Gemfile 없이 GitHub Pages에서(`remote_theme:`):
+
+```yaml
+# _config.yml
+remote_theme: modootoday/jekyll-theme-modootoday@v1.0.0
+plugins:
+  - jekyll-remote-theme
+```
+
+태그나 커밋으로 고정하세요. 자세한 내용: [설치 가이드](https://modootoday.github.io/jekyll-theme-modootoday/ko/guides/install/).
+
+## 빠른 시작
+
+```sh
+mkdir my-docs && cd my-docs
+printf 'source "https://rubygems.org"\ngem "jekyll", "~> 4.4"\ngem "jekyll-theme-modootoday", "~> 1.0"\n' > Gemfile
+printf 'theme: jekyll-theme-modootoday\nmarkdown: kramdown\nkramdown: {input: GFM}\nsass: {style: compressed, silence_deprecations: [import, global-builtin]}\n' > _config.yml
+printf -- '---\nlayout: doc\ntitle: Home\n---\n# Hello\n\n> [!TIP]\n> Plain Markdown, styled.\n' > index.md
+bundle install && bundle exec jekyll build
+bundle exec modootoday-check . _site
+```
+
+따라 하기: [첫 페이지 쓰기](https://modootoday.github.io/jekyll-theme-modootoday/ko/guides/first-page/).
+
+## 개념
+
+- **본문은 평범하게, 레이아웃은 풍부하게.** 본문은 GFM이고 front matter의 `sections:`가 `##`마다 컴포넌트를 연결합니다. [컴포넌트](https://modootoday.github.io/jekyll-theme-modootoday/ko/components/)와 [키친싱크](https://modootoday.github.io/jekyll-theme-modootoday/ko/components/kitchen-sink/)를 보세요.
+- **규칙.** 본문에 쓸 수 있는 것과 각 패턴의 변환 결과는 [RULES.md](RULES.md)(`md-components v1`)가 정합니다.
+- **설정과 토큰.** `_config.yml`의 `modootoday:` 블록 하나, CSS 사용자 속성 `--mt-*`, 컴포넌트별 Sass 파셜. [설정](https://modootoday.github.io/jekyll-theme-modootoday/ko/guides/configuration/)과 [커스터마이즈](https://modootoday.github.io/jekyll-theme-modootoday/ko/guides/customize/)를 보세요.
+- **블로그와 뉴스.** `blog`, `news`, `news-article`, `author`, `feed` 레이아웃: 페이지네이션 카드 목록(list, grid, magazine), `_data/authors.yml` 바이라인, 시리즈, 관련 글, 공유, JSON-LD, 언어별 Atom 피드. Liquid만 쓰고 스타일과 스크립트는 선택 번들입니다. [블로그와 뉴스](https://modootoday.github.io/jekyll-theme-modootoday/ko/layouts/blog-news/)를 보세요.
+- **Markdown 버전: 세 가지 방식** — 스텁 파일(기본, 기본 Pages), `jekyll-theme-modootoday` 플러그인(Jekyll 4 / Actions), 또는 front matter 없는 페이지와 `modootoday.twins: source`(기본 Pages, 스텁 없음). [RULES.md §5a](RULES.md#5a-markdown-twins)를 보세요.
+
+## 명령
+
+`modootoday-check SRC SITE [옵션]` (`jekyll build` 다음에 실행, 표는 영어 원본에서 생성):
+
+<!-- commands:begin (generated by script/readme-commands; do not edit) -->
+| Option | Checks |
+|---|---|
+| `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 |
+<!-- commands:end -->
+
+## AI 에이전트
+
+- `guide.md`의 Markdown 버전은 `/guide/index.md`이며 본문과 바이트 단위로 같고, `rel="alternate" type="text/markdown"`으로 연결됩니다.
+- `llms.txt`와 `llms-full.txt`는 `/`와 각 `/<lang>/` 아래에 있습니다.
+- Jekyll 4에서는 `plugins: [jekyll-theme-modootoday]`가 만들고, 기본 GitHub Pages 빌드는 파일 하나짜리 스텁을 씁니다.
+- 자세히: [에이전트 가이드](https://modootoday.github.io/jekyll-theme-modootoday/ko/guides/agents/), 이 저장소의 [llms.txt](https://modootoday.github.io/jekyll-theme-modootoday/llms.txt).
+
+## 가이드
+
+- [문서 사이트](https://modootoday.github.io/jekyll-theme-modootoday/ko/) ([`docs/`](docs/)에서 이 테마로 빌드)
+- [설치](https://modootoday.github.io/jekyll-theme-modootoday/ko/guides/install/) · [첫 페이지](https://modootoday.github.io/jekyll-theme-modootoday/ko/guides/first-page/) · [컴포넌트](https://modootoday.github.io/jekyll-theme-modootoday/ko/components/) · [설정](https://modootoday.github.io/jekyll-theme-modootoday/ko/guides/configuration/) · [커스터마이즈](https://modootoday.github.io/jekyll-theme-modootoday/ko/guides/customize/) · [블로그와 뉴스](https://modootoday.github.io/jekyll-theme-modootoday/ko/layouts/blog-news/) · [공개 API](https://modootoday.github.io/jekyll-theme-modootoday/ko/reference/api/) · [이전과 업그레이드](https://modootoday.github.io/jekyll-theme-modootoday/ko/guides/upgrade/) · [CSP](https://modootoday.github.io/jekyll-theme-modootoday/ko/recipes/csp/) · [접근성](https://modootoday.github.io/jekyll-theme-modootoday/ko/guides/accessibility/) · [로드맵](https://modootoday.github.io/jekyll-theme-modootoday/ko/reference/roadmap/) · [변경 기록](CHANGELOG.md)
+- 지원 스택: GitHub Pages(`github-pages` 232, Jekyll 3.10, Ruby 3.3.4)와 Jekyll 4.4(Ruby 3.2~3.4), 모두 CI에서 테스트합니다. Jekyll 3.9를 하한으로 테스트합니다.
+- [보안 정책](SECURITY.md) · [행동 강령](CODE_OF_CONDUCT.md)
+
+## 종료 코드
+
+| 코드 | 의미 |
+|---|---|
+| 0 | 문제 없음 |
+| 1 | 문제 발견(stderr에 출력) 또는 잘못된 사용법 |
+
+## 기여
+
+이슈와 풀 리퀘스트를 환영합니다. [CONTRIBUTING.md](CONTRIBUTING.md)를 보세요. 이 문서는 영어 [README.md](README.md)의 번역이며, 내용이 다르면 영어가 우선합니다.
+
+## 라이선스
+
+[MIT](LICENSE) © modootoday (모두의오늘)

data/README.md

@@ -0,0 +1,112 @@
+# jekyll-theme-modootoday
+
+A Jekyll theme that keeps page bodies in plain GitHub Markdown and styles them with layouts, includes and CSS.
+
+[![CI](https://github.com/modootoday/jekyll-theme-modootoday/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/modootoday/jekyll-theme-modootoday/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/jekyll-theme-modootoday)](https://rubygems.org/gems/jekyll-theme-modootoday)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+[Documentation](https://modootoday.github.io/jekyll-theme-modootoday/) · [한국어](README.ko.md)
+
+## Why
+
+- **Only standard Markdown in your pages.** GFM plus GitHub alerts; the same file reads well on github.com.
+- **Works on GitHub Pages.** Layouts and includes are Liquid only, so `remote_theme` works on the classic build; Jekyll 4 works too.
+- **Components without markup.** Alerts, status badges, card grids, tabs, buttons, accordion, steps, timeline and more come from plain Markdown patterns.
+- **Readable by agents.** Every page can have a byte-identical Markdown twin, plus `llms.txt` and `llms-full.txt`.
+- **Accessible.** Keyboard shortcuts, visible focus, safe areas on phones, 44 px touch targets, high contrast and reduced motion are built in.
+- **Checked.** `modootoday-check` validates the sources and the built site.
+
+## Install
+
+As a gem (`theme:`):
+
+```ruby
+# Gemfile
+gem "jekyll-theme-modootoday", "~> 1.0"
+```
+
+```yaml
+# _config.yml
+theme: jekyll-theme-modootoday
+```
+
+On GitHub Pages without a Gemfile (`remote_theme:`):
+
+```yaml
+# _config.yml
+remote_theme: modootoday/jekyll-theme-modootoday@v1.0.0
+plugins:
+  - jekyll-remote-theme
+```
+
+Pin a tag or a commit. More options: [Install guide](https://modootoday.github.io/jekyll-theme-modootoday/guides/install/).
+
+## Quick start
+
+```sh
+mkdir my-docs && cd my-docs
+printf 'source "https://rubygems.org"\ngem "jekyll", "~> 4.4"\ngem "jekyll-theme-modootoday", "~> 1.0"\n' > Gemfile
+printf 'theme: jekyll-theme-modootoday\nmarkdown: kramdown\nkramdown: {input: GFM}\nsass: {style: compressed, silence_deprecations: [import, global-builtin]}\n' > _config.yml
+printf -- '---\nlayout: doc\ntitle: Home\n---\n# Hello\n\n> [!TIP]\n> Plain Markdown, styled.\n' > index.md
+bundle install && bundle exec jekyll build
+bundle exec modootoday-check . _site
+```
+
+Walkthrough: [Write your first page](https://modootoday.github.io/jekyll-theme-modootoday/guides/first-page/).
+
+## Concepts
+
+- **Plain body, rich layout.** The body is GFM; `sections:` front matter maps each `##` to a component. See [Components](https://modootoday.github.io/jekyll-theme-modootoday/components/) and the [kitchen sink](https://modootoday.github.io/jekyll-theme-modootoday/components/kitchen-sink/).
+- **Rules.** What may appear in a body, and what each pattern becomes, is defined in [RULES.md](RULES.md) (`md-components v1`).
+- **Settings and tokens.** One `modootoday:` block in `_config.yml`, CSS custom properties `--mt-*`, one Sass partial per component. See [Configuration](https://modootoday.github.io/jekyll-theme-modootoday/guides/configuration/) and [Customize](https://modootoday.github.io/jekyll-theme-modootoday/guides/customize/).
+- **Blog and news.** `blog`, `news`, `news-article`, `author` and `feed` layouts: paginated card lists (list, grid, magazine), bylines from `_data/authors.yml`, series, related posts, share, JSON-LD, per-language Atom feeds; Liquid only, styles and script in an optional bundle. See [Blog and news](https://modootoday.github.io/jekyll-theme-modootoday/layouts/blog-news/).
+- **Twins: three ways** — stub files (default, classic Pages), the `jekyll-theme-modootoday` plugin (Jekyll 4 / Actions), or `modootoday.twins: source` with front-matter-less pages (classic Pages, no stubs). See [RULES.md §5a](RULES.md#5a-markdown-twins).
+
+## Commands
+
+`modootoday-check SRC SITE [options]` (run after `jekyll build`):
+
+<!-- commands:begin (generated by script/readme-commands; do not edit) -->
+| Option | Checks |
+|---|---|
+| `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 |
+<!-- commands:end -->
+
+## AI agents
+
+- Each page `guide.md` has a twin at `/guide/index.md` with the same bytes as its body, linked with `rel="alternate" type="text/markdown"`.
+- `llms.txt` and `llms-full.txt` exist at `/` and under each `/<lang>/`.
+- Jekyll 4: `plugins: [jekyll-theme-modootoday]` creates them; the classic GitHub Pages build uses one-file stubs.
+- Details: [Agents guide](https://modootoday.github.io/jekyll-theme-modootoday/guides/agents/) and this repository's own [llms.txt](https://modootoday.github.io/jekyll-theme-modootoday/llms.txt).
+
+## Guides
+
+- [Documentation site](https://modootoday.github.io/jekyll-theme-modootoday/) (built with this theme from [`docs/`](docs/))
+- [Install](https://modootoday.github.io/jekyll-theme-modootoday/guides/install/) · [First page](https://modootoday.github.io/jekyll-theme-modootoday/guides/first-page/) · [Components](https://modootoday.github.io/jekyll-theme-modootoday/components/) · [Configuration](https://modootoday.github.io/jekyll-theme-modootoday/guides/configuration/) · [Customize](https://modootoday.github.io/jekyll-theme-modootoday/guides/customize/) · [Blog and news](https://modootoday.github.io/jekyll-theme-modootoday/layouts/blog-news/) · [Public API](https://modootoday.github.io/jekyll-theme-modootoday/reference/api/) · [Migrate and upgrade](https://modootoday.github.io/jekyll-theme-modootoday/guides/upgrade/) · [CSP](https://modootoday.github.io/jekyll-theme-modootoday/recipes/csp/) · [Accessibility](https://modootoday.github.io/jekyll-theme-modootoday/guides/accessibility/) · [Roadmap](https://modootoday.github.io/jekyll-theme-modootoday/reference/roadmap/) · [Changelog](CHANGELOG.md)
+- Supported stacks: GitHub Pages (`github-pages` 232, Jekyll 3.10, Ruby 3.3.4) and Jekyll 4.4 on Ruby 3.2 to 3.4, all tested in CI; Jekyll 3.9 is the tested floor.
+- [Security policy](SECURITY.md) · [Code of conduct](CODE_OF_CONDUCT.md)
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | no problems |
+| 1 | problems found (listed on stderr) or bad usage |
+
+## Contributing
+
+Issues and pull requests are welcome. English is the canonical language; translations follow it. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © modootoday (모두의오늘)

data/RULES.md

@@ -0,0 +1,120 @@
+md-components v1
+
+# md-components rules
+
+Goal: page bodies (`*.md`, `<lang>/*.md`) use only standard GitHub Flavored Markdown (plus GitHub's alert extension) that renders unchanged on github.com. Design comes from layouts, includes, CSS and optional JS. Targets: the GitHub Pages build (`github-pages` gem 232, Jekyll 3.10, kramdown GFM, allowed plugins only, no build scripts) and Jekyll 4.
+
+Status: **final** (v1, approved 2026-10-30). `md-components v1` is the name of this Markdown rules standard; changes are listed in `CHANGELOG.md`.
+
+## 0. Front matter
+Every content page starts with front matter; an empty block (`---` then `---`) is enough. Reason: on GitHub Pages, `jekyll-optional-front-matter` renders a file without front matter and the raw file is also copied to `_site/<name>.md`. Checker error, except in the opt-in front-matter-less twin mode (`modootoday.twins: source`, §5a), which uses exactly that copy as the twin.
+
+## 1. Core components
+| Component | Markdown | Transformation | Fallback (no JS / GitHub viewer / twin) |
+|---|---|---|---|
+| Alerts (5) | top-level quote whose first line is exactly `> [!NOTE]` (TIP/IMPORTANT/WARNING/CAUTION; any case), body on the following `>` lines. The body may start with a paragraph, a blank `>` line, a list, a code block or a `###` heading. Alerts are a **GitHub extension outside the GFM spec**; other parsers show a plain quote | `_includes/modootoday/markdown/components.html` converts kramdown's `<p>[!TYPE]` + body, standalone `<p>[!TYPE]</p>` and `[!TYPE]<br />` (trailing spaces) into `blockquote.mt-callout.mt-callout-<type>[role=note]` with a localised title | quote / GitHub alert / source |
+| Sections | `# Title`, lead paragraph, link-only paragraph (CTA), then `## Section`; front matter `sections:` | `doc` layout → `_includes/modootoday/markdown/sections.html`: with `sections:` the part before the first `##` is `section.mt-hero` and item *i* wraps the *i*-th **top-level** `##` in `section.mt-section` (an `h2` nested in a quote, list or alert never splits); without it, one `div.mt-prose` | plain document |
+| Section mapping | each `sections:` item is a string `name` or `{c: component, name: key, ...params}`. No implicit mapping. Item count ≠ top-level `## ` count is a checker error; setext `---` headings, `##` in quotes/alerts/list items, `##` indented 1–3 spaces and `##` inside HTML comments are checker errors | `data-section`=name, `data-c`=c, class `mt-c-<c>` | none |
+| Card grid | under `##`, list items `- **Title** — text` or `- **Title**: text` | CSS only | list |
+| CTA buttons | every link-only paragraph in `section.mt-hero` and in `c: cta` sections; the first link is primary. Separator text such as `·` between links is a text node, so the paragraph still counts as link-only | CSS `p:has(> a):not(:has(> :not(a)))` | links |
+| Install tabs | in a `c: tabs` section, repeated `### name` + fenced code block (info string = one language word) | `data-tabs` + i18n `tabs.label`; `assets/js/modootoday/tabs.js` builds WAI-ARIA tabs (arrows, Home, End) | all blocks in order |
+| Diagrams, math | ```` ```mermaid ```` / ```` ```math ```` | none in the theme; the site renders at build time or self-hosts a renderer (docs: Math and diagrams) | code / GitHub mermaid, math |
+| Tables | GFM tables | CSS horizontal scroll | table |
+| Decoration | front matter or layout | read by layouts, never in bodies | none |
+
+## 2. Optional components
+| Component | Markdown | Transformation | Notes |
+|---|---|---|---|
+| Status badge | code span `` `status:available` `` / `partial` / `planned` (fixed set) | with badges on (default; `badges: false` per page or `modootoday.badges: false` site-wide): `span.mt-badge.mt-badge-<value>` = symbol (●◐○, `aria-hidden`) + i18n `status.<value>` | unknown values and leftover `<code>status:` in the build are checker errors |
+| Tag badge | `` `tag:beta` `` (one token `[A-Za-z0-9._-]+`) | `span.mt-badge.mt-badge-tag` | needs the `badge` component; bad values are checker errors. `since:` is not part of 1.0 and is a checker error |
+| Accordion | `c: accordion` section, each `###` is a question | JS turns `###` into `button[aria-expanded]` + panel; content stays visible without JS | — |
+| Steps | `c: steps` section with an `ol` or `###` items | CSS counters | — |
+| Figure | an image-only paragraph followed by an `*emphasis*`-only paragraph | `figure` + `figcaption` | images without alt (`![](...)`) are checker errors |
+| Breadcrumb / TOC / theme toggle | automatic (`breadcrumb: false`, `toc: false` per page; TOC shows with 2+ `##`/`###`; toggle only with `color_scheme: auto`) | `nav.mt-breadcrumb`, `nav.mt-toc`, header button (i18n `theme.toggle`, `breadcrumb.label`, `toc.label`) | — |
+| Timeline | `c: timeline` section; each `###` is a date or milestone, content follows | CSS line and dots | — |
+| Keyboard keys | `` `kbd:Ctrl+K` `` (keys joined by `+`, no spaces) | `kbd.mt-kbd > kbd` per key | bad values are checker errors |
+| Search | add `search.json` with `layout: null` and `{% include modootoday/search.json %}` | header `div.mt-search[role=search]` (i18n `search.label`) + `search.js` (under 1 KB compressed); pages with `search: false` are left out | rendered only when `/search.json` exists |
+| Post layout | `layout: post` (`date`, optional `author`, `tags`) | `p.mt-post-meta` (date with i18n `post.date_format`, author, tag badges), then the doc pipeline | — |
+| Code title | a line holding only `` `file:path` `` right before a fenced block | `div.mt-code` > `p.mt-code-title` + block | a lone `file:` line not followed by a fence is a checker error |
+| Progress | `` `progress:60` `` (whole number 0–100) | `span.mt-progress` > `progress` + value text (i18n `progress.label`) | out of range is a checker error |
+| Embed | a paragraph holding only `` `embed:https://… Title` `` | `div.mt-embed` > lazy `iframe[title]` (16:9 reserved) | non-https is a checker error |
+| Loading / skeleton | `` `loading:spinner` ``, `` `loading:bar` ``, `` `skeleton:text` `` / `card` / `image` / `avatar` / `row` | `span.mt-spinner`, `span.mt-topbar`, `span.mt-skeleton` with `role=status`, `aria-busy` and i18n `loading.label`; optional `loading` sheet; reduced motion, forced colors and RTL | unknown variants are checker errors |
+| File tree / Details / FAQ / Params / Link cards / Quote / Gallery / Pricing / Subscribe | `c: filetree` (nested list), `c: details` and `c: faq` (`###` per item), `c: params` (table), `c: linkcards` (link-first list), `c: quote` (quote ending in `— name`), `c: gallery` (tight image list), `c: pricing` (`###` per plan, param `recommended`), `c: subscribe` (text; form posts to `modootoday.subscribe.action`) | per-component markup listed in docs api.md; each has its own sheet | gallery images need alt; `recommended` must be in range; subscribe action must be https |
+| Component registry | optional `_data/components.yml`: `name: {params: {key: {allowed: [...], required: bool}}, i18n: [keys...]}` | when present the checker validates `c`, params and i18n keys | — |
+
+## 3. Localisation
+- Chrome strings use `_data/i18n/<lang>.yml`: `callout.<type>`, `tabs.label`, `status.<value>`, `skip`. Missing keys fall back to English.
+- The same rules apply to `<lang>/*.md`.
+
+## 3a. Writing direction
+RTL languages (`ar fa he ur yi ps sd ug dv ckb`, by the first subtag of `lang`) get `<html dir="rtl">`; front matter `direction: rtl|ltr` or i18n `direction:` overrides. Theme CSS uses logical properties for inline-start/end; code blocks, inline code and `kbd` stay LTR/isolated. Write the Markdown in logical order; never use bidi control characters to fake layout.
+
+## 4. Forbidden (outside code blocks and code spans)
+The bans are about **portability**: the same source must look the same on github.com, in kramdown (which passes raw HTML through and adds its own extensions) and in the plain-text twin.
+
+| Forbidden | Why | Check |
+|---|---|---|
+| raw HTML (`<div>`, `<details>`, `<kbd>` …) | not portable: GitHub renders some tags (`details`, `kbd`) and strips or escapes others (`script`, `iframe`), kramdown passes everything through; keeps twins readable | checker |
+| HTML comments `<!-- -->` | hidden on GitHub but emitted by kramdown; a `##` inside one shifts section counts. Exception: a tool region marker alone on its line, `<!-- tool:name:begin -->` / `<!-- tool:name:end -->` (lowercase, ends in `:begin` or `:end`) | checker |
+| Liquid `{% %}` `{{ }}` | breaks on GitHub and in twins | checker |
+| kramdown IAL/ALD `{: .x}`, `{:toc}` | kramdown-only | checker |
+| header ids `{#id}` | kramdown-only (literal text on GitHub) | checker |
+| definition lists `: text` | kramdown-only | checker |
+| abbreviations `*[HTML]: …` | kramdown-only (literal text on GitHub) | checker |
+| bare URL / `www.` / e-mail autolinks | GFM autolink extension; kramdown leaves them as text. Use `<https://…>` or `[text](url)` | checker |
+| alerts inside lists, tables or quotes | GitHub: "alerts cannot be nested"; not converted | checker (source + leftover `[!TYPE]` in the build, outside `<pre>`/`<code>`) |
+| unregistered alert types `> [!FOO]` | plain quote everywhere | checker error |
+| text after the marker `> [!NOTE] Title` | GitHub shows a plain quote (no custom titles) | checker error |
+| empty alert (marker only) | GitHub shows a plain quote | checker error |
+| formatted marker `> **[!NOTE]**`, tab after `>` | not an alert / kramdown code block | checker error |
+| `##` that is not a top-level ATX heading (setext `---`, in quote/alert/list, indented 1–3 spaces, in a comment) | parsers disagree; sections would split inside other blocks | checker error |
+| code fence info-string attributes (```` ```sh {title=x} ````, `~~~sh {.x}`, ```` ```sh title=x ````) | kramdown 2.4 turns the block into inline code | checker error: info string must be a single language word |
+
+Allowed and portable: footnotes `[^1]` (markup differs slightly), task lists, strikethrough, GFM tables, `<url>` autolinks, hard breaks. Note: `> [! NOTE]` (space inside) is not an alert; the checker warns, `--strict` makes it an error.
+
+## 5. Checker (`modootoday-check SRC SITE [--twins] [--github-pages[=VER]] [--strict] [--gh]`)
+1. front matter present 2. forbidden syntax, alert form, fence info strings 3. `status:` vocabulary 4. `sections:` count = top-level `## ` count, nested/setext/indented `##` 5. `_data/components.yml` if present 6. no `[!TYPE]` (any case, outside `<pre>`/`<code>`) / `<code>status:` in built HTML 7. `--github-pages`: `Gemfile.lock` pins github-pages VER (default 232, or `$MODOOTODAY_GITHUB_PAGES`) 8. `--twins`: rules below 8a. Sass sources (`_sass/`, `assets/**/*.scss`) and built CSS: no `@use`/`@forward`/`@supports selector()`, no `--x: $var` literals, every `var(--mt-*)` defined 8b. `_config.yml` `modootoday:`: `twins` is `true`, `false` or `source`, known `color_scheme`/`components`, boolean `css_layers`/`badges`, `tokens`/`tokens_dark` values are plain CSS values (no `; { } < >`, valid hex), unknown token names warn 9. `--gh` (optional, network + `gh` auth): render with `gh api markdown`.
+
+## 5a. Markdown twins
+Three ways to publish a page's raw Markdown next to its HTML. Pick one per site (stubs may be mixed with the others for single pages).
+
+| Mode | How | Twin URL | Use when | Limits |
+|---|---|---|---|---|
+| Stub (default) | `<name>.md.txt` with `layout: twin`, `twin_of`, `permalink` | `/<name>/index.md` | classic GitHub Pages, pages need front matter (`sections:`, `title`, `lang`) | one extra file per page |
+| Generator | `plugins: [jekyll-theme-modootoday]` | `/<name>/index.md` | Jekyll 4 or a GitHub Actions build | not run by classic GitHub Pages |
+| Source (front-matter-less) | `modootoday.twins: source`; pages have **no** front matter | the source path: `/<name>.md`, `/<dir>/index.md` | classic GitHub Pages without stubs; simple doc trees | see below |
+
+Source mode relies on `jekyll-optional-front-matter`, a GitHub Pages default plugin: a `.md` file without front matter is rendered to HTML **and** copied verbatim to its own path, so the twin is the whole source file (byte-identical, no front matter to strip). Limits:
+- No per-page front matter: layout, `lang`, `permalink` and other settings come from path-based `defaults:` in `_config.yml`; the title comes from the first `# ` heading (`jekyll-titles-from-headings`). Per-page `sections:` is not available (use a `defaults:` scope for a single file if needed).
+- Links to `other.md` in bodies are not rewritten to the HTML page in this mode; they reach the raw twin. Link to `other/` instead.
+- Local and Actions builds must list `plugins: [jekyll-optional-front-matter, jekyll-titles-from-headings]` (Jekyll 4: add both gems); the classic GitHub Pages build enables them by default.
+- `optional_front_matter.remove_originals: true` or `require_front_matter: true` disables the raw copy; the checker reports both.
+- Pages that keep front matter in source mode still need a stub or the generator; a stub next to a front-matter-less page is redundant (checker error).
+- The `default` layout and `llms.txt` link to the raw copy (`/<path>.md`) when it exists.
+- Observed on classic GitHub Pages (legacy build, `remote_theme`; one sample site, checked once on 2026-10-30): the raw copy at `/<name>.md` and `/<dir>/index.md` was served as `Content-Type: text/markdown; charset=utf-8` and was byte-identical to the source; `llms.txt` was served as `text/plain; charset=utf-8`; the HTML page carried the `rel="alternate" type="text/markdown"` and `rel="describedby"` links. `remote_theme` of this public theme also worked from a private repository (a Pages site built from a private repository is still public unless access control is set). Not verified: cache/CDN behaviour, other file extensions, non-English pages.
+
+Stub and generator details:
+- Source `<name>.md`. The twin comes from either
+  - the opt-in generator `plugins: [jekyll-theme-modootoday]` (Jekyll 4 or an Actions build; not run by the classic GitHub Pages build, which allows only whitelisted plugins), or
+  - a stub `<name>.md.txt` next to it with only `layout: twin`, `twin_of`, `permalink` and no body (works everywhere). Liquid cannot create output files, so on classic GitHub Pages a stub per page is unavoidable.
+  Both produce the same page; a stub wins over the generator. `twin: false` opts a page out.
+- Output: `index.md` → `/index.md`, others → `/<dir>/<name>/index.md`; other languages under `/<lang>/`.
+- Twin body is **byte-identical** to the source minus front matter (no added headers; put extra information in `llms.txt`).
+- `llms.txt` and `llms-full.txt` exist at `/` and under each `/<lang>/`. `llms.txt` follows llmstxt.org: `# Title`, a `>` summary, then `## Section` lists of `- [Name](url): note`. `llms-full.txt` is a common convention, not part of llmstxt.org. Layouts `llms` and `llms-full` generate both from a front-matter-only stub (or the generator adds them); `llms-full.txt` is every page body of that language, byte-identical, separated by a blank line.
+- The `default` layout adds `<link rel="alternate" type="text/markdown" href=".../index.md">` when the twin exists and `<link rel="describedby" type="text/plain">` to the nearest `/<lang>/llms.txt` or `/llms.txt`.
+- With `--twins` and `modootoday.twins: source`: a front-matter-less page needs a rendered page (`<name>.html` or `<name>/index.html`) and a byte-identical raw copy at its source path.
+- With `--twins`: a missing or non-identical twin is an error (`README.md` and `twin: false` excepted), a stub must use `layout: twin` with an empty body, `llms.txt` must start with `# `, and `llms-full.txt` must contain every page body of its language.
+- Twins and the checker assume directory URLs (`permalink: pretty` or `/<name>/`); with `.html` permalinks the generator writes `/<name>.md` but the checker still expects `/<name>/index.md`.
+- Twin bodies go through Liquid (`include_relative`); bodies must not contain Liquid (already forbidden in §4).
+
+## 6. Known limitations
+- `##` inside an alert, quote or list item stays a checker error rather than a supported form: GitHub would render an `h2` inside the box, but sections split only on column-0 `## `. Use `###` or bold text there. Alerts nested in lists, tables or quotes are errors because GitHub renders only top-level alerts.
+- Alert conversion depends on kramdown's output string (`<blockquote>` followed by `  <p>[!TYPE]`) and section splitting on top-level `<h2` starting a line. Tested with kramdown 2.4 (github-pages 232) and Jekyll 4; leftovers are detected by the checker.
+- kramdown differences that the checker does not flag: smart quotes and dashes (`"a" -- b` → “a” – b; GitHub leaves them), `#` headings indented one space are paragraphs, and `\|` inside a code span in a table cell keeps the backslash in kramdown (GitHub shows `|`). Avoid `|` in table code spans.
+- Liquid inside code (`{{ }}`) is still processed by Jekyll before kramdown; such pages need `{% raw %}` on the Jekyll side, which itself shows on GitHub.
+- The stylesheet uses Sass `@import` so it compiles with both Ruby Sass (GitHub Pages) and Dart Sass (Jekyll 4); Dart Sass prints deprecation warnings unless the site sets `sass: {silence_deprecations: [import, global-builtin]}` (jekyll-sass-converter ≥ 3.1). Custom properties holding Sass values must interpolate (`--x: #{$v}`); Ruby Sass prints `$v` literally.
+- Component classes are `mt-*`.
+- CTA buttons need `:has()`; without it they stay links.
+
+## 7. Design tokens artifact
+CI generates a DTCG `tokens.json` from the Sass token maps (`script/tokens-json`) and uploads it as a build artifact. It is read-only: edit the Sass maps, never the JSON. A test keeps it consistent with the built CSS.