jekyll-theme-resume 1.3.0

data/docs/reference/repository-map.md

@@ -0,0 +1,83 @@
+# Repository Map
+
+*Audience: theme developers*
+
+Annotated tree of the theme's code directories. The `docs/` directory is not listed; see the [documentation index](../README.md).
+
+```text
+jekyll-theme-resume/
+├── 403.html / 404.html / 500.html  # Root HTTP error pages (layout: error)
+│
+├── _layouts/
+│   ├── default.html              # Base HTML shell
+│   ├── profile.html              # Standalone landing page
+│   ├── resume.html               # Resume layout for every language (LTR and RTL)
+│   └── error.html                # HTTP error suite (404/403/500/503)
+│
+├── _includes/
+│   ├── resume-section.html       # Section dispatcher (14 sections, every language)
+│   ├── grouped-item-list.html    # Shared Experience/Volunteering renderer
+│   ├── date-formatter.html       # Locale-driven date and "Present" formatting
+│   ├── data-loader.html          # Dot-path data resolution into resume_data
+│   ├── shared-head.html          # Meta, anti-FOUC script, favicons
+│   ├── avatar.html               # Profile picture
+│   ├── safe-url.html             # URL scheme allowlist (sets safe_url)
+│   ├── dark-mode-toggle.html     # Floating theme toggle
+│   ├── language-switcher.html    # Floating dropdown linking to every other configured language
+│   ├── social-links.html         # Social icons (email + 14 platforms)
+│   ├── print-social-links.html   # Print-only social links text list
+│   ├── hreflang.html             # Alternate-language SEO links
+│   ├── analytics-head.html       # GTM / GA4 head script
+│   ├── analytics-body.html       # GTM noscript body fallback
+│   └── vendors/svg-icons/        # Bundled Lineicons SVGs (MIT; see ATTRIBUTION.md inside)
+│
+├── _sass/
+│   ├── _variables.scss           # Widths, gutters, font stacks
+│   ├── _dark-mode.scss           # Color tokens, overrides, print reset
+│   ├── _base.scss                # Reset, .sr-only, base typography
+│   ├── _layout.scss              # Floating language-switcher styles
+│   ├── _resume-ltr.scss          # Main resume styles + LTR positioning
+│   ├── _resume-rtl.scss          # Language-neutral RTL overrides
+│   ├── _profile-page.scss        # Landing page styles
+│   ├── _all-pages.scss           # Shared markdown typography, icon links, footer, error-page styles
+│   ├── _mixins.scss              # Breakpoints and font mixins
+│   └── _normalize.scss           # Normalize.css v8.0.1
+│
+├── assets/
+│   ├── css/
+│   │   ├── cv-ltr.scss           # Resume entrypoint for LTR locales
+│   │   ├── cv-rtl.scss           # Resume entrypoint for RTL locales
+│   │   ├── profile.scss          # Profile page entrypoint
+│   │   └── main.scss             # Default/error pages entrypoint
+│   └── favicon/resume/           # Favicon suite
+│
+├── _data/
+│   ├── locales/                  # en, ar, es, fr, de, ur locale dictionaries
+│   └── social_networks.yml       # Shared platform list for social-links.html / print-social-links.html
+│
+├── _plugins/
+│   ├── error_pages_generator.rb  # Synthesizes missing HTTP error pages
+│   ├── json_resume_generator.rb  # Publishes /<lang>/resume.json (and /resume.json for default_lang) via JsonResumeExporter
+│   ├── resume_pages_generator.rb # Synthesizes missing CV/profile pages per language
+│   └── resume_validator.rb       # Build-time validation (on by default)
+│
+├── lib/
+│   ├── jekyll-theme-resume.rb          # Gem entrypoint
+│   └── jekyll-theme-resume/
+│       ├── json_resume_exporter.rb # Maps resume data to a JSON Resume v1.0.0 document
+│       ├── resume_validator.rb   # Validator engine
+│       ├── template_key_checker.rb # Template checker (repository-only)
+│       └── schemas/
+│           ├── json_resume_v1.0.0.json # Bundled JSON Resume schema used to validate exports
+│           └── LICENSE.md        # License for the bundled schema
+│
+├── bin/
+│   ├── validate-resume           # Validator CLI (gem executable)
+│   ├── check-data-keys           # Template checker (repository-only)
+│   └── release                   # Release script (not packaged)
+│
+├── test/                         # Minitest suites; see reference/testing-suites.md
+└── Rakefile                      # validate, check_data_keys, test, rubocop, proof, default
+```
+
+Test suites are described in [testing suites](testing-suites.md). Layouts, includes, and Sass are detailed in [layouts](layouts.md), [includes](includes.md), and [Sass tokens](sass-tokens.md).

data/docs/reference/sass-tokens.md

