# Docs that stay plain Markdown

jekyll-theme-modootoday turns standard GitHub Flavored Markdown into a clean documentation site. The same file reads well on github.com, on GitHub Pages and as a Markdown twin for AI agents.

[Get started](guides/install/) [Browse components](components/) [GitHub](https://github.com/modootoday/jekyll-theme-modootoday)

## Why modoo.today theme

- **Only standard Markdown** — Alerts, tables, lists and code blocks. No HTML, no Liquid, no kramdown extras in your pages.
- **Works on GitHub Pages** — Liquid-only theme for the classic `github-pages` build, and Jekyll 4 for everything else.
- **Agent-readable** — Every page has a byte-identical Markdown twin, plus `llms.txt` and `llms-full.txt`.

## Quick start

### remote_theme

```yaml
remote_theme: modootoday/jekyll-theme-modootoday@v1.4.1
plugins: [jekyll-remote-theme]
```

### Gemfile

```ruby
gem "jekyll-theme-modootoday", "~> 1.4"
```

### _config.yml

```yaml
theme: jekyll-theme-modootoday
permalink: pretty
```

## Your path through the docs

1. [Install](guides/install/) the theme on GitHub Pages or Jekyll 4.
2. [Write your first page](guides/first-page/) with plain Markdown.
3. Pick from the [components](components/) and the [kitchen sink](components/kitchen-sink/).
4. Tune it in [configuration](guides/configuration/) and [customize](guides/customize/) the look with tokens and `_sass`.
5. Make it [readable by agents](guides/agents/) with twins and `llms.txt`.

## Start now

[Install the theme](guides/install/) [See every component](components/kitchen-sink/)
# Blog

A sample blog index (`layout: blog`, `variant: magazine`). See the [Blog and news guide](../layouts/blog-news/).
# Categories

Every post, grouped by category. Categories also shape post URLs (`permalink: pretty`). See [Posts and archives](../reference/api/#posts-and-archives).
# Components

Each component is ordinary Markdown. Every example below shows the Markdown source and then the live result the theme renders from that same source, in the light or dark scheme you are using. Copy a source block into your page to get the same result. On github.com each one falls back to the plain element.

[Open the kitchen sink](kitchen-sink/) [Configuration](../guides/configuration/)

## Alerts

`status:available` A GitHub alert becomes a callout with a localized title. Five types: note, tip, important, warning and caution. Screen readers announce each one as a note (`role="note"`).

> [!NOTE]
> Useful information that users should know, even when skimming.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

## Alerts with content

An alert can hold lists and code. Leave nothing after the marker on its line.

> [!TIP]
> Before you publish:
>
> - run `modootoday-check`
> - preview with `bundle exec jekyll serve`

## Cards

`status:available` In a `c: features` section, each list item that starts with **bold** text becomes a card. The bold text is the card title; one separator after it (` — `, `: ` or the full-width `：`) is not shown, and colons later in the text stay. `cols: 2`, `cols: 3` or `cols: 4` sets the grid; narrow screens show one column, and `cols: 4` shows two columns on medium screens.

- **Plain Markdown** — Pages read well on github.com too.
- **With a badge** — Cards can carry status. `status:available`

With `badge: bottom`, a status badge at the end of an item sits at the card's bottom edge, so badges line up across a row.

## Cards in three columns

The same list with `cols: 3`. With `reveal: true`, the section fades in as it scrolls into view, only in browsers with scroll-driven animations and when the reader allows motion; elsewhere it is shown as is, with no script.

- **Alerts** — Five alert types.
- **Tabs** — Accessible code tabs.
- **Search** — Client-side search.

## Cards in four columns

The same idea with `cols: 4` on wide screens.

- **Alerts** — Five alert types.
- **Tabs** — Accessible code tabs.
- **Search** — Client-side search.
- **Cards** — Grids of two to four columns.

## Buttons

`status:available` A paragraph that holds only links becomes buttons. The first link is the primary one. It works in the hero (before the first `##`) and in a `c: cta` section.

[Get started](../guides/install/) [Read the configuration](../guides/configuration/)

## Tabs

`status:available` In a `c: tabs` section, each `###` heading followed by a code block becomes a tab. Use at least two. Keyboard: arrow keys move between tabs, and Home and End jump to the first and last. Without JavaScript every block stays visible under its heading.

### macOS

```sh
brew install ruby
```

### Linux

```sh
sudo apt install ruby-full
```

## Badges

`status:available` Code spans with a known prefix become badges: status (available, partial, planned) and tag. The status symbol is hidden from screen readers, and the label is read instead.

`status:available` `status:partial` `status:planned`

`tag:beta`

## Keyboard keys

`status:available` A code span that starts with kbd and a colon becomes keyboard keys. Join keys with `+` and no spaces.

Open search with `kbd:Ctrl+K`, or press `kbd:/`.

## Accordion

`status:available` In a `c: accordion` section, each `###` heading becomes a button that shows or hides the content under it (`aria-expanded`). Enter or Space toggles it. Without JavaScript every answer stays visible.

### Does it work without JavaScript?

Yes. Every answer stays visible under its question.

### Can an answer hold code?

```sh
bundle exec jekyll serve
```

## Steps

`status:available` In a `c: steps` section, an ordered list becomes numbered steps.

1. Add the theme to `_config.yml`.
2. Write `index.md` in plain Markdown.
3. Run `bundle exec jekyll build`.

## Steps as headings

Use `###` headings instead of a list when a step needs more than one line.

### Install

Add `remote_theme` and the plugin.

### Publish

Push to `main` and turn on GitHub Pages.

## Timeline

`status:available` In a `c: timeline` section, `###` headings become points on a line.

### Install

Alerts, sections, cards and tabs.

### Check

Theme toggle, breadcrumb and table of contents.

## Timeline as a list

An ordered list works too.

1. Install: alerts, sections and cards.
2. Write: design tokens and navigation.
3. Check: theme toggle and steps.

## Figure

`status:available` A paragraph with only an image, followed by a paragraph with only *emphasis*, becomes a figure with a caption. Alt text is required.

![A Markdown source on the left becomes a styled page on the right](../assets/images/sample.svg)

*Markdown on the left, the rendered page on the right.*

## Tables

`status:available` GFM tables scroll sideways on small screens instead of overflowing the page.

| Key | Default | Description |
|---|---|---|
| `color_scheme` | `auto` | follow the OS or force light or dark |
| `badges` | `true` | turn status code spans into badges |

## Code blocks

`status:available` Fenced code blocks are highlighted and get a copy button at the end of the first line. A long line scrolls, and the block can be reached with the keyboard.

```ruby
Jekyll::Hooks.register :site, :post_write do |site|
  puts "Built #{site.pages.size} pages"
end
```

## Code titles and diffs

`status:available` A line holding only a code span that starts with file and a colon, right before a fenced block, becomes the block's title bar. A `diff` block tints added and removed lines and keeps the plus and minus signs.

`file:_config.yml`

```yaml
theme: jekyll-theme-modootoday
```

```diff
- remote_theme: old/theme
+ theme: jekyll-theme-modootoday
```

## Progress

`status:available` A code span that starts with progress and a colon, followed by a whole number from 0 to 100, becomes a labelled progress bar with the value as text.

Translation `progress:60`

## Embeds

`status:available` A paragraph holding only a code span that starts with embed and a colon, then an https URL and an optional title, becomes a lazy 16:9 frame that keeps its space while it loads.

`embed:https://modootoday.github.io/jekyll-theme-modootoday/assets/images/sample.svg Sample page drawing`

## Loading and skeletons

`status:available` Code spans that start with loading or skeleton and a colon become a spinner, a thin top bar or a placeholder (text, card, image, avatar, row). Each one has `role="status"` and a Loading label for screen readers, and the motion stops when the reader asks for reduced motion. Their styles are an optional sheet that only pages using them load.

`loading:spinner`

`skeleton:avatar`
`skeleton:text`
`skeleton:card`

## File tree

`status:available` In a `c: filetree` section, a nested list draws a folder tree. Items that hold a nested list are folders.

- docs
  - _config.yml
  - index.md
  - ko
    - index.md

## Details

`status:available` In a `c: details` section, each `###` heading becomes a native disclosure. It opens and closes without JavaScript.

### What does it need?

Nothing but the browser.

## FAQ

`status:available` A `c: faq` section works like details. For FAQPage structured data, add a `schema:` block (see [Structured data](../guides/structured-data/)).

### Is the theme free?

Yes, under the MIT license.

### Does it run on GitHub Pages?

Yes, with the github-pages gem.

## Parameter table

`status:available` In a `c: params` section, a table lists options: name, type, default, description. A cell holding only `required` shows a Required badge.

| Name | Type | Default | Description |
|---|---|---|---|
| `title` | string | `required` | Page title |
| `cols` | number | 2 | Card columns |

## Link cards

`status:available` In a `c: linkcards` section, list items that start with a link become cards. The whole card is the link target.

- [Install](../guides/install/) — Add the theme to a site.
- [Configuration](../guides/configuration/) — Every setting in one place.

## Quote

`status:available` In a `c: quote` section, a quote whose last line starts with an em dash gets that line as its attribution.

> The docs read well on github.com and on the site.
>
> — A theme user

## Gallery

`status:available` In a `c: gallery` section, a list of images becomes a thumbnail grid. Each thumbnail opens a full-size view without JavaScript. Every image needs alt text.

- ![A sunlit room with a plant and an armchair](../assets/images/gallery/room.webp)
- ![Pink sand dunes under a low sun](../assets/images/gallery/dunes.webp)
- ![Tropical leaves around a still pond](../assets/images/gallery/leaves.webp)
- ![A wooden pier on a mountain lake](../assets/images/news/travel-sm.webp)
- ![Wind turbines and solar panels on green hills](../assets/images/news/energy-sm.webp)
- ![Fanned swatches in cream, violet and coral](../assets/images/projects/brand.webp)

## Pricing

`status:available` In a `c: pricing` section, each `###` heading is a plan with a price, a feature list and a link. The `recommended` parameter marks one plan with a Recommended label.

### Free

**$0**

- One site

[Start the Free plan](#)

### Team

**$12**

- Ten sites
- Support

[Choose Team](#)

## Subscribe

`status:available` A `c: subscribe` section prints its text and an email form that posts to the address in `modootoday.subscribe.action`. Without that setting it shows only the text. Here the item also has `bleed: true`: any section item or `hero:` can take it to get a full-width background band in `--mt-bleed-bg` (default the muted surface) while its content keeps the reading column, and `bleed: wide` also widens the content up to the container width. With a sidebar or table of contents the band stays inside the main column.

Get one email when a release ships.


## Split

`status:available` A `c: split` section puts its text and a picture side by side from 48rem and stacks them below. The picture is the `visual:` include; `side: start` moves it to the start side and `ratio: "5:7"` gives it the wider column. Any other key on the item, such as `label:` here, reaches the include as `include.section.label`. The picture here is an illustration: a `figure` with `class="mt-illustration"`, `role="img"` and an `aria-label`, plus an `.mt-illustration-tag` badge whose text is also in the label. `decor: decor-demo` adds the dots in the top corner as an `aria-hidden` ornament. The hero takes the same form: `hero: {c: split, visual: <name>, side: start, ratio: "5:7"}` puts the title, lead, check row and buttons in the text column and the include beside them.`status:available` A `c: split` section puts its text and a picture side by side from 48rem and stacks them below. The picture is the `visual:` include; `side: start` moves it to the start side and `ratio: "5:7"` gives it the wider column. Any other key on the item, such as `label:` here, reaches the include as `include.section.label`. The picture here is an illustration: a `figure` with `class="mt-illustration"`, `role="img"` and an `aria-label`, plus an `.mt-illustration-tag` badge whose text is also in the label. `decor: decor-demo` adds the dots in the top corner as an `aria-hidden` ornament. The hero takes the same form: `hero: {c: split, visual: <name>, side: start, ratio: "5:7"}` puts the title, lead, check row and buttons in the text column and the include beside them.

`visual: code` on a `c: split` section or a split hero needs no include: the first fenced code block in that section, with its `file:` title if it has one, moves into the visual column and keeps the code styles and the copy button. `chrome: terminal` (its own small sheet, linked only where used) adds a border and a decorative bar that screen readers skip. Anywhere else, `visual: code` still means `_includes/sections/code.html`.

Text on one side, the picture on the other.

## Lists

`status:available` With `modootoday.lists` in `_config.yml`, plain sections and pages get two list styles. `link_chips: true` turns a list whose every item is one link into a row of chips; `titled_items: true` gives an item that starts with a bold title and a colon its own title and separator. `hero: {checks: true}` turns the first list in the hero into a row of check marks, as above. Lists in component sections keep their own style.

- [Install](../guides/install/)
- [Configuration](../guides/configuration/)
- [Accessibility](../guides/accessibility/)

Items with a title:

- **Chips**: a list of links only
- **Titled items**: a bold title, a colon, then the text

## Navigation

`status:available` The header menu comes from `_data/nav/main.yml`. An entry with `items:` becomes a dropdown group on wide screens, and narrow screens get a menu button. Esc closes an open menu. The result is the header of this page.

```yaml
- {title: Install, url: /install/}
- {title: Components, url: /components/}
- title: More
  items:
    - {title: Public API, url: /api/}
```

## Language switcher

`status:available` With `languages:` and `language_switcher: header`, the header gets a globe button that opens a list of languages. It stays the same width however many languages you add. Each language is named in its own language, and the current one has `aria-current`. Esc closes the list. The result is the globe in the header of this page.

```yaml
modootoday:
  languages: [en, ko, ja]
  language_switcher: header
```

## Theme toggle

`status:available` The header button switches between light and dark and remembers the choice. Use `color_scheme` to fix one scheme. The result is the button in the header of this page.

```yaml
modootoday:
  color_scheme: auto   # auto | light | dark
```

## Icons and logo

`status:available` The theme draws its icons (globe, sun and moon, search, alert types, copy, edit, previous and next, external link, breadcrumb arrows) as inline SVG in `currentColor`, so they follow the light or dark scheme and need no extra requests. Icons are hidden from screen readers; each icon-only button has its own name. Arrows that point a direction flip in right-to-left pages. Set `logo` to put the modootoday mark (or your own image) before the site title, and `favicon` to add the matching browser icons. The result is the header and footer of this page.

```yaml
modootoday:
  logo: brand        # brand | /assets/img/logo.svg
  favicon: brand     # brand | /favicon.ico
```

## Search

`status:available` Client-side search over a `search.json` file, in the header (`role="search"`). Press `kbd:Ctrl+K` or `kbd:/` to focus it. Add a `search.json` file at the site root to turn it on: copy [the one this site uses](https://github.com/modootoday/jekyll-theme-modootoday/blob/main/docs/search.json). The result is the search box in the header of this page.

## Breadcrumb and table of contents

`status:available` Doc pages get a breadcrumb from the URL, and a table of contents from the `##` and `###` headings: at the side on wide screens and in a folding box on narrow ones. Both are added by the layout, so there is no source to write. Leave out `breadcrumb` or `toc` from `components` to turn them off. The result is at the top and side of this page.

```yaml
modootoday:
  components: [callout, badge, hero, cta, card, tabs, code-copy, nav, pagination, theme-toggle]
```

## Previous and next

`status:available` Pages listed in the nav get previous and next links in nav order. Set `pagination: false` in front matter to hide them. The result is at the bottom of this page.

```yaml
---
title: Components
pagination: false
---
```

## Posts and archives

`status:available` `layout: post` shows the date, author and tags (`p.mt-post-meta`).

```yaml
---
layout: post
title: Hello
date: 2026-10-30
author: Won
tags: [release]
---
```

## Status legend

| Badge | Meaning |
|---|---|
| `status:available` | shipped and stable |
| `status:partial` | works with known limits |
| `status:planned` | on the roadmap |

## Next

[Kitchen sink](kitchen-sink/) [Configuration](../guides/configuration/)
# Kitchen sink

Every component the theme ships, in every variant. The same file is readable on github.com, which shows the fallback.

- Plain Markdown
- Reads on github.com
- WCAG 2.2 AA

[Primary action](#) [Secondary](#) [Third link](#)

## Alerts

> [!NOTE]
> Useful information that users should know, even when skimming.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

> [!NOTE]
> An alert with more content:
>
> - a list item with `inline code`
> - a second item with a link to the [components index](../)
>
> ```sh
> echo "code inside an alert"
> ```

## Cards in two columns

- **Short** — One line.
- **Longer card** — A card with a longer description that wraps over several lines to check spacing, line height and alignment across the grid.
- **With a badge** — Cards can carry status. `status:available`
- **With a link** — Read the [install guide](../../guides/install/).

## Cards in three columns

- **Alerts** — Five GitHub alert types. `status:available`
- **Tabs** — Accessible install tabs. `status:partial`
- **Search** — Example of a planned item. `status:planned`
- **Tokens** — Colors, radius and fonts. `status:available`
- **Sass** — One partial per component. `status:available`
- **Twins** — Markdown for agents. `status:available`

## Cards in four columns

- **Alerts** — Five GitHub alert types. `status:available`
- **Tabs** — Accessible install tabs. `status:partial`
- **Search** — Example of a planned item. `status:planned`
- **Tokens** — Colors, radius and fonts. `status:available`
- **Sass** — One partial per component. `status:available`
- **Twins** — Markdown for agents. `status:available`
- **Grid** — Four across on wide screens.
- **Rows** — Eight cards fill two rows.

## Tabs with two panels

### macOS

```sh
brew install ruby
gem install jekyll bundler
```

### Linux

```sh
sudo apt install ruby-full
gem install jekyll bundler
```

## Tabs with many panels

### Ruby

```ruby
puts "Hello"
```

### JavaScript

```js
console.log("Hello");
```

### Python

```python
print("Hello")
```

### Shell

```sh
echo Hello
```

### A tab with a much longer name

```yaml
greeting: Hello
```

## Status badges

Inline badges: `status:available` `status:partial` `status:planned`

Tag badges: `tag:beta` `tag:experimental`

| Feature | Status |
|---|---|
| Alerts | `status:available` |
| Tabs | `status:partial` |
| Search | `status:planned` |

## Accordion

### What is the kitchen sink for?

It shows every component in one place, so visual regressions are easy to spot.

### Does it work without JavaScript?

Yes. Without JavaScript every answer stays visible under its question.

### Can an answer hold code?

```sh
bundle exec jekyll serve
```

## Steps as a list

1. Add the theme to `_config.yml`.
2. Write `index.md` in plain Markdown.
3. Run `bundle exec jekyll build`.
4. Check the result with `modootoday-check`.

## Steps as headings

### Install

Add `remote_theme` and the plugin.

### Write

Create a page with front matter.

### Publish

Push to `main` and turn on GitHub Pages.

## Figure

![A Markdown source on the left becomes a styled page on the right](../../assets/images/sample.svg)

*An image-only paragraph followed by an emphasis-only paragraph becomes a figure with a caption.*

## Timeline

### Install

Alerts, sections, cards, tabs, status badges and the checker.

### Write

Design tokens, the `modootoday:` block, navigation and code copy.

### Check

Theme toggle, breadcrumb, table of contents, accordion, steps and figures.

### Publish

Timeline, keyboard keys, client search and the post layout.

## Timeline as a list

1. Install: alerts, sections, cards and tabs.
2. Write: design tokens and navigation.
3. Check: theme toggle, table of contents and steps.

## Keyboard keys

Open search with `kbd:Ctrl+K`, or `kbd:/` on its own. Copy with `kbd:Cmd+C`.

## Tables

| Key | Type | Default | Description |
|---|---|---|---|
| `badges` | boolean | `true` | Convert status code spans into badges |
| `color_scheme` | string | `auto` | Follow the operating system or force a scheme |
| `components` | list | all core components | Limit the CSS and JavaScript that are shipped to the browser |
| `tokens` | map | theme defaults | Override design tokens such as primary color, radius and font stacks |

| Left | Center | Right |
|:---|:---:|---:|
| a | b | 1 |
| longer cell | centered | 1,000 |

## Code

Inline `code`, a fenced block and a long line that scrolls:

```ruby
# frozen_string_literal: true
Jekyll::Hooks.register :site, :post_write do |site|
  puts "Built #{site.pages.size} pages into #{site.dest} with a deliberately long line to test horizontal scrolling"
end
```

```diff
- theme: minima
+ theme: jekyll-theme-modootoday
```

## Typography

Paragraph text with **bold**, *italic*, ~~strikethrough~~, `code` and a link to the [components index](../). Footnotes work too.[^1]

### Heading level 3

#### Heading level 4

1. Ordered item
2. Ordered item
   - nested bullet
   - nested bullet

- [x] task done
- [ ] task open

> A plain quote that is not an alert.

---

Text after a thematic break.

[^1]: A footnote.

## Call to action

[Get started](../../guides/install/) [Read the rules](https://github.com/modootoday/jekyll-theme-modootoday/blob/main/RULES.md)

## Code titles and diffs

`status:available` A line holding only a code span that starts with file and a colon, right before a fenced block, becomes the block's title bar. A `diff` block tints added and removed lines and keeps the plus and minus signs.

`file:_config.yml`

```yaml
theme: jekyll-theme-modootoday
```

```diff
- remote_theme: old/theme
+ theme: jekyll-theme-modootoday
```

## Progress

`status:available` A code span that starts with progress and a colon, followed by a whole number from 0 to 100, becomes a labelled progress bar with the value as text.

Translation `progress:60`

## Embeds

`status:available` A paragraph holding only a code span that starts with embed and a colon, then an https URL and an optional title, becomes a lazy 16:9 frame that keeps its space while it loads.

`embed:https://modootoday.github.io/jekyll-theme-modootoday/assets/images/sample.svg Sample page drawing`

## Loading and skeletons

`status:available` Code spans that start with loading or skeleton and a colon become a spinner, a thin top bar or a placeholder (text, card, image, avatar, row). Each one has `role="status"` and a Loading label for screen readers, and the motion stops when the reader asks for reduced motion. Their styles are an optional sheet that only pages using them load.

`loading:spinner`

`skeleton:avatar`
`skeleton:text`
`skeleton:card`

## File tree

`status:available` In a `c: filetree` section, a nested list draws a folder tree. Items that hold a nested list are folders.

- docs
  - _config.yml
  - index.md
  - ko
    - index.md

## Details

`status:available` In a `c: details` section, each `###` heading becomes a native disclosure. It opens and closes without JavaScript.

### What does it need?

Nothing but the browser.

## FAQ

`status:available` A `c: faq` section works like details. For FAQPage structured data, add a `schema:` block (see [Structured data](../../guides/structured-data/)).

### Is the theme free?

Yes, under the MIT license.

### Does it run on GitHub Pages?

Yes, with the github-pages gem.

## Parameter table

`status:available` In a `c: params` section, a table lists options: name, type, default, description. A cell holding only `required` shows a Required badge.

| Name | Type | Default | Description |
|---|---|---|---|
| `title` | string | `required` | Page title |
| `cols` | number | 2 | Card columns |

## Link cards

`status:available` In a `c: linkcards` section, list items that start with a link become cards. The whole card is the link target.

- [Install](../../guides/install/) — Add the theme to a site.
- [Configuration](../../guides/configuration/) — Every setting in one place.

## Quote

`status:available` In a `c: quote` section, a quote whose last line starts with an em dash gets that line as its attribution.

> The docs read well on github.com and on the site.
>
> — A theme user

## Gallery

`status:available` In a `c: gallery` section, a list of images becomes a thumbnail grid. Each thumbnail opens a full-size view without JavaScript. Every image needs alt text.

- ![A sunlit room with a plant and an armchair](../../assets/images/gallery/room.webp)
- ![Pink sand dunes under a low sun](../../assets/images/gallery/dunes.webp)
- ![Tropical leaves around a still pond](../../assets/images/gallery/leaves.webp)
- ![A wooden pier on a mountain lake](../../assets/images/news/travel-sm.webp)
- ![Wind turbines and solar panels on green hills](../../assets/images/news/energy-sm.webp)
- ![Fanned swatches in cream, violet and coral](../../assets/images/projects/brand.webp)

## Pricing

`status:available` In a `c: pricing` section, each `###` heading is a plan with a price, a feature list and a link. The `recommended` parameter marks one plan with a Recommended label.

### Free

**$0**

- One site

[Start the Free plan](#)

### Team

**$12**

- Ten sites
- Support

[Choose Team](#)

## Subscribe

`status:available` A `c: subscribe` section prints its text and an email form that posts to the address in `modootoday.subscribe.action`. Without that setting it shows only the text. Here the item also has `bleed: true`: any section item or `hero:` can take it to get a full-width background band in `--mt-bleed-bg` (default the muted surface) while its content keeps the reading column, and `bleed: wide` also widens the content up to the container width. With a sidebar or table of contents the band stays inside the main column.

Get one email when a release ships.

## Split

`status:available` A `c: split` section puts its text and a picture side by side from 48rem and stacks them below. The picture is the `visual:` include; `side: start` moves it to the start side and `ratio: "5:7"` gives it the wider column. Any other key on the item, such as `label:` here, reaches the include as `include.section.label`. The picture here is an illustration: a `figure` with `class="mt-illustration"`, `role="img"` and an `aria-label`, plus an `.mt-illustration-tag` badge whose text is also in the label. `decor: decor-demo` adds the dots in the top corner as an `aria-hidden` ornament. The hero takes the same form: `hero: {c: split, visual: <name>, side: start, ratio: "5:7"}` puts the title, lead, check row and buttons in the text column and the include beside them; the kitchen sink's hero uses it.

Text on one side, the picture on the other.

## Split with code

`status:available` `visual: code` on a `c: split` section or a split hero needs no include: the first fenced code block in that section, with its `file:` title if it has one, moves into the visual column and keeps the code styles and the copy button. `chrome: terminal` (its own small sheet, linked only where used) adds a border and a decorative bar that screen readers skip. Anywhere else, `visual: code` still means `_includes/sections/code.html`.

Install the kit, then run the checker before each build.

`file:terminal`

```sh
bundle add jekyll-theme-modootoday
bundle exec modootoday-check . _site
```

## Lists

`status:available` With `modootoday.lists` in `_config.yml`, plain sections and pages get two list styles. `link_chips: true` turns a list whose every item is one link into a row of chips; `titled_items: true` gives an item that starts with a bold title and a colon its own title and separator. `hero: {checks: true}` turns the first list in the hero into a row of check marks, as above. Lists in component sections keep their own style.

- [Install](../../guides/install/)
- [Configuration](../../guides/configuration/)
- [Accessibility](../../guides/accessibility/)

Items with a title:

- **Chips**: a list of links only
- **Titled items**: a bold title, a colon, then the text
# Guides

Start here, in order.

<!-- spec:docs-index:begin -->
- [Install](install/) — Add the theme to a GitHub Pages or Jekyll 4 site.
- [First page](first-page/) — Write a page with front matter, sections and alerts.
- [Configuration](configuration/) — Site-wide settings under the modootoday key in _config.yml.
- [Customize](customize/) — Change colors, radius and fonts with tokens, or override Sass partials.
- [Agents](agents/) — Markdown twins, llms.txt and llms-full.txt for AI agents.
- [Migrate](upgrade/) — Move a site from another Jekyll theme, adopt the theme in an existing project, and upgrade between versions.
- [Accessibility](accessibility/) — Keyboard use, screen readers, safe areas, touch targets, high contrast and reduced motion.
- [Structured data](structured-data/) — The schema.org JSON-LD graph the theme prints on every page, and how to configure it.
- [Translation rules](translation/) — The canonical style rules, glossary and lint for the Korean and Japanese docs and interface strings.
<!-- spec:docs-index:end -->
# Accessibility

The theme aims for WCAG 2.2 AA with no setup. This page lists what it does for readers and the two settings that change it.

## Keyboard

| Key | Where | Action |
|---|---|---|
| `Tab` | any page | the first stop is "Skip to content", which moves focus to the main text |
| `/` or `Ctrl`+`K` (`Cmd`+`K` on macOS) | any page with search | focus the search box (`/` is ignored while you type in a field) |
| `↓` `↑` | search results | move between results and back to the box |
| `Esc` | search | leave the results, or clear the box |
| `←` `→` `Home` `End` | tabs | switch tabs; left and right follow the reading direction in right-to-left pages |
| `↓` `↑` `Esc` | language menu, nav "More" menu, page actions | move between items; `Esc` closes and returns focus |
| `Tab` | wide code blocks and tables | a block that scrolls sideways becomes a labelled region you can focus and scroll with the arrow keys |

Focus is always visible. Inside tabs, panels and scroll regions the focus ring is drawn inside the box so it is not clipped.

## Screen readers

Landmarks (header, navigation, main, footer), the current page in navigation, breadcrumbs and the language menu (`aria-current`), and labels for icon buttons, code blocks and tables are built in. Labels follow `lang:` in 23 languages (see [Configuration](../configuration/#languages)). Icons are decorative unless they carry a label.

## Phones and tablets

- **Safe areas.** Pages extend under the notch, rounded corners and home indicator, and the header, side padding and footer move clear of them.
- **Touch targets.** On touch screens, links in the header, menus, tabs, copy buttons and pagination are at least 44 px tall, and the search box uses 16 px text so iOS does not zoom.
- **Browser colour.** The address bar matches the page background in light and dark mode.

## High contrast and motion

- With Windows high contrast (forced colours), icon buttons and the search box keep visible borders.
- With "reduce motion" turned on, transitions and animations are off.

## Settings

```yaml
modootoday:
  viewport_fit: auto           # default: cover (draw under the notch with safe-area padding)
  theme_color: {light: "#ffffff", dark: "#0d1117"}  # or one "#hex", or false
```

| Key | Default | Effect |
|---|---|---|
| `viewport_fit` | `cover` | `auto` keeps the page inside the safe area, letting the browser add the margins |
| `theme_color` | page background | colour of the browser bar; one `"#hex"`, `{light, dark}`, or `false` to drop the tags |

Your own CSS can read the insets as `--mt-safe-top`, `--mt-safe-right`, `--mt-safe-bottom` and `--mt-safe-left`.

## Your content

The theme cannot fix the content itself. `modootoday-check` reports the common problems before you publish:

- **Images:** give every image `alt` text that says what it shows (`![Sales doubled in May](chart.png)`). Use empty `alt` only when the image adds nothing; an HTML `<img>` without `alt` is an error.
- **Illustrations and ornaments:** a drawn scene in an include is `<figure class="mt-illustration" role="img" aria-label="…">`; the label says what it shows and repeats any `.mt-illustration-tag` text, because screen readers skip the children of `role=img`. `modootoday-check` reports an `.mt-illustration` without them. Pure decoration goes in `decor:`, which the theme hides from assistive technology.
- **Links:** the text must name the destination, so it makes sense when read alone. Empty links are an error; "click here" or "read more" is a warning. Mention the file type for downloads, for example `[Price list (PDF, 2 MB)](prices.pdf)`.
- **Headings:** the page title is the only `#` heading; start content at `##` and do not skip a level (`##` then `####` is a warning). Screen-reader users jump between headings by level.
- **Tables:** give every table a header row, and introduce it with a sentence or heading that says what it lists.
- **IDs:** an `id` used twice on one page is an error; it breaks anchors and labels.
- **Language:** set `lang:` on every translated page, so screen readers pick the right voice. Right-to-left languages get `dir="rtl"` automatically.

Search results are announced as they appear, and copy buttons announce when the text has been copied.
# Agent-readable Markdown

Every page is published twice: as HTML for people and as its original Markdown for agents.

## Markdown twins

A page `guide.md` is also served at `/guide/index.md`, byte-identical to its body. On Jekyll 4 the theme plugin creates twins automatically:

```yaml
plugins: [jekyll-theme-modootoday]
```

The classic GitHub Pages build cannot run plugins, so add a stub next to each page instead:

```yaml
# guide.md.txt
---
layout: twin
twin_of: guide.md
permalink: /guide/index.md
---
```

`twin_of` is a path relative to the stub file (it is read with `include_relative`), so keep the stub in the same folder as its page or use `../` paths. It cannot point outside the site source or into `_` folders.

```yaml
# guides/install.md.txt, next to guides/install.md
twin_of: install.md          # correct: relative to the stub
twin_of: guides/install.md   # wrong: a path from the site root fails with "Could not locate the included file"
```

Each HTML page links its twin with `rel="alternate" type="text/markdown"`.

## llms.txt

`/llms.txt` lists every page of a language, following [llmstxt.org](https://llmstxt.org). `/llms-full.txt` concatenates every page body. Both come from one-line stubs:

```yaml
---
layout: llms
---
```

Try them on this site: [llms.txt](../../llms.txt) and [llms-full.txt](../../llms-full.txt).

## Next

[Changelog](../../reference/changelog/) [Home](../../)
# Configuration

Everything is optional. Settings live under one `modootoday:` key so they never clash with other plugins.

## Keys

```yaml
modootoday:
  color_scheme: auto  # auto | auto-dark | auto-light | light | dark
  components: [callout, badge, cta, card, tabs]
  tokens: {primary: "#4f46e5", radius: "0.5rem"}
  nav: main
```

| Key | Default | Effect |
|---|---|---|
| `badges` | `true` | turn status code spans into badges; `false` keeps code |
| `color_scheme` | `auto` | `auto` follows the OS; `auto-dark` or `auto-light` starts dark or light and keeps the toggle (the reader's choice is remembered); `light` or `dark` forces one scheme without a toggle. The starting scheme is printed in the HTML, so nothing flashes |
| `components` | all | limit the CSS and JS that are shipped. `lists`, `bleed` and `terminal` are always included: their sheets reach only pages that turn them on with `lists:` or `hero: {checks: true}`, `bleed:` and `chrome: terminal` |
| `css_layers` | `false` | wrap the theme CSS in `@layer mt.*` |
| `nav` | `main` | navigation file in `_data/nav/`; an entry with `items:` becomes a group. Previous/next links walk the file in order: a group's own page, then its items |
| `sidebar` | `auto` | `auto` adds a sidebar to `doc` pages when the nav has groups; `true` always, `false` never. Below 64rem it folds into a menu above the page. `sidebar: false` in front matter hides it on one page |
| `page_actions` | `true` | on pages with a Markdown twin, a menu with View as Markdown, Copy page and Copy for AI (copies the source URL, then the Markdown). `false` here or in front matter turns it off; leave `page-actions` out of `components` to drop it entirely |
| `tokens`, `tokens_dark` | theme values | override semantic design tokens inline |
| `twins` | stubs | `source` for front-matter-less twins (see [Agents](../agents/)) |
| `seo` | `true` | `false` drops the built-in canonical, hreflang and Open Graph tags |
| `hreflang` | follows `seo` | `true` keeps the `hreflang` alternates when `seo: false` (for sites that bring `jekyll-seo-tag`) |
| `schema` | on when `url` is set | schema.org JSON-LD graph: `publisher`, `search_url`, `layouts`; `false` turns it off. See [Structured data](../structured-data/) |
| `languages` | none | language codes for `hreflang`, such as `[en, ko]` The header site title links to the page language's home (`/<lang>/`) when it exists. |
| `full_languages` | none | the codes from `languages` that translate every page, such as `[ko, ja]`; `modootoday-check --i18n-pages` warns about each default-language page without one |
| `lists` | none | `{link_chips: true, titled_items: true}`: on plain sections and pages, a list of links only becomes `ul.mt-chips` and an item starting with `**Title**:` gets `strong.mt-item-title`; the optional `lists` sheet styles them (and `hero: {checks: true}`) and is linked only where used |
| `language_switcher` | none | `header` (a globe button with a dropdown menu; same width however many languages) or `footer` (a list of language names) shows a language switcher built from `languages`; each link goes to this page's translation, or that language's home page. Nothing renders with fewer than two languages. The menu opens without JavaScript; `menu.js` adds Esc, arrow keys and closing on an outside click |
| `og_image` | none | default Open Graph image; `image:` in front matter wins |
| `feed` | `false` | `true` links `/feed.xml` (add `jekyll-feed` to `plugins`) |
| `logo` | none | `brand` puts the theme's brand mark before the site title in `currentColor` (the `brand` token, so it follows light and dark); a path shows your own image instead (decorative, `alt=""`). Override `modootoday/brand/logo.html` to draw something else |
| `favicon` | none | `brand` links the theme's brand mark as SVG, 32 px PNG and Apple touch icon; a path links your own icon |
| `csp` | none | `strict` loads the pre-paint script from a file instead of inline |
| `viewport_fit` | `cover` | `auto` keeps the page inside the safe area instead of drawing under the notch (see [Accessibility](../accessibility/#settings)) |
| `theme_color` | page background | browser bar colour: one `"#hex"`, `{light: "#hex", dark: "#hex"}`, or `false` to drop the tags |
| `edit_url` | none | prefix for an "Edit this page" link, ending in `/` |
| `archive` | none | archive page URLs, such as `{tags: /tags/, categories: /categories/}`; post footers link here (see [Posts and archives](../../reference/api/#posts-and-archives)) |
| `mermaid` | off | `{enabled: true, src:, integrity:, theme: auto}` renders ```` ```mermaid ```` fences on the pages that have one; `src` is a version-pinned https URL with an SRI `integrity` hash, or a path on your site. A CDN adds its origin to `script-src` and sends visitors' IP addresses to it; see [Math and diagrams](../../recipes/math-diagrams/#built-in-loaders) |
| `math` | off | `{enabled: true, engine: katex, src:, css:, integrity: {js:, css:}, auto_render_src:, auto_render_integrity:, inline: false}` renders ```` ```math ```` fences and `$$` blocks with KaTeX on the pages that have one; `inline: true` also renders `$…$`. A CDN adds its origin to `script-src`, `style-src` and `font-src`; see [Math and diagrams](../../recipes/math-diagrams/#csp-and-privacy) |
| `external_links` | none | `new_window: true` opens every external link (not starting with `url:`) in a new window; `icon: false` hides the arrow; see [Links that open a new window](#links-that-open-a-new-window) |
| `blog` | none | blog settings (`per_page`, `variant`, `related`, `share`, `reading_time`, ...); see [Blog and news](../../layouts/blog-news/#settings) |
| `news` | none | news settings, such as `sections:` for the front page; see [Blog and news](../../layouts/blog-news/#settings) |
| `css` | `split` | `split` links a small core sheet plus only the component sheets a page uses; `bundle` links one sheet with everything |
| `banner` | none | `{text: "…", url: /path/, link: "Read more"}` shows a site-wide announcement bar under the skip link |
| `back_to_top` | `false` | `true` adds a Back to top link at the end of every page |
| `loading` | `false` | `true` loads the spinner and skeleton sheet on every page, for placeholders your own scripts add; pages that use them in Markdown load it on their own |
| `subscribe` | none | `{action: https://…}` is where the `c: subscribe` email form posts |

`modootoday-check` validates every key. The full list of stable names is in [Public API](../../reference/api/).

## Links that open a new window

Opening a new window is opt-in. Set it per link or for every external link.

```yaml
# _config.yml: every external link
modootoday:
  external_links:
    new_window: true
    icon: true        # false hides the arrow
```

```yaml
# per link: nav items, cards, buttons, link cards, directory items, pricing cta, footer links
- {title: "Status page", url: "https://status.example.com", new_window: true}
- {title: "Forum", url: "https://forum.example.com", target: _blank}
```

```markdown
[Release notes](https://github.com/modootoday/jekyll-theme-modootoday/releases "new-window")
```

Each such link gets `target="_blank"`, `rel="noopener noreferrer"`, a small arrow drawn in CSS, and a hidden hint ("opens in a new window", translated into the page language) that screen readers read through `aria-describedby`. There is no script, so a strict Content Security Policy keeps working. `new_window: false` on a link turns it off even when the site setting is on.

## Head and SEO

With `url:` set, every page gets a canonical link and Open Graph tags; no plugin is needed. With `languages:` set, pages that exist in several languages link each other with `hreflang`. Sitemaps and feeds are opt-in plugins that GitHub Pages allows:

```yaml
url: https://example.github.io
modootoday:
  languages: [en, ko]
  edit_url: https://github.com/OWNER/REPO/edit/main/docs/
plugins: [jekyll-remote-theme, jekyll-sitemap, jekyll-feed]
```

To use `jekyll-seo-tag` instead, set `seo: false` and put the jekyll-seo-tag `seo` tag in `_includes/head-custom.html`. A page can show its date with `last_modified_at:` in front matter. The first breadcrumb shows the home page `short_title:` (front matter) when set, otherwise its `title`. Strict Content Security Policy: see [CSP](../../recipes/csp/).

## Languages

Put interface strings in `_data/i18n/<lang>.yml` and pages in `<lang>/`:

```yaml
language: 한국어
site_title: 모두의오늘 테마   # header, <title>, og:site_name and JSON-LD name; falls back to site.title
callout: {note: 참고, tip: 팁, important: 중요, warning: 경고, caution: 주의}
tabs: {label: 설치 방법}
status: {available: 사용 가능, partial: 일부 구현, planned: 계획}
skip: 본문으로 건너뛰기
```

Set `lang:` and the theme's own labels (skip link, navigation, callouts, status badges, table of contents, pagination, code copy, search, language menu) are already localized for 23 languages: en, zh-CN, zh-TW, ja, ko, tr, ru, vi, th, de, es, fr, uk, pl, pt-BR, ar, fa, id, it, el, ml, ur-Latn, ro. Nothing needs to be copied, on GitHub Pages or with Jekyll 4. A code with a region the theme does not ship uses its base language (`pt` → pt-BR, `zh` → zh-CN); any other language shows English.

Each label is resolved in this order:

1. your `_data/i18n/<lang>.yml`, key by key
2. the theme's catalog for that language
3. English

So a site catalog only needs the keys you want to change, plus anything your own components read. Use the `.yml` extension; the checker rejects `.yaml`. To start from the theme's wording, copy a catalog and check it:

```sh
modootoday-check . _site --i18n-init=ko   # optional: copy the theme's ko.yml to edit
modootoday-check . _site --i18n           # unknown keys and placeholder mismatches
```

For a language the theme does not ship, add `_data/i18n/<code>.yml` with the keys of the English catalog and list the code in `languages`. Pages get `dir="rtl"` for Arabic, Persian, Hebrew, Urdu and other right-to-left languages (`ur-Latn` stays left-to-right); `direction: rtl` or `ltr` in a catalog or in front matter overrides it. Page content is translated as Markdown in `<lang>/`, not in the catalogs.

Pages that translate each other under different paths share a `ref:` in front matter, such as `ref: guide` on `guides/start.md` and `ko/guides/sijak.md`. `hreflang` links and the language switcher then use that page; a page with `ref:` and no translation is left out of `hreflang`, and the switcher sends that language to its home page. In includes and layouts, `modootoday/link.html` with `ref="guide"` gives the URL of the `ref: guide` page in the current language, or in the default language when there is none (add `exact=true` for no fallback, `absolute=true` for a full URL); `modootoday-check` reports a `ref=` that no page defines. With `full_languages` set, `modootoday-check . _site --i18n-pages` lists default-language pages that have no translation in those languages (same `ref:`, or the same path under `<lang>/`); they are warnings, and `--strict` makes them fail.

Some labels are your site's, not the theme's: `tabs.label` names the tab list on pages that use tabs (for example `tabs: {label: Install method}`), so screen readers announce what the tabs choose between. Put it in each language's catalog.

In your own includes, `modootoday/t.html` with `key="nav.label"` prints a label with the same resolution.

## Component registry

An optional `_data/components.yml` lets the checker validate `sections:` parameters:

```yaml
features: {params: {cols: {allowed: [2, 3, 4], required: false}, badge: {allowed: [bottom], required: false}}}
tabs: {i18n: [tabs.label]}
cta: {}
```

## Next

[Customize the look](../customize/) [Components](../../components/)
# Customize

Start with tokens. Reach for Sass partials only when tokens are not enough.

## Design tokens

The theme exposes CSS custom properties. Override them in your own stylesheet or with `modootoday.tokens`:

```css
:root {
  --mt-primary: #0f766e;
  --mt-radius: 0.75rem;
}
```

Overrides in your own stylesheet need to beat the theme's dark-scheme selectors (`:root[data-theme]` and the `prefers-color-scheme` rule). Two supported ways:

- Put the values in `modootoday.tokens` and `modootoday.tokens_dark`. The theme prints them with the same selectors as its own tokens.
- Set `modootoday.css_layers: true`. The theme CSS then sits in `@layer mt.*`, and any rule outside a layer wins, so a plain `:root { … }` is enough.

Images in dark mode: photos use `--mt-img-filter-dark`; `.svg` figures (diagrams) use `--mt-diagram-filter-dark`, which inverts them with the hues kept and then applies `--mt-img-filter-dark`. Override either in your tokens, for example `--mt-diagram-filter-dark: none` to keep every diagram as drawn; a `#light` ending on one image's path (`flow.svg#light`) does the same for that image. See [Math and diagrams](../../recipes/math-diagrams/#diagrams).

## Section visuals and full-width pages

Add `visual: <name>` to a `sections:` item to render your own `_includes/sections/<name>.html` at the end of that section. The include gets the item as `include.section`, so extra keys such as `scene:` reach it. `hero: {visual: <name>}` in front matter does the same for the part before the first `##` (it needs `sections:`). `modootoday-check` fails when the include is missing.

```yaml
---
full_width: true
hero: {visual: player-mock}
sections: [{c: features, name: why, visual: chart, scene: night}, faq]
---
```

The theme ships one hero visual, `showcase`: a soft background image, a token overlay and an animated UI scene drawn in SVG. It adds its own stylesheet only on that page, needs no JavaScript and settles within five seconds. With reduced motion it shows the final frame. In dark mode the same image is dimmed with a CSS filter; set `--mt-img-filter-dark` to change it. To use your own picture, set `hero.image` — a path, or `{path, srcset, width, height}`; it is the same `hero.image` key the home layout hero uses. The [home page](../../) uses it.

```yaml
hero: {visual: showcase}
# or: hero: {visual: showcase, image: {path: /assets/hero.webp, srcset: "/assets/hero-800.webp 800w, /assets/hero.webp 1600w", width: 1600, height: 900}}
```

`full_width: true` removes the reading-column width and side padding of `main.mt-main` (adds `.mt-main-full`) for landing pages.

## Sass partials

Jekyll reads `_sass/` from your site before the theme. Create `assets/css/modootoday.scss` to add your own rules after the theme:

```scss
---
---
@import "modootoday";

.mt-hero h1 { letter-spacing: -0.02em; }
```

> [!WARNING]
> Use `@import`, not `@use`. GitHub Pages compiles Sass with Ruby Sass, which passes `@use` through unchanged.

## Shadowing layouts and includes

Any file in the theme's `_layouts/`, `_includes/` or `_sass/` can be replaced by a file with the same path in your site. Add tags to the page head with `_includes/head-custom.html`:

```html
<link rel="icon" href="/favicon.svg">
```

> [!CAUTION]
> Shadowed files do not receive theme updates. Prefer tokens and `head-custom.html`.

Lists without a class get a small gap between items. If your layout or include turns an unclassed Markdown list into a grid or flex row (for example `.c-body > ul`), add `mt-flat-list` to an ancestor, such as `<div class="c-body mt-flat-list">`, so the first item lines up with the rest. A list that has a class of its own gets no gap.

## Next

[Agent-readable Markdown](../agents/) [Configuration](../configuration/)
# Write your first page

A page is a Markdown file with a small front matter block. The theme does the rest.

## Front matter

```yaml
---
title: Getting started
description: shown in search results and llms.txt
sections:
  - {c: features, name: highlights}
  - {c: cta, name: next}
---
```

Each `sections:` item maps to one top-level `##` heading, in order. Leave `sections:` out for a plain article.

## Body

```markdown
# Getting started

One sentence that explains the page.

## Highlights

- **Fast** — Builds in under a second.
- **Plain** — Readable on GitHub.

## Next

[Install](../install/)
```

> [!NOTE]
> The text before the first `##` becomes the hero. A paragraph that contains only links becomes buttons.

## The rules in one minute

| Allowed | Not allowed |
|---|---|
| GFM tables, lists, task lists | raw HTML and HTML comments |
| fenced code with one language word | Liquid tags in page bodies |
| top-level GitHub alerts | kramdown attributes and `{#id}` |
| `<https://…>` autolinks | bare URLs |

The full list lives in [RULES.md](https://github.com/modootoday/jekyll-theme-modootoday/blob/main/RULES.md).

## Next

[Explore components](../../components/) [Back to install](../install/)
# Install

Pick the build you already use. All three read the same Markdown.

## Choose a method

### GitHub Pages

```yaml
# _config.yml (classic GitHub Pages build, no Gemfile needed)
remote_theme: modootoday/jekyll-theme-modootoday@v1.4.1
plugins: [jekyll-remote-theme]
```

### Jekyll 4

```ruby
# Gemfile
source "https://rubygems.org"
gem "jekyll", "~> 4.4"
gem "jekyll-theme-modootoday", "~> 1.4"
```

### github-pages gem

```ruby
# Gemfile (reproduce GitHub Pages locally)
source "https://rubygems.org"
gem "github-pages", "~> 232", group: :jekyll_plugins
```

## Minimal configuration

Use pretty permalinks and the `doc` layout for every page:

```yaml
theme: jekyll-theme-modootoday
lang: en
permalink: pretty
markdown: kramdown
kramdown: {input: GFM}
defaults:
  - {scope: {path: ""}, values: {layout: doc}}
```

> [!TIP]
> With `remote_theme`, replace the `theme:` line with the two `remote_theme` lines from the GitHub Pages tab.

## Verify the build

```sh
bundle exec jekyll build
bundle exec modootoday-check . _site --twins
```

The checker reports any syntax that would not render the same on github.com.

A `remote_theme` site has no Gemfile entry for the theme, so `bundle exec modootoday-check` is not available. Install the gem once, at the same minor version as the theme tag, and run the checker on the built site:

```sh
gem install jekyll-theme-modootoday -v '~> 1.4'
modootoday-check . _site --twins
```

If the shell cannot find `modootoday-check`, the gem's bin directory is not on `PATH`: run `ruby -S modootoday-check . _site --twins`. If it stops with `can't find gem jekyll-theme-modootoday (Gem::GemNotFoundException)`, the script on `PATH` belongs to another gem location (another Ruby, or `GEM_HOME`/`GEM_PATH` set by a version manager). Point Ruby at the place `gem install` used:

```sh
GEM_PATH="$(gem env gemdir)" ruby -S modootoday-check . _site --twins
```

Without installing a gem, run the checker from the release source. It needs only Ruby:

```sh
curl -sL https://github.com/modootoday/jekyll-theme-modootoday/archive/refs/tags/v1.4.1.tar.gz | tar xz -C /tmp
ruby /tmp/jekyll-theme-modootoday-1.4.1/exe/modootoday-check . _site --twins
```

Use the tag your `remote_theme` line names.

In GitHub Actions, add the same two lines as a step after the build, for example `run: gem install jekyll-theme-modootoday -v '~> 1.4' && modootoday-check docs docs/_site --twins`.

Two warnings from the `github-pages` gem are harmless: `To use retry middleware with Faraday v2.0+, install faraday-retry gem` (the remote theme download still works), and Sass notices about `@import`. GitHub Pages uses an older Sass that does not read the Sass silencing option, so the notices appear even when your `_config.yml` sets it. The build output is correct either way.

## Next

[Write your first page](../first-page/) [Back to home](../../)
# Structured data

When `url:` is set in `_config.yml`, every page gets one `<script type="application/ld+json">` block holding a schema.org `@graph`. Search engines and AI tools read it to learn what the page is. Without `url:` nothing is printed, because schema.org URLs must be absolute.

## What the graph contains

| Node | `@id` | Contents |
|---|---|---|
| `WebSite` | `<url>/#website` | site name, URL, language, publisher; a `SearchAction` when `schema.search_url` is set |
| `Organization` or `Person` | `<url>/#publisher` | `schema.publisher` (name, URL, logo, `same_as`) |
| page type (`WebPage` and subtypes) | `<page>#webpage` | name, URL, description, `inLanguage`, image, breadcrumb |
| main entity | `<page>#main` | the article, job, event or other thing the page is about |
| `BreadcrumbList` | `<page>#breadcrumb` | the same trail as the visible breadcrumb |

Dates are ISO 8601 with the site time zone; text is escaped so the block is safe under a strict [CSP](../../recipes/csp/).

## Type per layout

| Layout | Type |
|---|---|
| `post` | `BlogPosting` (`NewsArticle` with `layout: news-article` or `kind: news`) |
| `doc` | `TechArticle` |
| `archive`, `blog`, `news` | `CollectionPage` |
| `author`, `profile`, `resume` | `ProfilePage` |
| `contact` | `ContactPage` |
| `search` | `SearchResultsPage` |
| `faq` | `FAQPage` |
| others | `WebPage` |

Authors come from `author`/`authors` in front matter, looked up in `_data/authors.yml`.

## Configuration

```yaml
modootoday:
  schema:
    publisher:
      type: Organization        # or Person
      name: Example Inc.
      url: https://example.com/
      logo: /assets/logo.png
      same_as: [https://github.com/example]
    search_url: /search/?q={search_term_string}   # optional SearchAction
    layouts:
      landing: SoftwareApplication               # override the type for a layout
```

Turn it off with `modootoday.schema: false` (or `schema: {enabled: false}`), or for one page with `schema: false` in front matter. `seo: false` also removes it.

With `seo: false` and `jekyll-seo-tag`, the plugin writes its own JSON-LD between the `<!-- Begin Jekyll SEO tag` and `<!-- End Jekyll SEO tag -->` comments. `modootoday-check` checks that block only for valid JSON and reports a warning, not errors: the kit does not write it, and its `WebPage` has `headline` but no `name`. schema.org marks no property as required, and Google lists no required properties for `WebPage`; the required-property list is the kit's own rule for the markup it writes. To have the page checked in full, move to the kit's tags ([Migrate](../upgrade/#from-jekyll-seo-tag)).

## Per-page entities

Set `schema.type` and any schema.org properties in front matter; `type:` keys become `@type`. The theme fills `name`, `description`, `url` and `image` from the page.

```yaml
schema:
  type: JobPosting
  datePosted: 2026-10-01
  hiringOrganization: {type: Organization, name: Example Inc.}
  jobLocation: {type: Place, address: {type: PostalAddress, addressCountry: KR}}
```

Other supported types include `SoftwareApplication` with `offers: {type: Offer, price: 0, priceCurrency: USD}`, `Event`, `Course`, `PodcastEpisode`, `DefinedTermSet`, `ItemList` and `FAQPage` (`mainEntity:` list of `Question`). Top-level URLs starting with `/` are made absolute; URLs inside nested values must already be absolute.

## Checking

`modootoday-check` validates every block in the built site offline: one block per page, valid JSON, known schema.org types and properties, required properties (Google's list), unique `@id`s, absolute URLs, ISO 8601 dates, and agreement with `og:url`, `og:title`, `og:image` and `<html lang>`. Add `--schema-recommended` to also list missing recommended properties.
# Translation rules

English is the source. Korean (`ko`) and Japanese (`ja`) pages, `README.ko.md`, the example site and the interface catalogs in `i18n/<code>.yml` are localized from it. This page is the single set of rules; `i18n/glossary.yml` is its machine-readable glossary, and `script/i18n-build --check` enforces both.

## Principles

- Say what the English page says, no more and no less. When they disagree, English wins and the translation is fixed.
- Localize, do not transliterate. Rewrite each sentence the way a native technical writer would: natural word order, the language's own sentence length, no stacked nouns copied from English.
- One concept, one word. Use the glossary term every time, on every page.
- Prefer the standard word over the jargon a few developers use. When a native word is clearer than a loanword, use it ("이동 경로", not "브레드크럼").
- Keep identifiers as they are: code, inline code, paths, Liquid, front matter keys and theme-read values, component and section names, badge values, CSS classes, `--mt-*` tokens, configuration keys, commands, URLs, product names and the `[!NOTE]`-style markers.

## Register

| Text | 한국어 | 日本語 |
|---|---|---|
| Docs, README, repository posts | 합니다체 (instructions may use ~하세요) | です・ます |
| Interface sentences (`i18n/*.yml`) | 해요체 | です・ます |
| Labels, buttons, headings | noun phrase | 体言止め |
| Table cells, list fragments | noun phrase or 합니다체 | 体言止め or 常体 |
| Sample pages (`noindex: true`) | the genre's own voice | the genre's own voice |

Korean docs use 합니다체 because it is the register of Korean reference documentation (Microsoft, MDN, Mozilla) and was already the majority on this site. Interface messages use the softer 해요체 common in Korean product UI. Never mix registers inside one page.

## Korean

- Standard spelling and spacing (국립국어원 표준국어대사전, 외래어 표기법): 내비게이션, 배지, 레이블, 사용자.
- No calques: "~를 가진", "~에 의해", "되어지다", "~하는 것이 가능합니다", "~에 대해서", "~것이 필요합니다". Write "~가 있는", the active voice, "~할 수 있습니다", "~해야 합니다".
- Drop English plurals; do not add 들 to technical nouns.
- Particles attach to code with no space and follow its pronunciation: `theme`을, `index.md`를.
- ASCII punctuation; quotes “ ”.

## Japanese

- JTF style guide spelling. Loanwords ending in -er, -or, -ar keep the long vowel: サーバー, ブラウザー, フォルダー, パラメーター, ヘッダー, フッター, ユーザー.
- No calques: "〜を持つ" for "has", "〜することが可能です", "〜によって行われる". Write "〜がある", "〜できます", the active voice.
- Full-width 、。（）「」 in prose. One half-width space between Japanese and Latin words or inline code; JTF omits it, this site keeps it for readability next to code.

## Numbers and dates

ASCII digits with the language's grouping (1,000). Prose dates: 2026년 10월 30일, 2026年10月30日; machine dates stay ISO 8601. Versions and units as in English (`1.0.0`, 360 px).

## Glossary highlights

The full list, with the wordings to avoid, is in `i18n/glossary.yml`.

Brand name: write the theme as **modoo.today theme** in English, **모두의오늘 테마** in Korean and **modoo.today テーマ** in Japanese; other languages keep `modoo.today` and translate the word *theme* (for example *thème modoo.today*). Always add the word for theme, so the name is not confused with the modoo.today service. The gem name `jekyll-theme-modootoday`, repository paths and code names such as `modootoday-check` stay as they are. Each language sets the header name in `site_title` of `_data/i18n/<lang>.yml`.

| English | 한국어 | 日本語 | Avoid |
|---|---|---|---|
| Markdown twin | Markdown 버전 | Markdown 版 | 쌍둥이, 트윈, ツイン, 双子 |
| front matter | front matter | front matter | 머리말, 프런트 매터, フロントマター |
| include | include | include | 인클루드, インクルード |
| breadcrumb | 이동 경로 | パンくずリスト | 브레드크럼, ブレッドクラム |
| checker | 검사기 | チェッカー | 체커 |
| navigation | 내비게이션 | ナビゲーション | 네비게이션 |
| repository | 저장소 | リポジトリ | 레포지토리 |
| screen reader | 스크린 리더 | スクリーンリーダー | 화면 낭독기 |
| component | 컴포넌트 | コンポーネント | 部品 |

## Interface strings

Catalogs keep every key of `i18n/en.yml` and every placeholder (`[n]`, `[total]`, `[section]`, `%{x}`); only values change. Labels are short noun phrases. After an edit run `script/i18n-build` to regenerate the Liquid catalogs.

## What the lint checks

`script/i18n-build --check` runs `script/i18n/lint.rb` and fails on:

- catalogs: missing or unknown keys, empty values, leading or trailing spaces, placeholder mismatches, 합니다체 in Korean interface sentences;
- ko and ja pages, READMEs, posts and example pages, outside code: glossary terms to avoid, calques, the wrong register (해요체 or 한다체 in Korean docs, 常体 sentences in Japanese prose) and untranslated English sentences.

Style the lint cannot judge (word order, idiom, tone) is checked in review against this page.

## Other languages

The other 20 catalogs follow the same principles. A term joins the glossary for a language once a native reviewer approves it.

The docs site lists all 23 languages in the language menu. For the 20 languages beyond English, Korean and Japanese, only the home page is localized. It links to the English guides and says so in a note at the end, and the sidebar shows the English menu. A page is translated whole or not at all.

## Sources

- [Microsoft localization style guides](https://learn.microsoft.com/globalization/reference/microsoft-style-guides) (Korean and Japanese)
- [MDN translated content guidelines](https://github.com/mdn/translated-content) and the Korean team notes
- [Mozilla Korean style guide](https://mozilla-l10n.github.io/styleguides/ko/)
- [JTF 日本語標準スタイルガイド](https://www.jtf.jp/tips/styleguide)
- [Toss technical writing guide](https://technical-writing.dev/)
- [국립국어원 한국어 어문 규범](https://kornorms.korean.go.kr/)
- [Google developer documentation style guide](https://developers.google.com/style)
- [W3C Internationalization](https://www.w3.org/International/)
# Migrate and upgrade

## From another theme

1. Replace `theme:` or `remote_theme:` with this theme (see [Install](../install/)) and pin a version.
2. Set `layout: doc` as a default in `_config.yml`, or keep your own layouts and include only the parts you need.
3. Keep page bodies as they are. GitHub alerts, tables and fenced code already work. Remove raw HTML and Liquid from bodies where you can; `modootoday-check` lists what is not portable.
4. Move colours and fonts into `modootoday.tokens` instead of overriding CSS selectors.
5. Run `jekyll build` and `modootoday-check SRC _site`, then fix what it reports.

Common mappings: minima `layout: page` and just-the-docs `layout: default` become `layout: doc`; callouts made with an `include note.html` tag become `> [!NOTE]`; badges written in HTML become `` `status:available` `` code spans.

## Adopting in an existing project

| Method | Use when | Updates |
|---|---|---|
| Gem (`theme:`) | the site has a `Gemfile` (Jekyll 4 or the `github-pages` gem) | `bundle update jekyll-theme-modootoday` |
| `remote_theme:` | classic GitHub Pages without a `Gemfile` | change the `@vX.Y.Z` tag |
| Copy-in | you need to fork layouts or cannot add a dependency | copy `_layouts`, `_includes`, `_sass` and `assets` from a tagged release and record the version; you merge updates by hand |

Prefer the gem or `remote_theme:` pinned to a tag. Copy-in loses upgrades and checker guarantees for the files you change.

## Markdown twins

Pick one of three ways to publish the agent-readable twin of each page:

- **Stub files** (default, classic GitHub Pages): one small `<page>.md.txt` per page.
- **Plugin** (Jekyll 4 or GitHub Actions): `plugins: [jekyll-theme-modootoday]` creates twins and `llms.txt` without stubs.
- **Source mode** (classic GitHub Pages, no stubs): `modootoday.twins: source` with pages that have no front matter. Classic GitHub Pages serves the raw copy as `text/markdown; charset=utf-8`, identical to the source (see RULES.md §5a for the limits).

Switching between them does not change page bodies. See [Agents](../agents/) and section 5a of `RULES.md`.

## From jekyll-seo-tag

To let the kit write the SEO tags instead of `jekyll-seo-tag`:

1. Remove `jekyll-seo-tag` from `plugins:` and the `Gemfile`, and the `seo` tag from `_includes/head-custom.html`.
2. Remove `seo: false` and `hreflang: true` from `modootoday:`. The kit writes the canonical link, the `hreflang` alternates and Open Graph again; delete any alternate links you added by hand, so no page lists them twice.
3. Set the browser bar colour with `modootoday.theme_color` (see [Configuration](../configuration/)). The kit writes two `theme-color` tags by default, one for light and one for dark; remove any `theme-color` tag of your own, or the page has three.
4. The kit writes only `twitter:card` (`summary_large_image` when the page has an image). It reads no `twitter:` setting; put a `twitter:site` meta tag in `_includes/head-custom.html` if you need one.
5. Rebuild and run `modootoday-check SRC _site`: the warning about jekyll-seo-tag JSON-LD should be gone.

## Upgrading

Read `CHANGELOG.md` for every version you skip. The [Public API](../../reference/api/) page lists the documented names. After upgrading, run `modootoday-check --strict`.

| From | To | What to do |
|---|---|---|
| a build from the repository before 1.0.0 | 1.0 | pin `~> 1.0` or `@v1.0.0`; run `modootoday-check --strict` |
| 1.0 or 1.1 | 1.2 | pin `~> 1.2` (or the newest `v1.2.x` tag with `remote_theme`); the new section and hero options (`bleed:`, `reveal:`, `c: split` with `visual:`) are opt-in, so pages need no edits; run `modootoday-check --strict` |
| 1.2 | 1.3 | pin `~> 1.3` (or `@v1.3.0` with `remote_theme`); the `reference` sidebar (`sidebar: true`) and package table (`packages:`) are opt-in, so pages need no edits; run `modootoday-check --strict` |
| 1.3 | 1.4 | pin `~> 1.4` (or `@v1.4.1` with `remote_theme`); `packages_compact` and `packages_position` are opt-in, and `reference` pages now convert alerts like `doc`, so pages need no edits; run `modootoday-check --strict` |

If your pages come from a pre-1.0 draft that allowed fewer `sections:` items than `##` headings, add a plain name (such as `notes`) for each remaining heading: the count must now match, and `modootoday-check` reports the page and both numbers.
# Layouts

Set a layout with `layout:` in front matter. Pages without one use `doc`.

| Layout | Use it for |
| --- | --- |
| `doc` | Documentation pages with a table of contents, breadcrumb and sidebar |
| `post` | Blog posts in `_posts/` |
| `archive` | Tag and category index pages |
| `default` | A bare page: header, body and footer only |

<!-- spec:docs-index:begin -->
- [Page shells](shells/) — Page shells for every kind of page, each with its own optional stylesheet.
- [Directory layouts](directory/) — Card lists for projects, people, jobs, events, sponsors and integrations, with a filter that needs no JavaScript.
- [Detail pages](detail/) — One page per project, case study, job, event or podcast episode, with a facts list, one call to action and structured data.
- [Marketing pages](marketing/) — Feature, pricing, download, brand, link and contact pages with a shared optional stylesheet.
- [Blog and news](blog-news/) — Blog indexes, news front pages, article bylines, author pages and Atom feeds.
- [Docs extras](docs-extra/) — Reference, changelog, roadmap, glossary, hub, course and book pages with one shared optional stylesheet.
- [Documents](documents/) — Legal pages and a print-first resume.
<!-- spec:docs-index:end -->
# Blog and news

Five layouts turn the theme into a blog or a newsroom. They are Liquid only, so they build on classic GitHub Pages and on Jekyll 4. They load `modootoday-blog.css` and `share.js` on their own pages only. Docs pages do not download either file.

| Layout | Use it for |
| --- | --- |
| `blog` | A list of posts, with pagination, in `list`, `grid` or `magazine` style |
| `post` | One post: byline, reading time, cover, series, previous and next, related posts |
| `news` | A front page: lead story, secondary stories, the latest list, one section per category |
| `news-article` | A post with a deck, breaking or live badge, corrections and sources |
| `author` | One author's bio and posts |
| `feed` | An Atom feed for one language |

## Demos

Each demo below is a real page built with one layout, outside the docs. Open it here or in a new window. Links inside the demos that would leave the sample point to `#`.

| Demo | Layout | New window |
| --- | --- | --- |
| [Blog index](blog/) | `blog` | [Open in new window](blog/ "new-window") |
| [Blog post](post/) | `post` | [Open in new window](post/ "new-window") |
| [News front page](news/) | `news` | [Open in new window](news/ "new-window") |
| [News article](article/) | `news-article` | [Open in new window](article/ "new-window") |
| [Yearly archive](archive/) | `archive` | [Open in new window](archive/ "new-window") |

The Atom feed for English posts is at [feed.xml](../../feed.xml); [Korean](../../ko/feed.xml) and [Japanese](../../ja/feed.xml) have their own.

## Blog index

```markdown
---
title: Blog
layout: blog
variant: grid      # list | grid | magazine
category: guides   # optional filter; tag: works too
---
```

See it rendered on the [sample blog](../../blog/), which lists the posts on this site.


With `jekyll-paginate` on and `paginate:` set, the root `index.html` blog page shows pager links. Otherwise the page shows `per_page` posts and a link to `archive_url`.

## Posts

```markdown
---
title: Shipping 1.0
author: kim            # or authors: [kim, lee], ids from _data/authors.yml
image: /assets/cover.png
image_alt: The release dashboard
series: launch         # posts with the same series get "Part 2 of 3" and links
last_modified_at: 2026-10-30
---
```

Author data lives in `_data/authors.yml`:

```yaml
kim: {name: Kim, url: "https://example.com", page: /authors/kim/, bio: Writes the docs.}
```

Each post emits `BlogPosting` JSON-LD and `article:*` Open Graph tags. Related posts are scored by shared tags and categories.

## News

```markdown
---
title: News
layout: news
news_sections: [releases, guides]
---
```

An article uses `layout: news-article` and adds `deck:`, `breaking: true` or `live: true`, `correction:`, `sources: [...]` and `credits:`. It emits `NewsArticle` JSON-LD. See the [sample front page](../../news/) and the [sample article](../../releases/2026/10/29/blog-news-layouts/).

## Authors and feeds

```markdown
---
layout: author
author: kim
---
```

Add a `feed.xml` page with `layout: feed` in each language folder (`/ko/feed.xml`) to get one Atom feed per language. The head links to it. Set `feed_content: full` for full text.

## Settings

```yaml
modootoday:
  blog:
    variant: list       # default list style
    per_page: 10
    excerpt: true
    reading_time: true
    related: 3          # 0 hides related posts
    share: true         # copy-link button
  news:
    sections: [releases]  # default news_sections
```

| Front matter | Layouts | Meaning |
| --- | --- | --- |
| `variant` | blog, author | `list`, `grid` or `magazine` |
| `category`, `tag` | blog, news, feed | Filter posts |
| `news_sections`, `secondary`, `latest` | news | Category sections and story counts |
| `posts_lang` | blog, news, author | `all` lists every language |
| `featured` | post | Pins the post as the lead card |
| `hidden`, `list: false` | post | Leaves the post out of lists |
| `author`, `authors` | post, author | Ids from `_data/authors.yml` |
| `series` | post | Groups posts into numbered parts |
| `deck`, `breaking`, `live`, `correction`, `sources`, `credits` | news-article | News details |
| `feed_lang`, `limit`, `feed_content` | feed | Feed scope |
# Detail pages

A detail page shows one item: a header, a list of facts read from front matter, the body and one call to action. These layouts load `modootoday-detail.css` only on their own pages and add no JavaScript. Each one prints a schema.org main entity built from the same front matter; a `schema:` map overrides any property. An optional `image: {path, alt, width, height}` shows a cover under the header.

| Layout | Facts | Call to action | Structured data | Demo |
|---|---|---|---|---|
| `project` | client, role, year, stack, links | `cta` | CreativeWork | [Project](/jekyll-theme-modootoday/layouts/detail/project/) |
| `case-study` | client, role, year, stack, links | `cta` | Article | [Case study](/jekyll-theme-modootoday/layouts/detail/case-study/) |
| `job` | location, employment, salary, posted, deadline | Apply (`apply`) | JobPosting | [Job](/jekyll-theme-modootoday/layouts/detail/job/) |
| `event` | starts, ends, venue, online | Tickets and an .ics file | Event | [Event](/jekyll-theme-modootoday/layouts/detail/event/) |
| `episode` | season and episode, posted, duration; audio player | `cta` | PodcastEpisode | [Episode](/jekyll-theme-modootoday/layouts/detail/episode/) |

## Job

```yaml
---
layout: job
title: Technical writer
description: Write and maintain the product documentation.
date: 2026-10-01          # datePosted
deadline: 2026-12-01      # validThrough
employment: full-time     # full-time, part-time, contractor, temporary, intern, volunteer, per-diem, other
location: Seoul           # or remote: South Korea (the country applicants must live in)
salary: {min: 50000, max: 70000, currency: USD, unit: year}
apply: mailto:jobs@example.com
---
```

The hiring organization is the site publisher (`modootoday.schema.publisher`). `modootoday-check` reports a job without `date`, without `location` or `remote`, or with an unknown `employment`.

## Event

```yaml
---
layout: event
title: Theme meetup
starts: 2026-11-20 19:00:00 +0900
ends: 2026-11-20 21:00:00 +0900
venue: Hall A             # a place, an online URL, or both
address: 1 Main St, Seoul
online: https://example.com/live
tickets: https://example.com/tickets
---
```

The calendar link is an .ics file in a `data:` URL, so it works without a server.

## Episode

```yaml
---
layout: episode
title: Pilot
date: 2026-10-10
season: 1
episode: 3
duration: 42              # minutes
audio: /media/ep3.mp3
transcript: /podcast/3/transcript/
---
```

The player is the browser's own `<audio controls>`; it loads nothing until it is played.

## Project and case study

```yaml
---
layout: project           # or case-study (an Article with author and dates)
title: Atlas
client: ACME
role: Design and build
year: 2026
stack: [Jekyll, Sass]
links:
  - {label: Repository, url: "https://example.com/atlas"}
cta: {label: Contact us, url: /contact/}
---
```

## Accessibility

The article is labelled by its heading, facts are a description list, and links that repeat (Apply, Tickets) name the page for screen readers. Print hides the call to action and the player.
# Directory layouts

A directory page is your text followed by a list of cards. The cards come from `items:` in front matter or from a file in `_data`. These layouts load `modootoday-directory.css` only on their own pages and add no JavaScript.

| Layout | Cards show | Filter by | Structured data | Demo |
|---|---|---|---|---|
| `portfolio` | image, title, text, tags | `tags` | ItemList | [Portfolio](/jekyll-theme-modootoday/layouts/directory/portfolio/) |
| `team` | round photo, name, role | `group` | ItemList of Person | [Team](/jekyll-theme-modootoday/layouts/directory/team/) |
| `jobs` | title, location, type | `department` | ItemList | [Jobs](/jekyll-theme-modootoday/layouts/directory/jobs/) |
| `events` | date tile, title, place, calendar file | none | ItemList of Event | [Events](/jekyll-theme-modootoday/layouts/directory/events/) |
| `sponsors` | logo, name, tier | `tier` | ItemList | [Sponsors](/jekyll-theme-modootoday/layouts/directory/sponsors/) |
| `integrations` | logo, name, category, text | `category` | ItemList | [Integrations](/jekyll-theme-modootoday/layouts/directory/integrations/) |

`layout: directory` is the plain version: set `preset:` to one of the names above, or leave it out for simple cards.

## Items

```yaml
---
layout: team
items:
  - {name: Ada Kim, role: Founder, group: Leadership, image: /assets/ada.jpg, alt: "", url: /about/ada/}
  - {name: Ben Ito, role: Designer, group: Design}
---
```

Each item needs `title` or `name`. All items take `url`, `text`, `image`, `alt`, `width` and `height`; give `alt: ""` when the photo only repeats the name. Preset fields:

- `team`: `role`, `group`
- `jobs`: `department`, `location`, `type`
- `events`: `date` (required, `YYYY-MM-DD HH:MM`), `end`, `location`, `online: true` for an online event (then `url` is where it happens)
- `sponsors`: `tier`
- `integrations`: `category`
- `portfolio`: `tags` (a list)

To share a list between pages, put it in `_data/team.yml` and write `data: team` instead of `items:`.

## Filter

When the filter field has two or more values, a row of buttons appears above the cards. It is a group of radio buttons, so it works with the keyboard and screen readers announce the choice. Up to 12 values are shown. Set `filter: false` to hide it, or `filter: <field>` to filter by another field. In browsers without `:has()` every card stays visible.

## Events

Each event links to an `.ics` file built into the page, so visitors can add it to their calendar without a server. Dates use the site's `timezone`.
# Docs extras

These layouts cover the pages around a manual. They load `modootoday-docs-extra.css` only on their own pages and add no JavaScript. Each reads a title and a `description:` (the lead); the page body comes after the generated part unless noted.

| Layout | Front matter | Structured data | Demo |
|---|---|---|---|
| `reference` | `members: [{name, signature, text, since, id}]` | TechArticle | [Reference](/jekyll-theme-modootoday/layouts/docs-extra/reference/) |
| `changelog` | `releases: [{version, date, url, added, changed, fixed, removed, security}]` | WebPage | [Changelog](/jekyll-theme-modootoday/layouts/docs-extra/changelog/) |
| `roadmap` | `items: [{title, status, text, url}]`, status `now`, `next` or `later` | WebPage | [Roadmap](/jekyll-theme-modootoday/layouts/docs-extra/roadmap/) |
| `glossary` | `terms: [{term, text, id}]` | DefinedTermSet | [Glossary](/jekyll-theme-modootoday/layouts/docs-extra/glossary/) |
| `hub` | `cards: [{title, text, url}]` | CollectionPage | [Hub](/jekyll-theme-modootoday/layouts/docs-extra/hub/) |
| `course` | `level`, `modules: [{title, lessons: [{title, url, minutes}]}]` | Course | [Course](/jekyll-theme-modootoday/layouts/docs-extra/course/) |
| `book` | `image`, `author`, `isbn`, `pages`, `chapters: [{title, url}]` | Book | [Book](/jekyll-theme-modootoday/layouts/docs-extra/book/) |
| `reference` with `sidebar: true` and `packages:` | `group` on members; `packages: [{name, version, text, url, links: [{label, url}]}]`, `packages_title`, `packages_compact`, `packages_position` | TechArticle | [API reference](/jekyll-theme-modootoday/layouts/docs-extra/api/) |

## Changelog

Each release lists its changes under the five category headings, in that order, with labels in the page language. Items are Markdown. `modootoday-check` reports any other key, so a typo such as `fix:` does not vanish silently.

## Glossary

Terms are sorted for you and grouped by first letter, with a letter bar that links only to letters in use. Every term gets an anchor (`id:` or a slug of the term), and the page data lists each one as a DefinedTerm.

## Course

Lesson `minutes` add up to the total shown under the title and to `timeRequired`. The course provider is the site publisher; a `description:` is required.

## API sidebar and package table

Both are opt-in on the `reference` layout; a page without them renders as before. `sidebar: true` moves the member list into a side column that stays in view on wide screens (64rem and up). Members that share a `group:` are listed under that label, in the order the groups first appear; on narrow screens the same list sits above the page. `packages:` adds a table with one row per package (name, version and links, with the `text` under the name), before the body; on small screens each row stacks into a short card. A reference page with `packages:` may leave out `members:`. Both use CSS only.

When the body already describes each package, `packages_compact: true` leaves out the `text` under each name, and `packages_position: after` moves the table below the body (the default is `before`). A Markdown page sets the table in front matter only: `modootoday-check` rejects Liquid in page bodies, because GitHub shows it as plain text. In your own layouts or HTML pages, include `modootoday/docs-extra/packages.html` (with `items=page.packages`, and optionally `caption=` and `compact=true`) wherever the table should go. The body of a reference page turns GitHub alerts (`> [!TIP]` and the rest) into callouts, as the `doc` layout does. The page's Markdown twin and `llms-full.txt` carry the package table as a Markdown table, in the same place.

## Checks

`modootoday-check` requires the list each layout is built on, a valid `status`, a `text` for each term, no duplicate terms, a `url` for each hub card, whole-number `minutes` and `pages`, and a 10- or 13-digit `isbn`.
**Packages**

| Name | Version | Links |
| --- | --- | --- |
| [`modootoday-core`](#): Parsing, rendering and the page model. | `1.4.0` | [Docs](#), [Source](#) |
| [`modootoday-cli`](#): The `modootoday` command. | `1.4.0` | [Docs](#), [Source](#) |
| [`modootoday-lint`](#): Checks pages against the layout contracts. | `0.9.2` | [Docs](#), [Source](#) |

The sidebar groups members by `group:`; the table lists the packages that make up the library.

> [!TIP]
> Pin the packages to one minor version so the table and the members stay in step.
# Documents

Two layouts for pages people print or keep. Both hide the site header, footer and banners on paper.

| Layout | Front matter | Bundle | Structured data | Demo |
|---|---|---|---|---|
| `legal` | `effective` (required), `updated`, `version`, `toc: false` | pages | WebPage with dates | [Terms](/jekyll-theme-modootoday/layouts/documents/legal/) |
| `resume` | `name`, `headline`, `email`, `phone`, `location`, `links`, `experience`, `education`, `skills` | resume | ProfilePage + Person | [Resume](/jekyll-theme-modootoday/layouts/documents/resume/) |

## Legal

```yaml
---
layout: legal
effective: 2026-01-01
updated: 2026-10-30
---
```

The contents list is built from the `##` and `###` headings in the body; `toc: false` hides it. The dates become `datePublished` and `dateModified`.

## Resume

```yaml
experience:
  - {role: Lead engineer, org: Example Docs, start: 2024-03-01}
education:
  - {degree: BSc, school: Example University, end: 2019-02-01}
skills:
  - {group: Languages, items: [Ruby, JavaScript]}
```

An entry with no `end` shows "Present" and becomes the Person's `worksFor`. Schools become `alumniOf` and skills `knowsAbout`. The markup also carries h-card classes. The page is laid out for A4 and Letter paper first and reflows on screens.
# Marketing pages

These layouts build the pages around a product: what it does, what it costs, where to get it, how to show it and how to reach you. They load `modootoday-marketing.css` only on their own pages and add no JavaScript. Every layout reads a title, a `description:` (the lead) and optional `actions: [{label, url}]` buttons.

| Layout | Front matter | Structured data | Demo |
|---|---|---|---|
| `feature` | `features: [{title, text}]`, `cta` | WebPage | [Feature](/jekyll-theme-modootoday/layouts/marketing/feature/) |
| `pricing` | `plans`, `currency` | WebPage | [Pricing](/jekyll-theme-modootoday/layouts/marketing/pricing/) |
| `download` | `version`, `date`, `downloads: [{label, url, size, checksum}]` | WebPage | [Download](/jekyll-theme-modootoday/layouts/marketing/download/) |
| `brand` | `colors: [{name, hex}]`, `assets: [{label, url, format}]` | WebPage | [Brand](/jekyll-theme-modootoday/layouts/marketing/brand/) |
| `links` | `image`, `name`, `links: [{label, url}]` | ProfilePage | [Links](/jekyll-theme-modootoday/layouts/marketing/links/) |
| `contact` | `contacts: [{label, value, url}]`, `form: {action, fields}` | ContactPage | [Contact](/jekyll-theme-modootoday/layouts/marketing/contact/) |

For product data, add a `schema:` map (for example `type: SoftwareApplication` with `offers`) and the page prints it as the main entity.

## Pricing

```yaml
---
layout: pricing
currency: $
plans:
  - {name: Free, monthly: 0, yearly: 0, features: [One site]}
  - {name: Team, monthly: 12, yearly: 120, recommended: true, features: [Ten sites, Support], cta: {label: Choose Team, url: /buy/}}
---
```

Plan cards use the pricing component styles. When plans have `yearly`, a Monthly/Yearly switch made of two radio buttons changes the prices with CSS alone. Set `yearly` on every plan or none; only one plan can be `recommended`, and it is labelled in text.

## Links

A link page has no site header. `links:` become large buttons; their full URLs become `sameAs` of the Person (or `profile: organization`) in the ProfilePage data.

## Contact

```yaml
---
layout: contact
contacts:
  - {label: Email, value: hello@example.com, url: "mailto:hello@example.com"}
form:
  action: https://forms.example.com/your-form   # an external form service; https only
  fields: [name, email, message]
---
```

GitHub Pages cannot receive form posts, so the form appears only when `form.action` is set. Every field has a visible label and `autocomplete`.

## Brand

Swatches are SVG fills, so the page needs no inline style under a strict Content Security Policy, and each color also shows its hex code as text. `modootoday-check` reports a color that is not `#rgb` or `#rrggbb`.
# Page shells

Set `layout:` in a page's front matter. The page shells below load an extra stylesheet, `modootoday-pages.css`, only on the pages that use them, so other pages stay as light as before. None of them adds JavaScript.

| Layout | Use it for | Demo |
|---|---|---|
| `minimal` | Standalone notices, sign-in notes, link pages. No header, page meta or pagination. | [Minimal](/jekyll-theme-modootoday/layouts/demo/minimal/) |
| `wide` | Card grids, wide tables and galleries. Full header and footer, no reading-width cap. | [Wide](/jekyll-theme-modootoday/layouts/demo/wide/) |
| `home` | A landing page: hero from front matter, then the body. Adds WebSite structured data. | [Home](/jekyll-theme-modootoday/layouts/demo/home/) |
| `error` | 404, 410 and 500 pages with localized title and text. | [Error](/jekyll-theme-modootoday/layouts/demo/error/) |
| `redirect` | A moved page. Sends visitors on without script, so it works under a strict CSP. | [Redirect](/jekyll-theme-modootoday/layouts/demo/redirect/) |
| `search` | A full search page with a form that also works without JavaScript. | [Search](/jekyll-theme-modootoday/layouts/demo/search/) |

Card lists for projects, people, jobs, events, sponsors and integrations are on [Directory layouts](/jekyll-theme-modootoday/layouts/directory/).

## Home

```yaml
---
layout: home
hero:
  title: Build a site from Markdown
  text: One sentence about the site.
  actions:
    - {label: Get started, url: /install/}
    - {label: GitHub, url: "https://github.com/modootoday/jekyll-theme-modootoday"}
---
```

The first action is the primary button. Without `hero.title` the layout shows only the body. `home` renders the body as written and does not read `sections:`, so cards, tabs and buttons sections do not apply. For a rich home page with those, use `layout: doc` with `hero:` and `sections:`, as this site's home page does. An optional `hero.image` (a path, or `{path, alt, width, height, srcset}`) shows a wide picture under the actions; leave `alt` empty when it is decorative. The `showcase` hero visual reads the same `hero.image` key (see [Customize](../../guides/customize/)).

## Error

```yaml
---
layout: error
status: 404
permalink: /404.html
sitemap: false
---
```

`status` is `404` (default), `410` or `500`. The title and text come from the theme's catalogs in 23 languages; set `heading:` to replace the title, and write a body to add your own links.

## Redirect

```yaml
---
layout: redirect
permalink: /old-page/
redirect_to: /new-page/
---
```

`redirect_to` takes a site path or a full URL. The page is marked `noindex` and points search engines to the new address.

## Search

The header search box gives instant results. Below the page body, the `search` layout adds a form that searches this site through an external engine when JavaScript is off. Change it in `_config.yml`:

```yaml
modootoday:
  search:
    fallback: {url: "https://duckduckgo.com/", param: q}   # or false to hide the form
```
# News

A sample front page (`layout: news`): lead story, secondary stories, the latest list and one section per category.
# Recipes

Each recipe solves one task on top of the guides.

<!-- spec:docs-index:begin -->
- [Math and diagrams](math-diagrams/) — Render Mermaid diagrams and KaTeX math with the built-in loaders, at build time, or with your own loader, and what each does to your CSP and privacy.
- [CSP](csp/) — Run the theme under a strict CSP without unsafe-inline.
- [Product site](marketing/) — Put a feature page, pricing, downloads and a brand kit together.
- [Company pages](company/) — About, team, jobs, contact and legal pages for a small organization.
- [Documentation site](docs/) — A docs home, a reference, a changelog and a glossary around your guides.
- [Personal site](personal/) — A link page, a printable resume and a portfolio under one name.
- [Community site](community/) — Events, a public roadmap and sponsors for an open project.
- [System pages](system/) — Not-found, error, moved and search pages that every site needs.
<!-- spec:docs-index:end -->
# Community site

List meetups with `events` and one `event` page each, share plans on a `roadmap` with `now`, `next` and `later`, and thank backers on `sponsors`. Link the roadmap items to issues so readers can follow the work.

Layouts: `events`, `event`, `roadmap`, `sponsors`.
# Company pages

Use `team` for people, `jobs` with one `job` page per opening, `contact` for ways to reach you, and `legal` for terms and privacy with an `effective` date. Set the site `publisher` once; every page then names the same Organization in its structured data.

Layouts: `team`, `jobs`, `contact`, `legal`.
# Content Security Policy

The theme loads its CSS and scripts from files under `assets/`. Two things are inline by default:

| Inline item | When | Strict option |
|---|---|---|
| Pre-paint theme script (avoids a flash of the wrong colour scheme) | `theme-toggle` is on and `color_scheme: auto` | `modootoday.csp: strict` loads `assets/js/modootoday/theme-init.js` as a blocking script instead |
| `<style id="mt-tokens">` | `modootoday.tokens` or `tokens_dark` is set | move the overrides into your own Sass (`--mt-primary: …` on `:root`) and remove the keys |

With both handled, this policy works:

```text
Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:
```

GitHub Pages cannot send response headers. A `<meta http-equiv="Content-Security-Policy">` tag in `_includes/head-custom.html` works for these directives. If you keep the inline script, allow it by hash instead; the hash changes only when the script changes, which `CHANGELOG.md` announces.

To add math or diagrams under this policy, see [Math and diagrams](../math-diagrams/).
# Documentation site

Make the docs home a `hub` with one card per section. Generate `reference` members from your CLI or API, append each release to the `changelog`, and keep shared words in one `glossary` so guides can link to `/glossary/#term`. These pages load `modootoday-docs-extra.css`; guide pages stay on the core sheet.

Layouts: `hub`, `reference`, `changelog`, `glossary`.
# Product site

Make `/` a `feature` page whose `actions:` link to `/pricing/` and `/download/`. Keep one `pricing` page with every plan, set `version` and `date` on `download` from your release, and link a `brand` page from the footer. All four share `modootoday-marketing.css`, so a visitor loads it once.

Layouts: `feature`, `pricing`, `download`, `brand`.
# Math and diagrams

A ```` ```math ```` or ```` ```mermaid ```` fence renders as a code block until you turn a renderer on, and GitHub renders it on github.com. There are three ways to render them on your site:

| Option | Works on | CSP | JavaScript in the browser |
|---|---|---|---|
| [Built-in loaders](#built-in-loaders): `modootoday.mermaid` and `modootoday.math` | classic GitHub Pages, Jekyll 3.10 and 4, any host | self-hosted: `'self'`; CDN: add the CDN origin (below) | yes, only on pages with a block |
| [Render at build time](#render-at-build-time) and commit the output | classic GitHub Pages, Jekyll 4, any host | strict, nothing to add | none |
| [Your own loader](#your-own-loader) in `_includes/footer-custom.html` | classic GitHub Pages, Jekyll 4, any host | strict for KaTeX; Mermaid needs `style-src 'unsafe-inline'` | yes |

## Built-in loaders

Both are off by default. Turn one on in `_config.yml` with a URL to a renderer **at an exact version** and its [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) hash, or with a path to a copy on your own site:

```yaml
modootoday:
  mermaid:
    enabled: true
    src: https://cdn.jsdelivr.net/npm/mermaid@11.4.1/dist/mermaid.min.js
    integrity: sha384-…   # the hash of that exact file
    theme: auto           # auto (follows the page's light or dark mode), default, dark, neutral, forest
  math:
    enabled: true
    engine: katex
    src: https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js
    css: https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css
    integrity: {js: sha384-…, css: sha384-…}
    auto_render_src: https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js
    auto_render_integrity: sha384-…
    inline: false
```

- **Only where needed.** The tags load only on pages that contain a block: `language-mermaid` for Mermaid, a ```` ```math ```` fence or a `$$` block for math. Set `mermaid: false` or `math: false` in a page's front matter to skip one page.
- **No hash, no load.** A CDN URL without `integrity` (or a non-https URL) loads nothing, and `modootoday-check` reports an error. The checker also requires an exact version in the URL (`@11.4.1`, not `@11` or `@latest`) and reports any other third-party script or stylesheet in the built pages.
- **Self-hosted.** A path such as `/assets/vendor/mermaid.min.js` loads from your own site (`relative_url` is applied; `integrity` is optional). For KaTeX, copy `katex.min.js`, `katex.min.css`, the `fonts/` folder and `contrib/auto-render.min.js` from the `katex` package.
- **Readable without JavaScript.** The source stays on the page as a code block until the renderer replaces it, and stays if a diagram or formula fails to parse.
- **Light and dark.** With `theme: auto`, diagrams use Mermaid's `dark` theme when the page is dark (the theme toggle or the visitor's system setting) and redraw when it changes. With reduced motion requested, diagram animations are off. A diagram wider than the column scrolls inside its own keyboard-focusable region.
- Each loader is a small separate script (`assets/js/modootoday-mermaid.js`, `assets/js/modootoday-math.js`) with its own size budget, not part of the core script.

### Math notation

Use a ```` ```math ```` fence or a `$$` block on its own lines; both are the standard notation and render on github.com too. A `$$` block needs `auto_render_src`; without it only fences render. Inline `$…$` renders only with `inline: true`, because a `$` in ordinary prose (prices, shell variables) would otherwise turn into math. With `inline: false`, `modootoday-check` warns about inline `$…$` in your pages. kramdown prints `$$…$$` written inside a sentence as inline math, which renders whenever `auto_render_src` is set.

### CSP and privacy

A CDN changes your Content Security Policy and your visitors' privacy:

- **CSP.** Add the CDN origin to `script-src` (both), to `style-src` (KaTeX's stylesheet) and to `font-src` (KaTeX's fonts). Mermaid also writes `<style>` into each diagram, so it needs `style-src 'unsafe-inline'` wherever you host it. A self-hosted copy keeps `'self'` for scripts, styles and fonts. See [Content Security Policy](../csp/).
- **Privacy.** Each visitor's browser requests the files from the CDN, so the CDN receives the visitor's IP address, the page address (as referrer) and the time. Self-hosting avoids this; mention the CDN in your privacy notice if you use one.
- **Availability.** With a CDN, the blocks render only while that CDN is reachable; the source code block remains otherwise.

## Render at build time

This is the recommended option. The page ships static SVG, so it works without JavaScript, prints well and passes a strict CSP.

### Diagrams

Render each Mermaid source to SVG with the Mermaid CLI, commit the SVG, and reference it as a figure. Keep the source next to it so the diagram can be regenerated.

```sh
npx -y @mermaid-js/mermaid-cli -i assets/diagrams/flow.mmd -o assets/diagrams/flow.svg -b transparent
```

```markdown
![Markdown becomes a page, then the checker verifies the build](../../assets/diagrams/flow.svg)

*The build flow.*
```

An image-only paragraph followed by an emphasis-only paragraph becomes a figure with a caption. Write the alt text as the diagram's meaning, not "diagram". An `.svg` figure works in both colour schemes from one file: in dark mode the theme inverts it with the hues kept, then applies `--mt-img-filter-dark` (the token `--mt-diagram-filter-dark`). Set `--mt-diagram-filter-dark: var(--mt-img-filter-dark)` for a dimmer tone only, or `none` to turn it off for the site; end one image's path in `#light` (`flow.svg#light`) to keep it as drawn. Raster images keep the usual photo tone. On a narrow screen a wide diagram keeps a readable width (`--mt-figure-min-width`, default `32rem`) and scrolls sideways inside its own region, which is focusable and named by the alt text.

### Math

Render formulas to HTML with KaTeX once, in a script you run before committing, or in a Jekyll 4 build on GitHub Actions. Then serve KaTeX's CSS and fonts from your own site. In the examples, replace `/your-base` with your site's `baseurl` (or use Jekyll's `relative_url` filter):

```sh
npm install katex
mkdir -p assets/katex && cp -r node_modules/katex/dist/katex.min.css node_modules/katex/dist/fonts assets/katex/
```

```html
<!-- _includes/head-custom.html -->
<link rel="stylesheet" href="/your-base/assets/katex/katex.min.css">
```

KaTeX's static output is plain HTML and CSS classes, so `style-src 'self'` is enough.

## Your own loader

Use this when you need control the built-in loaders do not give. Copy the renderer's files into your site, then load them from `_includes/footer-custom.html`. Wrap the tags in a Liquid `if page.math` (or `if page.mermaid`) block so they load only on pages that set that key in front matter.

### KaTeX in the browser

```html
<link rel="stylesheet" href="/your-base/assets/katex/katex.min.css">
<script defer src="/your-base/assets/katex/katex.min.js"></script>
<script defer src="/your-base/assets/js/math.js"></script>
```

```js
// assets/js/math.js: render ```math fences (kramdown: pre > code.language-math)
document.querySelectorAll("code.language-math").forEach((code) => {
  const box = document.createElement("div");
  katex.render(code.textContent, box, { displayMode: true, throwOnError: false });
  code.closest("div.highlighter-rouge, pre").replaceWith(box);
});
```

Add `math: true` to the page's front matter. The script is a file, so `script-src 'self'` is enough.

### Mermaid in the browser

Mermaid writes `<style>` elements into each SVG, so a strict `style-src 'self'` blocks its styling. Either render at build time (above), or allow inline styles for that page only and keep scripts strict:

```html
<script defer src="/your-base/assets/mermaid/mermaid.min.js"></script>
<script defer src="/your-base/assets/js/diagrams.js"></script>
```

```js
// assets/js/diagrams.js
document.querySelectorAll("code.language-mermaid").forEach((code) => {
  const box = document.createElement("pre");
  box.className = "mermaid";
  box.textContent = code.textContent;
  code.closest("div.highlighter-rouge, pre").replaceWith(box);
});
const dark = document.documentElement.dataset.theme === "dark" || (!document.documentElement.dataset.theme && matchMedia("(prefers-color-scheme: dark)").matches);
mermaid.initialize({ startOnLoad: false, theme: dark ? "dark" : "default", securityLevel: "strict" });
mermaid.run();
```

Keep `securityLevel: "strict"`: it disables click handlers and HTML labels inside diagrams.

## Checklist

- The source stays in the Markdown, so github.com and agents reading the [Markdown twin](../../guides/agents/) still see it.
- No third-party origins in your CSP, or the CDN origin listed and pinned with `integrity`.
- Every diagram has alt text or a caption that states what it shows.
- Load renderers only on pages that need them.
# Personal site

Put a `links` page at `/`, a `resume` at `/cv/` and `portfolio` with `project` pages for your work. Use the same `name` on the link page and the resume so both ProfilePages describe one Person; print the resume from the browser to get a clean PDF.

Layouts: `links`, `resume`, `portfolio`.
# System pages

Add `404.md` with `layout: error`, use `redirect` for pages that moved, and give search its own page with `layout: search`. These pages use the small pages bundle; set `sitemap: false` on error pages so they stay out of the sitemap.

Layouts: `error`, `redirect`, `search`.
# Reference

Look things up here.

<!-- spec:docs-index:begin -->
- [Public API](api/) — The names, classes and files this theme documents for your site.
- [Tags](../tags/) — Every post on this site, grouped by tag.
- [Categories](../categories/) — Every post on this site, grouped by category.
- [Changelog](changelog/) — Releases of jekyll-theme-modootoday.
- [Roadmap](roadmap/) — What the theme supports, which stacks it runs on, and where it is heading.
<!-- spec:docs-index:end -->
# Public API

The public API is documented here; changes are listed in `CHANGELOG.md`. Anything not listed (internal includes, Sass partial paths, private `--mt-p-*` primitives, HTML details that no rule describes) can change in any release.

## Stable names

| Area | Stable names |
|---|---|
| Settings | every key under `modootoday:` listed in [Configuration](../../guides/configuration/) |
| Design tokens | semantic and component custom properties `--mt-*` (not the primitives `--mt-p-*`); the generated `tokens.json` mirrors them |
| Markdown rules | the patterns in `RULES.md` and their output classes `mt-*`; the opt-out class `mt-flat-list` (no gap between list items below it) |
| Layouts | `default`, `doc`, `post`, `archive`, `twin`, `llms`, `llms-full` |
| Includes you may override | `head-custom.html`, `footer-custom.html`; `modootoday/lang-switch.html` and `modootoday/brand/logo.html` (takes `size`) can be included from your footer; override `modootoday/brand/logo.html` to draw your own logo |
| Includes you provide | `_includes/sections/<name>.html`, rendered at the end of a section or the hero by `visual: <name>` (see [Customize](../../guides/customize/#section-visuals-and-full-width-pages)) |
| Includes you may call | `modootoday/archive.html` with `by` and `lang`; `modootoday/brand/icon.html` with `name` (globe, sun, moon, search, menu, copy, check, external, prev, next, chevron-right, chevron-down, note, tip, important, warning, caution, edit, rss, tag, folder, brand), optional `size` (px, default 18), `label` (makes it `role="img"` with that name; otherwise `aria-hidden`) and `class`. Output: `svg.mt-icon.mt-icon-<name>` in `currentColor`; directional icons add `.mt-icon-flip` (mirrored in RTL) |
| Includes | `modootoday/t.html` (`key=`, optional `n=` / `name=`) prints a theme label for the page language |
| Data files | `_data/i18n/<lang>.yml` keys (optional overrides of the built-in catalogs), `_data/nav/<name>.yml`, `_data/components.yml` |
| Checker | the `modootoday-check` options, exit code 0 (no problems) and 1 (problems or bad usage) |

## Markdown rules

`md-components v1` is the name of the Markdown rules standard in `RULES.md`; it is not a CSS prefix. Output classes use `mt-*`.

## Component structure

This is the markup you can target from your own CSS today. Classes and attributes in this table are part of the public API; elements inside them that the table does not name (wrappers, generated ids, the order of child elements) are not. The [slot contract](#slot-contract) names the Markdown parts each component consumes.

| Component | Root | Parts you may style | State and variants |
|---|---|---|---|
| Page shell | `body.mt-body` | `a.mt-skip`, `header.mt-header` > `.mt-header-inner` (`.mt-site-title`, `nav.mt-nav`, `.mt-search`, `details.mt-lang.mt-menu` (`summary` globe button, `ul` of `a[lang][hreflang]`, current one `aria-current`), `.mt-theme-toggle`), `main.mt-main`, `footer.mt-footer` > `.mt-footer-inner` | `html[data-theme=light\|dark]` (fixed scheme, or set by the toggle) |
| Doc page | `article.mt-doc` | `.mt-doc-layout` > `.mt-doc-main` and `.mt-doc-aside` (holds `nav.mt-toc`), `nav.mt-toc-mobile`, `nav.mt-breadcrumb`, `.mt-page-meta`, `nav.mt-pagination` | — |
| Doc sidebar | `aside.mt-doc-nav` > `nav.mt-sidebar` (from 64rem); `details.mt-sidebar-mobile` (below) | `.mt-sidebar-group`, `.mt-sidebar-title`, the `ul` of links; the current link has `aria-current=page` | `.mt-doc-layout.mt-has-sidebar`; `[open]` on the mobile menu |
| Page actions | `details.mt-menu.mt-page-actions` | `summary`, the `ul` of `button[data-mt-act=copy\|ai]` (hidden until JS runs) and the View as Markdown `a[type="text/markdown"]` | `[open]` |
| Hero | `section.mt-hero` | the `h1`, lead `p.mt-hero-lead` (the first `p` right after the `h1`), link-only `p` (CTA buttons; first link is primary) | `.mt-hero-checks` (front matter `hero: {checks: true}`: the first `ul` is a row of ✓ marks in `--mt-ok`) |
| Section | `section.mt-section` | the `h2` and its content | `[data-section]` = name; `[data-c]` and `.mt-c-<c>` = component; `.mt-cols-<n>`; `.mt-cta` (on the section, or on a `[data-mt-result]` element inside it when one is present) |
| Section decor | `.mt-has-decor` on `section.mt-hero` or `section.mt-section` (front matter `decor: <include>`) | `.mt-section-decor[aria-hidden=true]`, the last child, holding `_includes/sections/<include>.html`; placed in the top end corner, no pointer events | — |
| Scroll reveal | `.mt-reveal` on `section.mt-hero` or `section.mt-section` (front matter `reveal: true`) | — | CSS only: fades in on scroll inside `@supports (animation-timeline: view())` and `prefers-reduced-motion: no-preference`; shown as is otherwise |
| Full-width band | `.mt-bleed` on `section.mt-hero` or `section.mt-section` (front matter `bleed: true`), `.mt-bleed-wide` (`bleed: wide`) | — | `--mt-bleed-bg` sets the band colour; inside a sidebar or table-of-contents layout the band stays in the main column; `bleed` sheet |
| Illustration | `figure.mt-illustration[role=img][aria-label]` (your own include) | `.mt-illustration-tag` badge in the top start corner; its text belongs in the `aria-label` too, because the children of `role=img` are not read | — |
| List styles | `ul.mt-chips`; `li > strong.mt-item-title + span.mt-item-sep` (with `modootoday.lists`) | the `li > a` chips (44px tall, → after the text); the title and the `: ` separator | — |
| Prose (no `sections:`) | `div.mt-prose` | the rendered body | — |
| Card grid | `section.mt-section` | `ul > li`, its leading `strong` is the title | `.mt-cols-2`, `.mt-cols-3`, `.mt-cols-4`, `.mt-badge-bottom` (`c: features`) |
| Tabs | `section.mt-c-tabs[data-tabs]` | `[role=tablist]`, `[role=tab]`, `[role=tabpanel]` (built by JS; without JS the `h3` + code blocks stay) | `[aria-selected]` |
| Accordion | `section.mt-c-accordion` | `h3 > button[aria-expanded]`, the panel after it | `[aria-expanded=true\|false]` |
| Steps / Timeline | `section.mt-c-steps`, `section.mt-c-timeline` | `ol > li` or `h3` items | — |
| File tree | `section.mt-c-filetree` | `ul[aria-label]`, nested `ul` (items holding one are folders) | — |
| Details / FAQ | `section.mt-c-details`, `section.mt-c-faq` | `details.mt-details`, `summary > h3`, the content after it | `[open]` |
| Parameter table | `section.mt-c-params` | `th[scope=col]`, `.mt-param-required` | — |
| Link cards | `section.mt-c-linkcards` | `ul > li > a` (the whole card is the link target) | — |
| Quote | `figure.mt-quote` | `blockquote`, `figcaption` | — |
| Gallery | `section.mt-c-gallery` | `a.mt-gallery-thumb`, `a.mt-lightbox`, `.mt-lightbox-close` | `:target` on the open lightbox |
| Pricing | `.mt-plans` | `.mt-plan`, its `h3`, link-only `p.mt-actions` | `.mt-plan-recommended` with `.mt-plan-flag` |
| Subscribe | `section.mt-c-subscribe` | `form.mt-subscribe` (when an action is set), `label`, `input[type=email]`, `button` | — |
| Split | `section.mt-c-split` (with `.mt-split-start`, `.mt-split-5-7`) | `.mt-section-in` > `.mt-section-body` (the `h2` and text) + `.mt-section-visual` (the `visual:` include). `hero: {c: split}` puts `section.mt-hero` in the same wrappers, with the `h1`, lead, check row and actions in `.mt-section-body`. `visual: code` puts the first code block in `div.mt-section-visual.mt-split-code`; `chrome: terminal` adds `.mt-split-terminal` and `div.mt-split-bar` (`aria-hidden`). | — |
| Inline extras | `div.mt-code`, `span.mt-progress`, `div.mt-embed` | `.mt-code-title`, `progress`, `iframe` | — |
| Loading (optional sheet) | `.mt-spinner`, `.mt-topbar`, `.mt-skeleton` | `.mt-skeleton-text`, `-card`, `-image`, `-avatar`, `-row`; `.mt-ratio-16x9`, `-4x3`, `-1x1` | `[aria-busy=true]`, `[role=status]` |
| Banner | `div.mt-banner` | its `p` and link; `a.mt-back-to-top` | — |
| Alert | `blockquote.mt-callout[role=note]` | `p.mt-callout-title`, the body | `.mt-callout-<type>`, `[data-variant]` = note, tip, important, warning, caution |
| Badge | `span.mt-badge` | the symbol (`aria-hidden`), the label | `.mt-badge-<status>`, `.mt-badge-tag`, `[data-variant]` |
| Keyboard keys | `kbd.mt-kbd` | `kbd` per key | — |
| Figure | `figure.mt-figure` | `img`, `figcaption` | — |
| Post header | `header.mt-post-header` | `h1.mt-post-title`, `.mt-post-deck`, `.mt-byline` (`.mt-byline-authors` > `.mt-post-author`, `.mt-byline-dates` > `time`), `figure.mt-post-cover`, `nav.mt-series`, `p.mt-post-meta` (tag badges) | `[data-part]` = header, deck, byline, authors, dates, cover, terms |
| Post footer | `article.mt-doc` | `.mt-share` button, `nav.mt-post-nav`, `section.mt-related`, `.mt-news-correction`, `.mt-news-sources` | `[data-part]` = share, post-nav, related, sources |
| Post card | `article.mt-card-post` | `.mt-card-post-cover`, `.mt-card-post-meta`, `.mt-card-post-title`, `.mt-card-post-excerpt` | `.mt-card-post-featured`, `[data-kind=news]`, `.mt-post-list[data-variant=list\|grid\|magazine]` |
| News front | `div.mt-news-top` | `.mt-news-lead`, `.mt-news-secondary`, `section.mt-news-latest`, `section.mt-news-section` | `[data-category]`, `.mt-badge[data-variant=breaking\|live]` |
| Search | `div.mt-search[role=search]` | the input, `.mt-search-results` | — |

## Slot contract

A slot is a named part of a section's Markdown. Slot names are stable under the policy above, and declaring them never changes the generated markup. `modootoday-check` counts each slot in every section whose `c:` has a `slots:` entry in `_data/components.yml`, and fails when a count is outside the declared range.

| Slot | What it counts in the section (after its `##` heading) | Renders as |
|---|---|---|
| `lead` | Plain paragraphs before the first list, `###`, code block or quote | `p` |
| `items` | List items | `ul > li` or `ol > li` (cards, steps) |
| `panels` | `###` headings | tab, accordion or step panels |
| `actions` | Link-only lines | CTA buttons (`c: cta`) |
| `code` | Fenced code blocks | `pre` (tab content) |
| `figures` | Lines that start with an image | `figure.mt-figure` |

Each slot takes `required: true` (same as `min: 1`), `min` and `max` (whole numbers, `min` not greater than `max`). For a component that has two valid shapes, `slots:` can be a list of alternative forms; a section passes when it satisfies any one of them. `parts:` lists the selectors from the [component structure](#component-structure) table that the component promises to keep; when the site has an `api.md` with that table, every part must appear in it. When Nokogiri is available (it is under `github-pages`), every part must also match inside a section of that component in the built HTML of the pages that use it; parts that component scripts add at runtime (`role=`, `aria-*`) are checked after the scripts run by the docs site QA.

```yaml
features: {params: {cols: {allowed: [2, 3, 4]}, badge: {allowed: [bottom]}}, slots: {items: {min: 1}}, parts: [ul > li, .mt-cols-2, .mt-cols-3, .mt-cols-4, .mt-badge-bottom]}
tabs: {i18n: [tabs.label], slots: {panels: {min: 2}, code: {min: 2}}}
cta: {slots: {actions: {required: true}}, parts: [.mt-cta]}
accordion: {slots: {panels: {min: 1}}}
steps: {slots: [{items: {min: 1}}, {panels: {min: 1}}], parts: [section.mt-c-steps, ol > li]}
```

A component entry takes only `params`, `i18n`, `slots` and `parts`, and a slot rule only `required`, `min` and `max`. Any other key, an unknown slot name, a `min` above `max` or a list of fewer than two forms is an error, reported once per registry. Components without `slots:` are not counted, and a single-map `slots:` behaves exactly as before.

## Right-to-left and math

- Pages in Arabic, Persian, Hebrew, Urdu and other RTL languages get `dir="rtl"` from `lang`; set `direction: rtl` or `ltr` in front matter (or `direction:` in `_data/i18n/<lang>.yml`) to override. Components use logical properties and mirror; code stays left-to-right.
- The theme bundles no math or diagram renderer; see [Math and diagrams](../../recipes/math-diagrams/).

## Posts and archives

Posts use the `post` layout: a date, author and tag line, the body, then a footer that links each category and tag to its archive section. Set the archive pages in `_config.yml`:

```yaml
modootoday:
  archive: {tags: /tags/, categories: /categories/}
```

Then add one page per taxonomy, for example `tags.md`:

```yaml
---
title: Tags
layout: archive
archive: tags        # or categories
---
```

The page shows its own body, an index of terms with post counts, and one section per term (`id="tags-<slug>"`, newest post first). To place an archive anywhere else, call the include `modootoday/archive.html` from a layout or include, with `by` set to `tags` or `categories` and an optional `lang`. Archive styles live in `modootoday-blog.css`: the `archive` and `post` layouts load it, and any other page that calls the include needs `blog_css: true` in its front matter.

- A post's language is its `lang` (or `site.lang`). An archive lists only posts in the page's language; `archive_lang: all` (or `lang="all"` on the include) lists every post. Footer links of a post whose `lang` differs from `site.lang` point at `/<lang>/tags/`, so add an archive page under each language directory.
- Labels come from `archive.tags`, `archive.categories`, `archive.posts` and `archive.empty` in `_data/i18n/<lang>.yml`, with English fallbacks.
- Limits: classic GitHub Pages runs no custom plugin, so there is one page per taxonomy with an anchor per term, not one page per term. Posts get no Markdown twin; agents find them through the archive links. Jekyll puts the folder names above `_posts/` into `categories`, so keep posts in the top-level `_posts/` and set `lang:` in front matter.
# Changelog

The full history is in [CHANGELOG.md](https://github.com/modootoday/jekyll-theme-modootoday/blob/main/CHANGELOG.md).

## 1.0.0 (first release)

The first public version on RubyGems.

- Components: alerts, sections, cards, buttons, tabs, badges, tables, accordion, steps, figures, timeline, keyboard keys, breadcrumb, table of contents, theme toggle, client search and the `post` layout.
- Design tokens (`--mt-*`), one Sass partial per component and the `modootoday:` configuration block.
- Final content rules (`md-components v1`), a stable [public API](../api/) and the `modootoday-check` checker.
- SEO tags by default, a language switcher, right-to-left support, strict CSP support and a slot contract.
- Markdown twins and `llms.txt` for AI agents.
- Documentation in English, Korean and Japanese.

Sites built from the repository before 1.0.0 should read [Migrate and upgrade](../../guides/upgrade/).

> [!IMPORTANT]
> The rules are final as `md-components v1`. Changes are listed in `CHANGELOG.md`.

[Back to home](../../)
# Roadmap

## Supported in 1.0

- Components in light and dark: alerts, sections, cards, buttons, tabs, badges, tables, accordion, steps, figures, timeline, keyboard keys, breadcrumb, table of contents, theme toggle and search. See [Components](../../components/).
- Final content rules (`md-components v1`) and a stable [public API](../api/).
- Canonical, `hreflang` and Open Graph tags by default; sitemap and feed when you add the plugins.
- A language switcher for multilingual sites, and right-to-left scripts (see the [RTL kitchen sink](../../components/kitchen-sink-rtl/)).
- A slot contract for your own `_data/components.yml` ([API](../api/#slot-contract)).
- Markdown twins and `llms.txt` for AI agents ([Agents](../../guides/agents/)).
- Tag and category archive pages for the `post` layout.
- Strict Content Security Policy support ([CSP](../../recipes/csp/)) and a [math and diagrams guide](../../recipes/math-diagrams/).
- Documentation in English, Korean and Japanese.

## Compatibility

- GitHub Pages (`github-pages` 232, Jekyll 3.10) with `remote_theme`, and Jekyll 4.4 on Ruby 3.3 to 3.4. Jekyll 3.9 is the oldest supported version.
- The public API is documented on [Public API](../api/); changes are listed in the CHANGELOG. See [Migrate and upgrade](../../guides/upgrade/).

## Next

- New components and options are added without breaking existing sites where possible.
# Tags

Every post, grouped by tag. Each post's footer links its tags to the matching section here. See [Posts and archives](../reference/api/#posts-and-archives).