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

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 names the Markdown parts each component consumes.

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.

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 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.

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.

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:

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

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

---
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.