@@ -0,0 +1,279 @@
+# Sass reference (`_sass/`)
+
+*Audience: theme developers*
+
+Reference for the theme's styling system in [`_sass/`](../../_sass) and the entrypoint stylesheets in [`assets/css/`](../../assets/css): Dart Sass module architecture, partial inventory, and the dark mode tokens.
+
+---
+
+## Entrypoints & Compilation Architecture
+
+### Stylesheet Entrypoints
+
+Jekyll compiles files in [`assets/css/`](../../assets/css) that start with YAML front matter into final static CSS assets:
+
+| Source SCSS | Compiled Output CSS | Consuming Layouts |
+|---|---|---|
+| [`assets/css/cv-ltr.scss`](../../assets/css/cv-ltr.scss) | `assets/css/cv-ltr.css` | [`_layouts/resume.html`](../../_layouts/resume.html) for every locale with `direction: ltr` |
+| [`assets/css/cv-rtl.scss`](../../assets/css/cv-rtl.scss) | `assets/css/cv-rtl.css` | [`_layouts/resume.html`](../../_layouts/resume.html) for every locale with `direction: rtl` |
+| [`assets/css/profile.scss`](../../assets/css/profile.scss) | `assets/css/profile.css` | [`_layouts/profile.html`](../../_layouts/profile.html) |
+| [`assets/css/main.scss`](../../assets/css/main.scss) | `assets/css/main.css` | [`_layouts/default.html`](../../_layouts/default.html), [`_layouts/error.html`](../../_layouts/error.html) |
+
+### Modern Dart Sass `@use` Architecture
+
+The theme uses `@use` exclusively. The reasons are in [Why `@use` instead of `@import`](../explanation/architecture.md#why-use-instead-of-import).
+
+### Overriding Partials in a Consuming Site
+
+Steps: [Override Sass partials](../how-to/override-sass-partials.md).
+
+---
+
+## SCSS Partial Inventory
+
+### 1. `_variables.scss`
+
+- **File:** [`_sass/_variables.scss`](../../_sass/_variables.scss)
+- **Role:** Font stacks and default sizes. Only `$white` and `$text_color` are read (by `_base.scss`, as fallbacks for `--bg-color` and `--text-color`); the other variables are currently unused.
+- **Variables:**
+  - `$white`, `$text_color`: color fallbacks. They are not declared with `!default`, so they cannot be configured with `@use ... with`.
+  - `$container-width: 980px !default;`, `$grid-gutter: 10px !default;`, `$body-font`, `$mono-font`, `$body-font-size: 13px !default;`: declared but not used by any partial or entrypoint.
+
+---
+
+### 2. `_mixins.scss`
+
+- **File:** [`_sass/_mixins.scss`](../../_sass/_mixins.scss)
+- **Role:** Breakpoint helpers, typography mixins, and border accents.
+- **Key Mixins:**
+  - `@mixin media_mobile` (`max-width: 600px`)
+  - `@mixin media_larger_than_mobile` (`min-width: 600px`)
+  - `@mixin sans`, `@mixin serif`, `@mixin section_border`
+
+---
+
+### 3. `_normalize.scss`
+
+- **File:** [`_sass/_normalize.scss`](../../_sass/_normalize.scss)
+- **Role:** Normalize.css v8.0.1 browser baseline reset.
+
+---
+
+### 4. `_base.scss`
+
+- **File:** [`_sass/_base.scss`](../../_sass/_base.scss)
+- **Role:** HTML and body defaults, box-sizing, and screen-reader accessibility classes.
+- **Key Features:**
+  - Universal `box-sizing: border-box`.
+  - `.sr-only` utility class for WCAG screen-reader announcements.
+  - Selection background and text styling.
+
+---
+
+### 5. `_layout.scss`
+
+- **File:** [`_sass/_layout.scss`](../../_sass/_layout.scss)
+- **Role:** Floating language switcher component (`.language-switcher`, fixed top-left, hidden in print). The former grid classes (`.container`, `.columns`, `.one-third`, and so on) were removed.
+
+---
+
+### 6. `_resume-ltr.scss`
+
+- **File:** [`_sass/_resume-ltr.scss`](../../_sass/_resume-ltr.scss)
+- **Role:** The main resume stylesheet: every shared rule plus LTR positioning. Both entrypoints load it; `cv-rtl.scss` then layers `_resume-rtl.scss` on top.
+- **Typography:** resume text reads `var(--font-locale, <default stack>)` and `var(--line-height-locale, <default>)`, so each locale's font and line height apply without per-language rules.
+- **Components Styled:**
+  - Header: Avatar (`.avatar`), candidate name, contact info row, and social links bar.
+  - Contact CTA button (`.contact-button`) and "not looking" modifier.
+  - Section headers (`.section-header`) and item cards (`.resume-item`).
+  - Two-column responsive Languages table.
+  - Print-specific media overrides (`@media print`).
+
+---
+
+### 7. `_resume-rtl.scss`
+
+- **File:** [`_sass/_resume-rtl.scss`](../../_sass/_resume-rtl.scss)
+- **Role:** Language-neutral RTL overrides scoped under `html[dir="rtl"]`, loaded last by `cv-rtl.scss`. Serves Arabic, Urdu, and any future RTL locale.
+- **Key Overrides:**
+  - Flips horizontal floats, text alignments, borders, and margins.
+  - Repositions timeline bullets and contact icons for RTL reading order.
+  - Resets `letter-spacing` to `normal` on headings.
+  - Sets no `font-family` or `line-height`; those come from the locale CSS variables.
+
+---
+
+<a id="8-_profile-pagescss"></a>
+<a id="8-_profile-page-scss"></a>
+### 8. `_profile-page.scss`
+
+- **File:** [`_sass/_profile-page.scss`](../../_sass/_profile-page.scss)
+- **Role:** Styles for the dedicated portfolio landing page layout ([`_layouts/profile.html`](../../_layouts/profile.html)) and entrypoint [`assets/css/profile.scss`](../../assets/css/profile.scss).
+- **Architecture:** Provides clean, unconstrained vertical centering, avatar, bio typography, and CV action button without duplicating universal footer or SVG icon styles (which are loaded from [`_all-pages.scss`](../../_sass/_all-pages.scss)).
+
+---
+
+### 9. `_all-pages.scss`
+
+- **File:** [`_sass/_all-pages.scss`](../../_sass/_all-pages.scss)
+- **Role:** Universal styles shared across all layouts.
+- **Key Features:**
+  - Shared icon-link sizing, hover animations, and `.page-footer` spacing. Shared rules live here and `.sr-only` lives in `_base.scss`.
+  - Complete dark-mode-aware typography rules for markdown content in `.main-content` (headings, paragraphs, blockquotes, tables, lists, and code blocks).
+
+---
+
+### 10. `_dark-mode.scss`
+
+- **File:** [`_sass/_dark-mode.scss`](../../_sass/_dark-mode.scss)
+- **Role:** Single source of truth for all color tokens, theme overrides, and the floating toggle button.
+
+---
+
+## The Dark Mode Token System
+
+### Design Tokens Table
+
+Shared color styles use CSS custom properties defined on `:root` in [`_sass/_dark-mode.scss`](../../_sass/_dark-mode.scss):
+
+| CSS Custom Property | Light Mode Value | Dark Mode Value | Semantic Role |
+|---|---|---|---|
+| **Background & Typography** | | | |
+| `--bg-color` | `#ffffff` | `#121212` | Main page and viewport background |
+| `--text-color` | `#333` | `#e0e0e0` | Primary reading and heading typography |
+| `--text-muted` | `#999` | `#888888` | Secondary copy, timestamps, and details |
+| `--text-light` | `#646464` | `#aaaaaa` | Tertiary descriptive text |
+| `--border-color` | `#c7c7c7` | `#333333` | Section dividers and card borders |
+| `--card-bg` | `#efefef` | `#1e1e1e` | Button backgrounds and code blocks |
+| **Links & Navigation** | | | |
+| `--link-color` | `#333` | `#e0e0e0` | Interactive hyperlinks |
+| `--link-hover` | `#9c9c9c` | `#ffffff` | Hyperlink hover color |
+| `--link-hover-color` | `var(--link-hover)` | `var(--link-hover)` | Hyperlink hover alias |
+| **Accent & Brand** | | | |
+| `--accent-color` | `#3064a9` | `#6ba4e8` | Primary accents and focus outlines |
+| `--accent-contrast-text` | `#ffffff` | `#121212` | Text and focus outline against the accent background |
+| `--accent-hover` | `#307EA9` | `#8cbcf3` | Accent hover state |
+| `--accent-hover-color` | `var(--accent-hover)` | `var(--accent-hover)` | Accent hover alias |
+| `--social-hover-color` | `var(--accent-hover)` | `var(--accent-hover)` | Social icons hover color |
+| `--about-color` | `var(--text-light)` | `var(--text-light)` | Executive summary / about text color |
+| **Footer** | | | |
+| `--footer-text-color` | `var(--text-muted)` | `var(--text-muted)` | Footer copyright typography |
+| `--footer-link-color` | `var(--link-color)` | `var(--link-color)` | Footer hyperlink color |
+| **Icons & Graphics** | | | |
+| `--icon-fill` | `#333` | `#e0e0e0` | Social and contact SVG icon fill |
+| `--icon-fill-muted` | `#555555` | `#888888` | Muted secondary icon fill |
+| `--icon-fill-dark` | `#000` | `#ffffff` | Dark/prominent icon fill |
+| `--icon-hover-fill` | `var(--icon-fill-dark)` | `var(--icon-fill-dark)` | Icon hover fill |
+| `--header-icon-fill` | `var(--icon-fill-dark)` | `var(--icon-fill-dark)` | Header contact icon fill |
+| **Buttons (.contact-button, .cv-button)** | | | |
+| `--button-bg` | `#efefef` | `#2a2a2a` | Action button background |
+| `--button-text` | `#333` | `#e0e0e0` | Action button label color |
+| `--button-hover-bg` | `#333` | `#444444` | Action button hover background |
+| `--button-hover-text` | `#fff` | `#ffffff` | Action button hover label color |
+| **Text Selection** | | | |
+| `--selection-bg` | `rgba(51, 51, 51, .8)` | `rgba(107, 164, 232, .5)` | Highlighted text background |
+| `--selection-color` | `#fff` | `#ffffff` | Highlighted text color |
+| **Dark Mode Toggle Component** | | | |
+| `--toggle-btn-bg` | `transparent` | `transparent` | Toggle button background |
+| `--toggle-btn-border` | `var(--border-color)` | `var(--border-color)` | Toggle button border |
+| `--toggle-btn-color` | `var(--text-color)` | `var(--text-color)` | Toggle button icon color |
+| `--toggle-btn-hover-bg` | `var(--button-bg)` | `var(--button-bg)` | Toggle button hover background |
+| `--toggle-btn-focus-ring`| `var(--accent-color)`| `var(--accent-color)`| Toggle button focus ring outline |
+
+### Two-Tier Activation Mechanism
+
+Why activation has two tiers: [Dark mode approach](../explanation/dark-mode-approach.md#two-tiers-of-activation).
+
+1. **Automatic Detection:**
+   ```scss
+   @media (prefers-color-scheme: dark) {
+     :root:not([data-color-scheme="light"]):not([data-theme="light"]) {
+       --bg-color: #121212;
+       --text-color: #e0e0e0;
+       // ...
+     }
+   }
+   ```
+2. **Explicit User Pin:**
+   ```scss
+   :root[data-color-scheme="dark"],
+   :root[data-theme="dark"] {
+     --bg-color: #121212;
+     --text-color: #e0e0e0;
+     // ...
+   }
+   ```
+
+### Print Media Resets
+
+When printing to physical paper or PDF, [`_sass/_dark-mode.scss`](../../_sass/_dark-mode.scss) enforces a strict print reset:
+
+```scss
+@media print {
+  :root,
+  :root[data-color-scheme="dark"],
+  :root[data-color-scheme="light"],
+  :root[data-theme="dark"],
+  :root[data-theme="light"],
+  [data-color-scheme="dark"],
+  [data-theme="dark"],
+  html.dark,
+  html.light {
+    color-scheme: light !important;
+    --bg-color: #ffffff !important;
+    --text-color: #000000 !important;
+    --border-color: #c7c7c7 !important;
+    --card-bg: #fff !important;
+    /* ...every other color token (text, link, accent, icon, button, selection) is reset the same way */
+  }
+  html,
+  body {
+    background-color: #fff !important;
+    color: #000 !important;
+    -webkit-print-color-adjust: exact;
+    print-color-adjust: exact;
+  }
+  .dark-mode-toggle,
+  #dark-mode-toggle {
+    display: none !important;
+  }
+}
+```
+
+The block resets every color token to black, white, or grey values, whichever scheme the page is pinned to, forces `html` and `body` to `#fff` and `#000`, and hides the toggle.
+
+---
+
+## WCAG 2.2 Accessibility & High-Contrast Standards
+
+- **Contrast:** see [Accessibility decisions](../explanation/accessibility-decisions.md) for the pair-based contrast rule; [accessibility-coverage.md](accessibility-coverage.md) lists current limitations and verification steps.
+- **Focus Rings:** Interactive elements feature high-contrast visible focus outlines:
+  ```scss
+  :focus-visible {
+    outline: 2px solid var(--accent-color, #3064a9);
+    outline-offset: 2px;
+  }
+  ```
+- **Screen-Reader Utility:**
+  ```scss
+  .sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border-width: 0;
+    text-decoration: none !important;
+  }
+  ```
+
+---
+
+## Locale Typography & RTL Mechanics
+
+- **Per-locale typography:** `_layouts/resume.html` emits `--font-locale` (from the locale's `font_family`, when non-empty) and `--line-height-locale` (from `line_height`) in an inline `:root` style, and `_sass/_resume-ltr.scss` reads both with the theme defaults as fallbacks. Shipped font and line-height values: [locale-keys.md](locale-keys.md#shipped-locales). To change a language's font, see [Override locale strings](../how-to/override-locale-strings.md#change-a-languages-font).
+- **Direction selects the entrypoint:** the layout links `cv-<direction>.css` (see the entrypoints table).
+- **RTL scope:** overrides activate via `html[dir="rtl"]`; rationale in [Multilingual and RTL design](../explanation/multilingual-and-rtl-design.md#typography--rtl).

data/docs/reference/testing-suites.md

@@ -0,0 +1,62 @@
+# Testing suites
+
+*Audience: theme developers*
+
+How the theme is tested, what each suite proves. Validator rules themselves are in [validator-cli.md](validator-cli.md); agent verification rules are in [AGENTS.md](../../AGENTS.md#rule-5-build--packaging-verification).
+
+## Test tasks
+
+To run the suites or add a test, see [Add a test](../how-to/add-a-test.md).
+
+The `test` task runs every `test/test_*.rb` file, so a new suite needs no Rakefile edit. Two error-page tests run the page's real JavaScript in Node and are skipped when `node` is not installed.
+
+`bundle exec rake` (the default task) runs `validate`, `check_data_keys`, `rubocop`, and `test`. The default task runs `validate` with its default data directory (`_data` if `_data/en` exists, else `demo/_data`); pass another one with `rake "validate[path/to/_data]"`. There is no config-path argument; see [validator-cli.md](validator-cli.md#4-rake-task-rake-validate). HTML proofing runs separately after a build.
+
+## What each suite covers
+
+Every test goes through a public interface; see [Tests use public interfaces only](../explanation/architecture.md#tests-use-public-interfaces-only).
+
+| Suite | Interface under test | Covers |
+|---|---|---|
+| [`test_rendered_site.rb`](../../test/test_rendered_site.rb) | Generated HTML of a fixture site built from the theme's real `_layouts`, `_includes`, `_sass`, `_data`, `assets` | Each of the sections (fields, separators, inactive entries, grouping, RTL `dir="ltr"` isolation); date formats; header, contact bar, avatar, microdata; social and print links; hreflang; profile, default and error layouts (including the URL-language script and `baseurl`); config switches such as `enable_live`, `lang_header`, `baseurl`, analytics, dark mode |
+| [`test_language_switcher.rb`](../../test/test_language_switcher.rb) | Generated HTML, six languages | Switcher links, labels, direction, page/site opt-out, error layout |
+| [`test_resume_validator.rb`](../../test/test_resume_validator.rb) | `ResumeValidator#validate`, `bin/validate-resume`, build plugin | Every schema rule per section, dates, "Present" values, URLs, alias keys, locale merge and parity, config resolution, strict mode, CLI flags |
+| [`test_template_key_checker.rb`](../../test/test_template_key_checker.rb) | `TemplateKeyChecker#check`, `bin/check-data-keys` | Liquid binding resolution, include boundaries, advisory exit codes |
+| [`test_error_pages_generator.rb`](../../test/test_error_pages_generator.rb) | Site build | Generated 404/403/500 pages, site overrides, generator registration |
+| [`test_resume_pages_generator.rb`](../../test/test_resume_pages_generator.rb) | Site build | Generated CV/profile pages, collisions, per-language and global toggles |
+| [`test_json_resume_exporter.rb`](../../test/test_json_resume_exporter.rb) | `JsonResumeExporter.export`, site build | JSON Resume mapping, privacy, visibility, schema validation, routes; see [json-resume-fields.md](json-resume-fields.md) |
+| [`test_packaging.rb`](../../test/test_packaging.rb) | Gemspec, shipped `_data` | Gem file list, six-locale key parity, unused locale keys, social icons and labels, demo data parity |
+| [`test_doc_links.rb`](../../test/test_doc_links.rb) | The tracked Markdown files | Every relative link and `#anchor` in the docs resolves; links in code blocks and external URLs are skipped |
+
+## The rendered-site fixture
+
+`RenderedSiteTest` writes fixture data for `en` (LTR) and `ar` (RTL) into a temporary site. Each section has an entry for every rendering rule, an entry with optional fields missing, and an `active: false` entry whose text starts with `hidden-`. Entries are tagged `EN`/`AR` so a test can tell which language's data rendered.
+
+Config variants reuse the same fixture. Pass overrides and the site is built once per distinct override set:
+
+```ruby
+cv("en", "enable_live" => true)          # _site/en/cv/ built with enable_live on
+html("404.html", "baseurl" => "/cv")     # any output path
+section("Experience")                    # the <section> whose heading matches, default config
+```
+
+## Continuous integration
+
+This repository runs the validator and the template key checker in two workflows:
+
+- [`.github/workflows/lint.yml`](../../.github/workflows/lint.yml): `./bin/validate-resume demo/_data --fail-on-warnings`, `rake validate[demo/_data]`, `./bin/check-data-keys demo/_data`, `rake check_data_keys[demo/_data]`, a gemspec executable check, and RuboCop.
+- [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml): gem packaging, a strict Jekyll build, built-HTML proofing, RuboCop, the resume validator and template key checker, and the unit tests across Ruby 3.3, 3.4, and 4.0.
+
+## Built-HTML proofing semantics
+
+- External URLs are not fetched, so results are offline and deterministic.
+- Absolute URLs built from `site.url` (hreflang, canonical) are mapped onto local files so they are checked too.
+- When `_site/index.html` does not exist, `/` and every configured `languages.<lang>.url` are exempted as link targets. A site with a homepage gets no exemption. Use the demo build to check the complete generated site.
+
+## JSON Resume export coverage
+
+Run the normal demo build and `bundle exec rake`. Export coverage includes visibility, live contacts, privacy, locale characters, schema validation, collisions, literal Liquid content, and discovery-link cleanup on rebuild. Generated JSON can be downloaded directly or imported into JSON Resume tooling; compatibility with every third-party renderer is not guaranteed by schema validity.
+
+## Liquid pitfalls the tests guard
+
+See [Liquid pitfalls](../explanation/architecture.md#liquid-pitfalls).

data/docs/reference/validator-cli.md

@@ -0,0 +1,203 @@
+# Validator and build checks
+
+*Audience: site owners and theme developers*
+
+The repository has two verification engines; only the resume-data validator ships in the gem. `lib/jekyll-theme-resume/resume_validator.rb` checks resume YAML data — reached three ways: the `validate-resume` CLI, the `rake validate` task, and a Jekyll generator that runs during every consuming site's build. `lib/jekyll-theme-resume/template_key_checker.rb` checks the theme's own `_layouts`/`_includes` Liquid templates for references to data keys that don't exist — reached via the `check-data-keys` CLI and the `rake check_data_keys` task ([section 11](#11-template-key-checker-check-data-keys)); unlike the resume validator, it runs only in this repository's own development workflow and CI, never on a consuming site's build, and it is not packaged in the gem. This page describes what each checks and how their entry points behave.
+
+---
+
+## 1. What Gets Checked
+
+Findings are **errors** or **warnings**. Errors make the CLI exit 1; warnings do too only with `--fail-on-warnings`.
+
+| Check | Severity |
+|---|---|
+| YAML syntax in every data, locale, and config file | Error |
+| A configured language has no locale file (neither theme nor site) | Error |
+| A configured language has no data folder | Error |
+| A `languages.<lang>` entry has no `data_path` | Error |
+| An explicit `--config` file does not exist | Error |
+| Required fields per section, date formats, inverted date ranges, URLs that do not parse or do not start with `http://` or `https://` | Error (see [catalog](#6-validation-rules-catalog-by-section)) |
+| A section file exists in one language folder and not another (file parity) | Warning |
+| A language's effective locale is missing keys the reference locale has (locale parity) | Warning |
+| Missing or non-boolean `active` flag, brief or missing header intro, skill `level` outside 1 to 5 | Warning |
+
+Entries with `active: false` skip schema checks after the `active` flag check.
+
+---
+
+## 2. How Languages and Locales Are Resolved
+
+**Config.** The validator reads the site's Jekyll config to learn which languages exist. It uses the first file found: the `--config` path, then `<data_dir>/_config.yml`, `<data_dir>/_config.sample.yml`, `<data_dir>/../_config.yml`, `<data_dir>/../_config.sample.yml`. The Jekyll plugin passes the already-loaded site config instead.
+
+**Languages.** The set of languages to validate is, in order of precedence:
+
+1. `--languages` on the CLI, if given.
+2. Every key under `languages:` in the config. Each language's folder is `<data_dir>/<data_path>`, with dot paths split into folders (`2025-06.v1` resolves to `<data_dir>/2025-06/v1`).
+3. With no `languages:` in the config (or no config), a directory scan of `<data_dir>` for folders named like language codes (`en`, `pt-BR`, `zh_CN`) that contain YAML files. Folders named `locales`, `sample`, `archive`, `assets`, and similar are skipped.
+
+`--all-locales` adds the directory scan on top of 1 or 2.
+
+**Locales.** Each language's effective locale is the theme gem's `_data/locales/<lang>.yml` with the site's `<data_dir>/locales/<lang>.yml` deep-merged over it: nested hashes merge key by key, arrays (`months`, `present_values`) are replaced whole. This mirrors how Jekyll layers theme and site data (see [`multilingual-and-rtl-design.md`](../explanation/multilingual-and-rtl-design.md#overriding-theme-locales)). Locale parity is checked on the merged result, so a one-line site override warns on nothing, while a site-only locale for a language the theme does not ship must be complete.
+
+**Reference language.** Locale parity compares every language against one reference: `--primary` (default `en`) if it has a locale, else `default_lang`, else the first language that has one. File parity uses `--primary` if it has a data folder, else the first language that does.
+
+---
+
+## 3. CLI Validator (`validate-resume`)
+
+The gem installs `validate-resume` as an executable. In a consuming site run it through Bundler; in this repository run `./bin/validate-resume`.
+
+```bash
+bundle exec validate-resume                       # auto-detects the data directory
+bundle exec validate-resume _data                 # explicit data directory
+bundle exec validate-resume _data -c _config.yml  # explicit config
+./bin/validate-resume demo/_data                  # this repository's six-language demo
+```
+
+With no `DATA_DIR`, the CLI uses the first of `_data` and `demo/_data` that contains at least one language folder, else `_data`. A positional `DATA_DIR` wins over `-d`.
+
+| Flag | Long flag | Description | Default |
+|---|---|---|---|
+| `-d DIR` | `--dir DIR` | Data directory | `_data` or `demo/_data` |
+| `-c FILE` | `--config FILE` | Jekyll config that declares `languages:` | First config found next to the data directory ([section 2](#2-how-languages-and-locales-are-resolved)) |
+| `-l LANGS` | `--languages LANGS` | Comma-separated languages to validate; overrides the config | The config's `languages:` |
+| `-a` | `--all-locales` | Also validate every language folder found by directory scan | off |
+| `-p LOCALE` | `--primary LOCALE` | Reference language for parity checks | `en` |
+| `-w` | `--fail-on-warnings` | Exit 1 on warnings as well as errors | off |
+| `-v` | `--verbose` | Accepted for compatibility; currently has no effect | off |
+| `-q` | `--quiet` | Print only when there are findings | off |
+| `-h` | `--help` | Show usage | |
+
+Exit codes (from [`bin/validate-resume`](../../bin/validate-resume), which exits with the value `validate` returns; see [section 12](#12-ruby-api-resumevalidator)):
+
+| Code | When |
+|---|---|
+| `0` | No errors, and no warnings under `-w`; also after `-h` prints usage |
+| `1` | Any error (including a data directory that does not exist), or any warning under `-w` |
+
+An unrecognized option raises an uncaught `OptionParser` exception, so Ruby exits with status `1` before validation starts.
+
+---
+
+## 4. Rake Task (`rake validate`)
+
+```bash
+bundle exec rake validate               # _data if _data/en exists, else demo/_data
+bundle exec rake "validate[path/to/_data]"
+```
+
+The task takes no config argument; it finds the config next to the data directory as described in [section 2](#2-how-languages-and-locales-are-resolved). For what the default `bundle exec rake` task runs, see [testing-suites.md](testing-suites.md#test-tasks).
+
+---
+
+## 5. Jekyll Build-Time Validation
+
+When the gem is loaded as a plugin (through `group :jekyll_plugins` in the site's `Gemfile` or the theme name in `_config.yml`’s `plugins:` list), `_plugins/resume_validator.rb` validates the site's `data_dir` on every `jekyll build` and `jekyll serve`. It is **on by default**; findings are logged and the build continues.
+
+To opt out or gate the build on findings, see [Validate resume data in CI](../how-to/validate-in-ci.md#configure-build-time-validation).
+
+| Key | Default | Effect |
+|---|---|---|
+| `validate_resume` | on (unset) | Only the literal value `false` disables validation. |
+| `validate_resume_strict` | `false` | `true` raises `Jekyll::Errors::FatalException` when there are errors. |
+| `validate_resume_fail_on_warnings` | `false` | With `validate_resume_strict: true`, warnings also abort the build. Has no effect without strict mode. |
+
+If the configured `data_dir` does not exist, the plugin logs a warning and skips validation.
+
+---
+
+## 6. Validation Rules Catalog by Section
+
+The rules are identical for every language. Required fields must use the canonical key the templates render. Names in parentheses are aliases the templates never read: an entry that sets only an alias still fails, and the error names the alias it found (for example `Missing required field 'company': found 'organization', but the theme only renders 'company'`). Field names are listed in [data-schemas.md](data-schemas.md).
+
+| Section file | Required fields | Checked when present |
+|---|---|---|
+| `header.yml` | Must be a Hash | `intro` (or `about`): warning if missing or under 20 characters |
+| `experience.yml` | `company` (`organization`), `position` (`role`) | `startdate`, `enddate` (date or "present"), date order, `url`, empty `durations[].duration` warns; warning if none of `startdate`, `enddate`, or `durations` is set |
+| `education.yml` | `uni` (`institution`, `school`), `degree`, and nonblank `year` unless `startdate` is supplied | `startdate`, `enddate` (date or "present"), date order, `url` |
+| `certifications.yml` | `name` (`title`) | `issue_date`, `expiration`, `expiration >= issue_date`, `credential_url` |
+| `courses.yml` | `name` (`title`, `course`) | `startdate`, `enddate`, date order, `credential_url` |
+| `volunteering.yml` | `company` (`organization`), `position` (`role`) | `startdate`, `enddate` (date or "present"), date order, `url` |
+| `projects.yml` | `project` (`title`, `name`) | `url`, `startdate`, `enddate` (date or "present"), date order |
+| `skills.yml` | `skill` (`category`, `name`) | `level` is an integer 1 to 5 (warning) |
+| `recognitions.yml` | `award` (`title`, `recognition`) | `date` (ISO) |
+| `associations.yml` | `organization` (`company`, `name`) | `url` |
+| `languages.yml` | `language` (`name`) | |
+| `links.yml` | `description` (`name`, `title`), `url` | `url` |
+| `publications.yml` | `name` (`title`) | `release_date` (ISO), `url` (http/https) |
+| `references.yml` | `name`, `reference` (`quote`, `text`) | none |
+| `interests.yml` | none; missing `description` is a warning (naming `interest`/`name` when one is set) | No `active` flag check |
+
+Every file except `header.yml` must be a list of Hashes. Every list entry except in `interests.yml` should carry `active: true` or `active: false`.
+
+Dates must be ISO: `YYYY-MM-DD`, `YYYY-MM`, or `YYYY`. Ranges compare at the precision given, with partial end dates extended to the end of their period, so `2024-05-15` to `2024-05` is valid and `2025-01` to `2024-05` is an error.
+
+URLs must parse and must start with `http://` or `https://`; either failure is an error.
+
+---
+
+## 7. "Present" Dates
+
+The words the validator accepts for an ongoing `enddate` are listed in [Present values](locale-keys.md#present-values).
+
+---
+
+## 8. Troubleshooting
+
+Findings and their fixes are in [Troubleshoot builds](../how-to/troubleshoot-builds.md).
+
+---
+
+## 9. Continuous Integration
+
+This repository's workflows are listed in [testing-suites.md](testing-suites.md#continuous-integration). A consuming-site workflow is in [Validate resume data in CI](../how-to/validate-in-ci.md#run-the-validator-in-github-actions).
+
+---
+
+## 10. Built-HTML Proofing & Static Analysis
+
+Commands are in [Validate resume data in CI](../how-to/proof-built-html.md); proofing semantics are in [testing-suites.md](testing-suites.md#built-html-proofing-semantics).
+
+---
+
+## 11. Template Key Checker (`check-data-keys`)
+
+Why the checker exists and why it never defaults to `--fail-on-warnings`: [Resume Data Validator](../explanation/architecture.md#two-verification-engines).
+
+```bash
+./bin/check-data-keys demo/_data                  # this repository's six-language demo (the default target)
+./bin/check-data-keys demo/_data --fail-on-warnings  # opt into strict mode yourself, once you trust your data's coverage
+bundle exec rake check_data_keys                     # _data if _data/en exists, else demo/_data; never fails the task
+bundle exec rake "check_data_keys[path/to/_data]"
+```
+
+| Flag | Long flag | Description | Default |
+|---|---|---|---|
+| `-d DIR` | `--dir DIR` | Data directory whose sample data defines the known keys | `_data` or `demo/_data` |
+| `-c FILE` | `--config FILE` | Jekyll config that declares `languages:` | `_config.yml` / `_config.sample.yml` next to the data directory |
+| `-w` | `--fail-on-warnings` | Exit 1 on warnings | off |
+| `-v` | `--verbose` | Accepted for compatibility; currently has no effect | off |
+| `-q` | `--quiet` | Print only when there are findings | off |
+| `-h` | `--help` | Show usage | |
+
+With no `DATA_DIR`, `check-data-keys` uses the first of `_data` and `demo/_data` that contains at least one language folder, else `demo/_data`. A positional `DATA_DIR` wins over `-d`.
+
+Scans only `_layouts/*.html` and `_includes/**/*.html` — this repository's own shipped templates, never a consuming site's `_pages/` or `_layouts/`/`_includes` overrides. Runs in `bundle exec rake` (the default task) and in both CI workflows ([testing-suites.md](testing-suites.md#continuous-integration)), always without `--fail-on-warnings`.
+
+---
+
+## 12. Ruby API (`ResumeValidator`)
+
+`JekyllThemeResume::ResumeValidator` in [`lib/jekyll-theme-resume/resume_validator.rb`](../../lib/jekyll-theme-resume/resume_validator.rb) backs the CLI, the Rake task, and the Jekyll generator. Public interface:
+
+| Signature | Behavior |
+|---|---|
+| `new(data_dir = "_data", config_path: nil, config: nil, primary_locale: "en")` | Stores the data directory (trailing `/` removed), an explicit config path, an already-parsed site config Hash (the Jekyll plugin passes `site.config`; when `nil` the config is looked up on disk, `config_path` first), and the reference language (`nil` becomes `"en"`). |
+| `validate(languages: nil, all_locales: false, primary_locale: nil, verbose: false, quiet: false, fail_on_warnings: false)` | Clears previous findings, runs every check on the resolved languages, prints the report (skipped under `quiet:` when there are no findings), and returns `1` when there are errors or, with `fail_on_warnings: true`, warnings; otherwise `0`. A missing data directory is an error and returns `1` at once. A non-nil `primary_locale:` replaces the one given to `new`. |
+| `discover_languages` | Returns the subfolders of the data directory that are named like language codes, are not in the skip list, and contain `.yml`/`.yaml` files, with `primary_locale` first (when it is among them) and the rest sorted; `[]` if the data directory does not exist. |
+| `locale_for(lang)` | Returns the effective locale Hash for `lang` (stripped and downcased): the theme's `_data/locales/<lang>.yml` with the site's `<data_dir>/locales/<lang>.yml` deep-merged over it, a site-only locale as-is, or `nil` when neither exists; cached per `validate` run. |
+| `present_aliases_for(lang = nil)` | Returns the unique accepted "present" words for `lang`: the effective locale's `present_values` plus its `ui.present`, falling back to the `default_lang` (else reference-language) locale when `lang` has none; a `nil` or blank `lang` returns the words of every known locale. |
+| `present_date?(date_val, lang: nil)` | Returns `false` for `nil`, `Date`, or `Time` values, `true` for a blank string, and otherwise whether the value matches one of `present_aliases_for(lang)` case-insensitively. |
+
+Read-only attributes: `data_dir`, `errors`, `warnings`, `primary_locale`, and `info` (currently always empty). Each finding is a Hash `{ context:, message: }`.