jekyll-theme-resume 1.3.0

data/bin/validate-resume

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../lib/jekyll-theme-resume/resume_validator"
+
+options = {
+  data_dir: nil,
+  config_path: nil,
+  languages: nil,
+  all_locales: false,
+  primary_locale: "en",
+  verbose: false,
+  quiet: false,
+  fail_on_warnings: false
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: validate-resume [options] [DATA_DIR]"
+  opts.separator ""
+  opts.separator "Validates multilingual Jekyll resume YAML data for schema conformance, parity, and formatting."
+  opts.separator ""
+  opts.separator "Options:"
+
+  opts.on("-d", "--dir DIR", "Path to data directory (default: _data or demo/_data)") do |d|
+    options[:data_dir] = d
+  end
+
+  opts.on("-c", "--config FILE", "Jekyll config declaring `languages:` (default: _config.yml / _config.sample.yml next to DATA_DIR)") do |c|
+    options[:config_path] = c
+  end
+
+  opts.on("-l", "--languages LANGS", Array, "Comma-separated languages to validate (default: the config's `languages:`)") do |langs|
+    options[:languages] ||= []
+    options[:languages].concat(langs).uniq!
+  end
+
+  opts.on("-a", "--all-locales", "Also validate every language directory found in the data dir") do
+    options[:all_locales] = true
+  end
+
+  opts.on("-p", "--primary LOCALE", "Primary reference locale for parity checking (default: en)") do |p|
+    options[:primary_locale] = p
+  end
+
+  opts.on("-w", "--fail-on-warnings", "Treat warnings as errors and exit with code 1") do
+    options[:fail_on_warnings] = true
+  end
+
+  opts.on("-v", "--verbose", "Enable verbose validation output") do
+    options[:verbose] = true
+  end
+
+  opts.on("-q", "--quiet", "Suppress non-essential output (only report failures)") do
+    options[:quiet] = true
+  end
+
+  opts.on("-h", "--help", "Show this help message") do
+    puts opts
+    exit 0
+  end
+end
+
+parser.parse!
+
+# Positional argument takes precedence over -d, or fall back to standard data dirs
+data_dir = ARGV[0] || options[:data_dir]
+if data_dir.nil?
+  # Prefer a directory that holds at least one language folder (a site's _data, else the theme's demo).
+  data_dir = %w[_data demo/_data].find do |dir|
+    JekyllThemeResume::ResumeValidator.new(dir).discover_languages.any?
+  end || "_data"
+end
+
+validator = JekyllThemeResume::ResumeValidator.new(
+  data_dir,
+  config_path: options[:config_path],
+  primary_locale: options[:primary_locale]
+)
+exit_code = validator.validate(
+  languages: options[:languages],
+  all_locales: options[:all_locales],
+  primary_locale: options[:primary_locale],
+  verbose: options[:verbose],
+  quiet: options[:quiet],
+  fail_on_warnings: options[:fail_on_warnings]
+)
+
+exit exit_code

data/bin/verify

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Runs the AGENTS.md Rule 5 verification suite. Full output goes to a log;
+# stdout gets one line per step plus the log tail of the first failure.
+set -u
+cd "$(dirname "$0")/.."
+log="${TMPDIR:-/tmp}/resume-theme-verify.log"
+: > "$log"
+
+cleanup() { rm -rf .jekyll-cache jekyll-theme-resume-*.gem; }
+
+step() {
+  local name=$1; shift
+  echo "=== $name: $*" >> "$log"
+  if "$@" >> "$log" 2>&1; then
+    echo "PASS $name"
+  else
+    echo "FAIL $name (full log: $log)"
+    tail -n 40 "$log"
+    cleanup; exit 1
+  fi
+}
+
+step build bundle exec jekyll build --source demo --destination _site
+step rake  bundle exec rake
+step gem   gem build jekyll-theme-resume.gemspec
+cleanup
+echo "ALL PASS (full log: $log)"

data/docs/README.md

@@ -0,0 +1,89 @@
+# Documentation
+
+This documentation is organized by what you need right now: learn the theme, do a task, look something up, or understand why it works the way it does. Each page states its audience under the title.
+
+**Start here**
+
+- New to the theme? Follow the [tutorial](tutorials/getting-started.md) to get a two-language resume running.
+- Something broke? See [Troubleshoot builds](how-to/troubleshoot-builds.md).
+- Not sure what a term means? See the [Glossary](reference/glossary.md).
+
+## Tutorial
+
+| Page | Audience | You will |
+|---|---|---|
+| [Getting Started](tutorials/getting-started.md) | Site owners | Build and run an English and Arabic resume site from an empty folder. |
+
+## How-to guides
+
+Steps for one task each.
+
+| Page | Audience | Use it to |
+|---|---|---|
+| [Add a language](how-to/add-a-language.md) | Site owners | Add a new language with its locale file, data folder, and pages. |
+| [Add a custom section](how-to/add-a-section.md) | Site owners and theme developers | Add a resume section that renders in every language. |
+| [Add a social platform](how-to/add-a-social-platform.md) | Theme developers | Add a social network icon and label. |
+| [Add a test](how-to/add-a-test.md) | Theme developers | Run the test suites and add a test for a change. |
+| [Create a custom layout](how-to/create-a-custom-layout.md) | Theme developers | Add a page design that still renders in every language. |
+| [Enable dark mode](how-to/enable-dark-mode.md) | Site owners and theme developers | Show the dark mode toggle site-wide or on one page. |
+| [Link translations with hreflang](how-to/link-translations-with-hreflang.md) | Site owners | Connect the translations of a page for the language switcher and `hreflang` tags. |
+| [Migrate from v0.9 to v1.0](how-to/migrate-v0.9-to-v1.0.md) | Site owners | Upgrade a v0.9.0 site. |
+| [Override locale strings](how-to/override-locale-strings.md) | Site owners | Change UI text, fonts, error-page copy, or accepted "present" words. |
+| [Override Sass partials](how-to/override-sass-partials.md) | Site owners | Change theme styles, including the accent color, without forking the gem. |
+| [Proof the built HTML and lint the Ruby](how-to/proof-built-html.md) | Theme developers | Check a built site for dead links and missing assets, and run RuboCop. |
+| [Publish the JSON Resume export](how-to/publish-json-resume.md) | Site owners | Serve the generated `resume.json` files. |
+| [Show language proficiency in the header](how-to/show-language-proficiency-in-header.md) | Site owners | Show a one-line language summary in the resume header. |
+| [Switch resume versions](how-to/switch-resume-versions.md) | Site owners | Load a different set of resume data for a language. |
+| [Troubleshoot builds](how-to/troubleshoot-builds.md) | Site owners and theme developers | Diagnose a build problem from the symptom. |
+| [Validate resume data in CI](how-to/validate-in-ci.md) | Site owners and theme developers | Gate builds on validation and run the checks in GitHub Actions. |
+| [Verify accessibility](how-to/verify-accessibility.md) | Site owners and theme developers | Run the automated and manual accessibility checks. |
+
+## Reference
+
+Facts to look up: keys, schemas, flags, and structure.
+
+| Page | Audience | Contains |
+|---|---|---|
+| [Configuration reference](reference/config.md) | Site owners | Every `_config.yml` setting. |
+| [Data schemas](reference/data-schemas.md) | Site owners | The YAML schema of every resume data file. |
+| [Locale keys](reference/locale-keys.md) | Site owners and theme developers | The locale file schema, shipped locales, and override rules. |
+| [JSON Resume export reference](reference/json-resume-fields.md) | Site owners | Export configuration, privacy, and field mappings. |
+| [Validator and build checks](reference/validator-cli.md) | Site owners and theme developers | `validate-resume`, `check-data-keys`, rules by section, and the Ruby API. |
+| [Accessibility coverage](reference/accessibility-coverage.md) | Site owners and theme developers | What the theme implements and what the automated checks cover. |
+| [Layouts reference](reference/layouts.md) | Site owners and theme developers | The layouts, language resolution, and data loading. |
+| [Includes reference](reference/includes.md) | Theme developers | Every include and its parameters. |
+| [Sass reference](reference/sass-tokens.md) | Theme developers | The stylesheet architecture, partials, and dark mode tokens. |
+| [Testing suites](reference/testing-suites.md) | Theme developers | What each test suite proves. |
+| [Repository map](reference/repository-map.md) | Theme developers | The annotated code tree. |
+| [Glossary](reference/glossary.md) | Site owners and theme developers | Definitions of terms used across the docs. |
+
+## Explanation
+
+Why the theme is designed the way it is.
+
+| Page | Audience |
+|---|---|
+| [Architecture](explanation/architecture.md) | Theme developers |
+| [Multilingual and RTL design](explanation/multilingual-and-rtl-design.md) | Site owners and theme developers |
+| [The data-driven model](explanation/data-driven-model.md) | Site owners and theme developers |
+| [Dark mode approach](explanation/dark-mode-approach.md) | Site owners and theme developers |
+| [Accessibility decisions](explanation/accessibility-decisions.md) | Site owners and theme developers |
+
+## Working on the theme: where things live and how to check a change
+
+These commands assume a checkout of the theme repository.
+
+| Need / Task | Go to | Check your change |
+|---|---|---|
+| Configure site settings, languages, avatar, or analytics | `_config.yml`, [Configuration reference](reference/config.md) | Run the demo build; see [Getting Started](tutorials/getting-started.md) |
+| Add a language or change UI strings, fonts, or month names | `_data/locales/<lang>.yml`, [Add a language](how-to/add-a-language.md), [Override locale strings](how-to/override-locale-strings.md), [Locale keys](reference/locale-keys.md) | `./bin/validate-resume demo/_data`, then inspect `_site/<lang>/cv/` |
+| Modify resume section data | `_data/<lang>/*.yml`, [Data schemas](reference/data-schemas.md) | `./bin/validate-resume demo/_data` |
+| Customize error pages or return URLs | `_layouts/error.html`, `_plugins/error_pages_generator.rb`, `error_pages` in the locale files, [Layouts reference](reference/layouts.md), [Locale keys](reference/locale-keys.md) | Inspect `_site/404.html`, `_site/500.html` |
+| Adjust dark mode colors or tokens | `_sass/_dark-mode.scss`, [Sass reference](reference/sass-tokens.md), [Dark mode approach](explanation/dark-mode-approach.md) | Inspect CSS variables on `:root` and `[data-theme="dark"]` |
+| Adjust RTL mirroring | `_sass/_resume-rtl.scss`, [Sass reference](reference/sass-tokens.md) | Inspect `_site/ar/cv/` and `_site/ur/cv/` |
+
+## Project files
+
+- [Changelog](../CHANGELOG.md): release notes.
+- [`_config.sample.yml`](../_config.sample.yml): the annotated sample configuration for a consuming site.
+- [Contribution and agent rules](https://github.com/kmutahar/jekyll-theme-resume/blob/master/AGENTS.md) (`AGENTS.md`, not shipped in the gem).

data/docs/explanation/accessibility-decisions.md

@@ -0,0 +1,27 @@
+# Accessibility decisions
+
+*Audience: site owners and theme developers*
+
+This page explains the accessibility choices the theme makes, and the limits that come with them. For what is covered and how to check it, see [accessibility coverage](../reference/accessibility-coverage.md) and [verify accessibility](../how-to/verify-accessibility.md).
+
+## What the theme claims, and what it does not
+
+The theme describes its accessibility features and the checks a consuming site needs; it is not a certification of complete WCAG conformance. That is deliberate. Content, custom colors, third-party integrations, and browser behavior all affect the result, and none of them are under the theme's control. A theme can supply sound building blocks, but only the finished site can be judged.
+
+## Structure and keyboard navigation
+
+Headers and footers use semantic HTML, and the resume also supplies explicit banner and contentinfo roles. The profile header sits outside its main content, so its skip link bypasses the name and bio. That is a trade-off of the layout: a keyboard user jumps past the header block, including the name and bio, to reach the content.
+
+`_sass/_base.scss` owns `.sr-only`, the skip-link styles, and the `:focus-visible` outlines, and the skip link becomes visible on focus. The language switcher (`_includes/language-switcher.html`) uses native `<details>`/`<summary>` and a labelled `<nav>`. Enter and Space toggle the disclosure. The cost of choosing the native element is that Escape and outside clicks do not automatically close it, because the theme adds no script to imitate that behavior.
+
+The language switcher is fixed top-left, and the optional theme toggle top-right, in every language, and both are hidden for print. Fixed positioning keeps them in the same place across languages, but small-screen overlap and focus visibility still need browser testing.
+
+## Color contrast
+
+Contrast is a property of a foreground/background pair, not of a token in isolation, so the theme's tokens have to be judged in the pairs they are used in. For example, the muted text token on a white background falls short of the AA contrast ratio for normal-size text; the measured ratios are in [accessibility coverage](../reference/accessibility-coverage.md#color-contrast). The token values are listed in [SASS tokens](../reference/sass-tokens.md).
+
+Hover, focus, disabled, print, and customized colors each need to be checked separately from the default state. Focus outlines do not establish that pointer targets meet target-size requirements. Hiding the theme toggle does not force a light palette: system and stored preferences still apply (see [the dark mode approach](dark-mode-approach.md)).
+
+## Summary
+
+The theme ships `.sr-only` utilities, visible `:focus-visible` outlines, landmarks, and localized skip links. Known limits are the ones above; coverage and verification steps are in the reference and how-to pages linked at the top.

data/docs/explanation/architecture.md

@@ -0,0 +1,44 @@
+# Architecture
+
+*Audience: theme developers*
+
+This page explains how the theme fits together: the layouts and generators, how the pieces are wired, the two verification engines, and the Liquid pitfalls that shape the templates. For the annotated file tree see [repository map](../reference/repository-map.md); to build the demo site, see [getting started](../tutorials/getting-started.md).
+
+**jekyll-theme-resume** is a Ruby gem / Jekyll theme for data-driven, multilingual resume and CV sites. One locale-agnostic layout renders every language, left-to-right or right-to-left, from YAML data and per-language locale files. The theme ships six locales: English, Arabic, Spanish, French, German, and Urdu.
+
+---
+
+## Components
+
+### Layouts and generators
+The four layouts (`default.html`, `profile.html`, `resume.html`, `error.html`) are described in the [layouts reference](../reference/layouts.md#layout-inventory).
+
+- `_plugins/error_pages_generator.rb` adds missing `404`, `403`, and `500` pages to consuming sites. A manual error page can use `code: 503`.
+- `_plugins/resume_pages_generator.rb` creates missing CV pages at each `languages.<lang>.url` and profiles at `/` or `/<lang>/`. Manual pages take precedence; see [page configuration](../reference/config.md#3-languages).
+
+### Two verification engines
+
+The repository has two verification engines, and only the resume-data validator ships in the gem: it checks resume YAML data, including during every consuming site's build. The template key checker checks the theme's own templates and runs only in this repository's development workflow and CI, never on a consuming site's build. The entry points and what each one checks are in the [validator reference](../reference/validator-cli.md).
+
+`check-data-keys` catches a different class of bug than the resume validator: not bad *data*, but a Liquid template in `_layouts` or `_includes` referencing a field that doesn't exist anywhere in the checked sample data (e.g. `item.discription` instead of `item.description`), which renders silently blank rather than raising an error. It traces `resume_data.<section>` bindings through `for`/`assign`/include-parameter chains, including the `grouped-item-list.html` include boundary and the `group_by` filter's synthetic `{name, items}` wrapper, since the theme's templates never write literal `site.data.foo.bar`.
+
+Because "known keys" are derived from whatever the checked sample data actually contains, a field a template correctly references but that no language in the checked data happens to exercise (an optional field, e.g. `education.yml`'s `awards` list) will warn even though nothing is wrong. For this reason `check-data-keys` never defaults to `--fail-on-warnings` in this repository's Rake task or CI steps, unlike `validate-resume`. Warnings are printed and worth reading, but a warning alone does not mean the template is broken; cross-check against the field before "fixing" it.
+
+### Accessibility
+- `.sr-only` utilities, visible `:focus-visible` outlines, landmarks, and localized skip links. Coverage and known contrast limitations are documented in [accessibility coverage](../reference/accessibility-coverage.md).
+
+### Liquid pitfalls
+
+Three Liquid behaviors shape how the templates are written, and the tests guard each of them.
+
+- **Presence checks never use `blank`.** Liquid's `blank` literal calls Ruby's `blank?`, which plain Jekyll strings and `nil` do not define, so `x != blank` is always true and would render empty sections. The templates use `x.size > 0` for text and a plain truthiness test `x` for dates.
+- **Dates are never passed to the `date` filter.** The filter reads a bare year such as `2018` as a Unix timestamp. `date-formatter.html` therefore parses the ISO parts itself.
+- **Includes share the caller's variables.** An include has no scope of its own, so an unprefixed loop variable would overwrite `lang`, `locale`, or `lang_cfg` in `resume.html`. Loop and helper variables inside includes carry a prefix (`switch_` in `language-switcher.html`, `social_` in the social includes).
+
+### Why `@use` instead of `@import`
+
+The theme uses modern Dart Sass `@use` exclusively, instead of the deprecated `@import`. Namespacing keeps variables and mixins encapsulated (for example `variables.$white`, `@include mixins.clearfix`), which prevents global pollution. Modules load only what they explicitly require.
+
+### Tests use public interfaces only
+
+Every test goes through a public interface: the HTML a visitor receives, a Ruby class's public methods, a CLI's exit code and output, or the gem's file list. No test calls a private method. Suites are listed in [testing suites](../reference/testing-suites.md).

data/docs/explanation/dark-mode-approach.md

@@ -0,0 +1,25 @@
+# Dark mode approach
+
+*Audience: site owners and theme developers*
+
+This page explains why dark mode is built the way it is: every color is a token, activation has two tiers, and a small inline script prevents a flash. For the token values see [SASS tokens](../reference/sass-tokens.md); to turn the toggle on, see [enable dark mode](../how-to/enable-dark-mode.md).
+
+## One place for every color
+
+[`_sass/_dark-mode.scss`](../../_sass/_dark-mode.scss) holds every color token on `:root`. Keeping the palette in tokens means a dark palette is a matter of redefining variables rather than restyling components.
+
+## Two tiers of activation
+
+Activation has two tiers. The first is automatic: the stylesheet uses `prefers-color-scheme: dark`, applied to `:root` unless it is explicitly pinned to light through `data-color-scheme="light"` or `data-theme="light"`. So `dark_mode: auto` adapts to the visitor's system with no JavaScript. The second is an explicit pin: `:root[data-color-scheme="dark"]` or `:root[data-theme="dark"]` sets the dark palette regardless of the system. `dark_mode: enabled` adds a toggle that uses `localStorage` to persist the visitor's choice. The `:not(...)` guard on the first tier is what lets an explicit light pin win over a dark system preference. The first tier is a no-JavaScript baseline that respects the operating system; the second exists so a visitor can override it.
+
+## Avoiding a flash of the wrong theme
+
+A stored preference lives in `localStorage`, which only script can read, and stylesheets would otherwise paint first. To prevent theme flashing (FOUC), an inline `<head>` script in [`_includes/shared-head.html`](../../_includes/shared-head.html) applies the stored preference before stylesheets load.
+
+## What the settings do not do
+
+Page front matter `dark_mode: false` or `true` controls the toggle on one page. These settings do not disable the system-preference CSS or the stored-preference script; `false` hides the button rather than forcing a light palette. Hiding the control and removing the behavior are different things: a visitor whose system is dark, or who stored a preference earlier, still gets that palette. See [config](../reference/config.md) for the setting itself.
+
+## Print
+
+Dark mode does not apply to print or PDF. `@media print` in `_sass/_dark-mode.scss` forces black text on white, and the toggle carries `.no-print`, so the control does not appear on paper either.

data/docs/explanation/data-driven-model.md

@@ -0,0 +1,25 @@
+# The data-driven model
+
+*Audience: site owners and theme developers*
+
+This page explains why resume content lives in per-language YAML data, how the theme finds and reads it, and the limits of the JSON export. For schemas see [data schemas](../reference/data-schemas.md), and for the lookup mechanics see [layouts](../reference/layouts.md).
+
+## Content as data, one folder per language
+
+Resume content lives in YAML files, one folder per language. Keeping one folder per language (`_data/en/`, `_data/ar/`, `_data/es/`, and so on), each holding the same file names, means every language renders through the same layout and only the data differs. Complete starter data for six languages (a Sherlock Holmes demo persona) is in [`demo/_data/`](../../demo/_data/): `en`, `ar`, `es`, `fr`, `de`, `ur`.
+
+Each language's folder is set by `languages.<lang>.data_path` in `_config.yml`. Dot paths such as `"2025-06.v1"` select nested, versioned datasets, so several versions of a resume can live side by side and a language can point at whichever one it needs. See [config](../reference/config.md) for the setting.
+
+## Why lookups are written the way they are
+
+Sections render in the order of `site.resume_section_order` through one dispatcher, [`_includes/resume-section.html`](../../_includes/resume-section.html), plus the `header.yml` intro. Order is therefore configuration, not template code; the list of sections is in [data schemas](../reference/data-schemas.md).
+
+Two Liquid details shape how data is read. Presence checks use `field.size > 0` for text or a plain truthiness test for dates, never `!= blank`; the reason is in [Liquid pitfalls](architecture.md#liquid-pitfalls).
+
+Bracket access (`resume_data[part]`) is what makes folder names like `2025-06` or `20250621-PM` work; Liquid dot notation (`site.data.2025-06`) fails on leading digits and hyphens. Using brackets is what allows dated, versioned folder names.
+
+## Privacy and the limits of the JSON export
+
+The JSON export is built from the same data, but it is a supported subset of the CV, not a lossless representation of every website field. Documented optional enrichment fields can appear in JSON even if HTML does not display those fields.
+
+`json_resume.privacy.export_contact_info: false` omits the structured contact fields; the exact list is in [Visibility and privacy](../reference/json-resume-fields.md#visibility-and-privacy). The setting has limits: it does not redact free-form narrative text, usernames, or arbitrary URLs, and it does not change the HTML site's contact visibility. Treat it as a switch for the structured contact fields, not as a general privacy filter. Field details are in [JSON Resume fields](../reference/json-resume-fields.md).

data/docs/explanation/multilingual-and-rtl-design.md

@@ -0,0 +1,40 @@
+# Multilingual and RTL design
+
+*Audience: site owners and theme developers*
+
+Why the theme treats a language as data rather than code, how theme and site locale files layer, and why right-to-left support is language-neutral. For task steps see [add a language](../how-to/add-a-language.md) and [override locale strings](../how-to/override-locale-strings.md); for the key list see the [locale keys reference](../reference/locale-keys.md).
+
+## What a language is
+
+Since v1.0.0 the theme renders every language through one layout, `_layouts/resume.html`. A language is three things:
+
+1. A **locale file**, `_data/locales/<lang>.yml`: text direction, font, line height, UI strings, month names, "present" words, and error page copy.
+2. A **data folder**, `_data/<data_path>/`: the resume content (`experience.yml`, `education.yml`, and so on). Schemas are in [`data-schemas.md`](../reference/data-schemas.md).
+3. A **config entry**, `languages.<lang>` in `_config.yml`: data path, URL, name, title, address, avatar alt text, and the header intro toggle.
+
+Because nothing else distinguishes one language from another, a language the theme does not ship is added by the site alone, with no Ruby, HTML, or SCSS changes. The shipped locales are listed in the [locale keys reference](../reference/locale-keys.md#shipped-locales). Pages only set `layout: resume` and `lang: <code>`; the layout reads direction and UI copy from the active locale and never branches on a specific language code.
+
+## One date formatter for every language
+
+Dates in the data are written as ISO values and month names come from the locale file, so the data stays language-neutral. [`_includes/date-formatter.html`](../../_includes/date-formatter.html) localizes month names and "Present" for every language. It splits the ISO value itself rather than using Liquid's `date` filter, which reads a bare `2018` as a Unix timestamp. This include is the single date hook for every language: calendar extensions (for example Hijri dates) belong here rather than in a language-specific include. The accepted "present" words are described in the [locale keys reference](../reference/locale-keys.md#present-values).
+
+---
+
+## Overriding Theme Locales
+
+The six locale files ship inside the theme gem, so consuming sites get them with no setup. Jekyll reads theme data first and then deep-merges the site's `_data/` over it; the site wins. This layering is what lets a site change one heading with a one-key file, or replace a whole locale, without forking the theme or waiting for a gem release.
+
+The validator mirrors the same layering: it builds each language's effective locale from the theme file with the site file deep-merged over it, and checks key parity on that merged result. Checking the merged result rather than the site file alone is why a one-line site override warns on nothing, while a site-only locale for a language the theme does not ship must be complete. The merge rules (including how arrays behave) are in the [locale keys reference](../reference/locale-keys.md#overriding-theme-locales).
+
+---
+
+## Typography & RTL
+
+- **Fonts and line height come only from the locale file.** The layout emits them as CSS variables and the stylesheet reads them with the theme's default stacks as fallbacks, so changing a language's font is a locale override, not an SCSS edit. The shipped line heights follow the script: Arabic uses Cairo at `1.6` (room for diacritics); Urdu uses Noto Nastaliq Urdu at `2.0` (Nastaliq glyphs are tall); the LTR locales use the default stacks at `1.5`. The variable names are in the [Sass tokens reference](../reference/sass-tokens.md).
+- **Direction selects the stylesheet.** The layout links `cv-<direction>.css`, where `direction` comes from the locale file, and sets `<html dir>` from the same value.
+- **RTL is language-neutral.** Every RTL locale compiles through `assets/css/cv-rtl.scss`, which loads `_sass/_resume-ltr.scss` and then `_sass/_resume-rtl.scss`. The RTL partial only mirrors positioning (floats, margins, timeline bullets, contact icons; floated elements such as the avatar, social bar, and job title flip alignment) under `html[dir="rtl"]` and resets `letter-spacing` so cursive scripts keep their ligatures. It sets no fonts, so Arabic, Urdu, and any future RTL language each keep their own typeface.
+- **Bidi isolation.** In RTL locales, templates wrap phone numbers, email addresses, URLs, and credential IDs in `dir="ltr"` so Latin punctuation is not reordered.
+
+---
+
+Upgrading from the v0.9.0 per-language layouts (`resume-en`, `resume-ar`) to this model: see [migrate from v0.9 to v1.0](../how-to/migrate-v0.9-to-v1.0.md).

data/docs/how-to/add-a-language.md

@@ -0,0 +1,57 @@
+# Add a language
+
+*Audience: site owners*
+
+Add a new language (Italian, `it`, in this example) to your site, and optionally hand-author its page. The theme has no `it.yml`, so the site supplies a complete locale file.
+
+## Steps
+
+1. **Create the locale file.** Copy the theme's [`_data/locales/en.yml`](../../_data/locales/en.yml) (find the installed theme with `bundle info --path jekyll-theme-resume`; the shipped locales are listed in [Locale keys](../reference/locale-keys.md#shipped-locales)) to your site as `_data/locales/it.yml`, keep every key, and translate the values. Set `direction`, `font_family`, `font_url`, and `line_height` for the script (see [multilingual and RTL design](../explanation/multilingual-and-rtl-design.md)). Replace `months` with the 12 Italian month names and `present_values` with the words your data uses for ongoing roles (for example `["present", "presente", "attuale"]`). Keep `present` in `present_values`: Experience and Volunteering fall back to the English word "Present" for a blank `enddate`, and the formatter translates it only when `present_values` contains it.
+2. **Create the data folder.** Copy an existing language folder (for example `_data/en/`) to `_data/it/` and translate every file. Keep the same file names and the same entries in the same order; the validator reports files that exist in one language and not the other.
+3. **Register the language** in `_config.yml`:
+   ```yaml
+   languages:
+     it:
+       data_path: it             # folder under _data/; dot paths like "2025-06.it" also work
+       url: /it/cv/              # used by error pages, hreflang, and the language switcher
+       header_intro: true        # render _data/it/header.yml intro under the header
+       name: "Nome Cognome"
+       resume_title: "Titolo professionale"
+       address: "Città, Paese"
+       avatar_alt: "Foto di Nome Cognome"
+   ```
+4. **Page (optional).** With `resume_auto_generate_pages` at its default `true`, the theme auto-generates the CV page at `languages.it.url` and a profile page at `/it/` for you, both carrying `t_id: resume` / `t_id: profile`. Create your own `it/cv.md` (`layout: resume`, `lang: it`, `permalink` matching `languages.it.url`) only if you want to hand-author it instead - a hand-authored page always takes precedence. See `resume_auto_generate_pages` / `languages.<lang>.auto_generate_pages` in the [config reference](../reference/config.md).
+5. **Validate and build:**
+   ```bash
+   bundle exec validate-resume _data
+   bundle exec jekyll build
+   ```
+   Done when the validator reports no errors for `it` and `_site/it/cv/index.html` renders with Italian section titles and month names.
+
+The error pages and the language switcher pick up the new language automatically because they loop over `site.languages`. hreflang tags pick it up when the new page shares a `t_id` with its translations: see [Link translations with hreflang](link-translations-with-hreflang.md).
+
+## Hand-author a page
+
+To override a generated page, or disable generation with `resume_auto_generate_pages: false`, create a page with matching `layout` and `lang`:
+
+```markdown
+---
+layout: resume
+lang: it
+permalink: /it/cv/
+t_id: resume        # optional: links translations for hreflang and the language switcher
+---
+```
+
+How the layout resolves a page's language is described in [Language Resolution](../reference/layouts.md#language-resolution).
+
+## Content conventions
+
+- Translate every data file natively; copying English into another language's folder produces a resume that looks localized in the headings and English in the body.
+- Keep proper nouns consistent: transliterate them in non-Latin scripts and keep them as-is in Latin-script languages.
+- Write dates as ISO (`YYYY-MM-DD`, `YYYY-MM`, or `YYYY`). Month names come from the locale file, so the data stays language-neutral.
+- For ongoing roles, leave `enddate` blank or use any value from that locale's `present_values`.
+
+## Troubleshoot: a page renders with no name or content
+
+The page's `lang` has no entry under `languages:`, or that entry's `data_path` points at a folder that does not exist. Run `bundle exec validate-resume _data`.

data/docs/how-to/add-a-section.md

@@ -0,0 +1,35 @@
+# Add a custom section
+
+*Audience: site owners and theme developers*
+
+Add a new resume section (`publications` in this example) that renders in every language.
+
+## Steps
+
+1. **Add the heading to every locale.** Add `ui.section_titles.publications` to each `_data/locales/<lang>.yml` you ship (in a consuming site, add it through site locale overrides; nested keys merge, so a one-key file per language is enough).
+2. **Add one branch** to `_includes/resume-section.html` (in a consuming site, first copy the theme's file to your own `_includes/resume-section.html`), just before the final `{% endif %}`. It serves every language:
+   ```liquid
+   {% elsif include.section_name == "publications" and site.resume_section.publications %}
+     <section class="content-section">
+       <header class="section-header">
+         <h2>{{ locale.ui.section_titles.publications }}</h2>
+       </header>
+       {% for item in resume_data.publications %}
+         {% if item.active == true %}
+           <div class="resume-item">
+             <h3 class="resume-item-title">{{ item.title }}</h3>
+             <p class="resume-item-details">{{ item.publisher }} &bull; {{ item.year }}</p>
+           </div>
+         {% endif %}
+       {% endfor %}
+     </section>
+   ```
+3. **Add data** as `publications.yml` in every language folder. Each file must be a list of items, each with an `active` flag; the validator checks only that shape for custom sections.
+4. **Enable it:** `resume_section.publications: true` and `- publications` in `resume_section_order`.
+
+## See also
+
+- [Show language proficiency in the header](show-language-proficiency-in-header.md)
+- [Includes reference](../reference/includes.md)
+- [Data schemas](../reference/data-schemas.md)
+- [Config reference](../reference/config.md)

data/docs/how-to/add-a-social-platform.md

@@ -0,0 +1,32 @@
+# Add a social platform
+
+*Audience: theme developers*
+
+Add a new social network icon and label to the theme.
+
+## Steps
+
+1. Place an optimized SVG in `_includes/vendors/svg-icons/newplatform.svg`. Match the shipped icons: a square image with `width="24" height="24" viewBox="0 0 24 24"`, and `aria-hidden="true"` and `focusable="false"` on the `<svg>` element, because the link around the icon carries the accessible name. The stylesheet sets the icon color (`.icon-link svg`), so any fill colors inside the SVG do not matter. If the icon comes from a licensed set, add a row to the table in that folder's `ATTRIBUTION.md` giving the file name and the set it came from.
+2. Add an entry to [`_data/social_networks.yml`](../../_data/social_networks.yml), the single list both `social-links.html` and `print-social-links.html` loop over. The order in this file is the order of the icons in the header and of the print list:
+   ```yaml
+   - key: newplatform
+     icon: newplatform
+     itemprop: sameAs # or "url" for a non-profile link
+     label: New Platform
+   ```
+   `key` is the name a site uses under `social_links:` in `_config.yml`. `icon` is the SVG file name without `.svg`. Use `itemprop: sameAs` for a profile that verifies who the person is, `url` for a website or other link, and `email` for an email address. `label` is the English fallback for the icon's accessible name; each locale's label wins when it has one.
+3. Add a `ui.social_labels.newplatform` key to every locale file (the icon's accessible name and the print-only label; the print list has no fallback):
+   ```yaml
+   # _data/locales/<lang>.yml, in each of the six shipped locales
+   ui:
+     social_labels:
+       newplatform: "New Platform"   # translate for each language
+   ```
+   Once the entry from step 2 exists, `test/test_packaging.rb` fails until its SVG and all six labels exist.
+4. To include the platform in the JSON Resume export, add its `key` to `JsonResumeExporter::NETWORKS` in [`lib/jekyll-theme-resume/json_resume_exporter.rb`](../../lib/jekyll-theme-resume/json_resume_exporter.rb). That list is hard-coded, so a platform missing from it is never exported.
+
+## Check it
+
+1. Run `bundle exec ruby test/test_packaging.rb`. It fails with the missing icon's file name, or with the language and key of a missing label, until steps 1 to 3 are complete.
+2. Add the platform to `social_links:` in a site's `_config.yml` (for example `newplatform: "https://example.com/you"`), build, and look for the icon in the header's social row. Hovering over it shows the label.
+3. Open the print preview. The print-only social list shows the platform's label followed by its address.

data/docs/how-to/add-a-test.md

@@ -0,0 +1,34 @@
+# Add a test
+
+*Audience: theme developers*
+
+Run the test suites and add a new test for a change.
+
+## Run the tests
+
+```bash
+git submodule update --init --recursive      # demo/ data is used by several suites
+bundle exec rake                             # validate + check_data_keys + rubocop + every test/test_*.rb
+bundle exec rake test                        # tests only
+bundle exec ruby test/test_rendered_site.rb  # one suite
+bundle exec ruby test/test_rendered_site.rb -n /date/   # tests whose name matches
+```
+
+## Add a test
+
+1. Pick the interface a user or consuming site touches: rendered HTML for templates, `ResumeValidator#validate` for data rules, a site build for generators.
+2. Write the failing test first and run it to see the failure message.
+3. Make the smallest change that passes it, then run `bundle exec rake`.
+
+## Common cases
+
+- **New section field:** add it to `resume_data` in `test_rendered_site.rb` and assert on the rendered text; add a validator rule test if the field is validated.
+- **New locale key:** add it to all six `_data/locales/*.yml` files. `test_packaging.rb` fails if the key sets differ or no template reads the key.
+- **New social platform:** follow [Add a social platform](add-a-social-platform.md); `test_packaging.rb` checks the SVG and labels.
+- **New generator:** require it from `lib/jekyll-theme-resume.rb` and add its class to the registration test in `test_error_pages_generator.rb`.
+
+## See also
+
+- [Testing suites reference](../reference/testing-suites.md)
+- [Validator CLI](../reference/validator-cli.md)
+- [Verification rules](../../AGENTS.md#rule-5-build--packaging-verification)

data/docs/how-to/create-a-custom-layout.md

@@ -0,0 +1,64 @@
+# Create a custom layout
+
+*Audience: theme developers*
+
+Add a new page design (for example `_layouts/academic-cv.html`) that still renders in every language. A new language never needs a new layout; see [Add a language](add-a-language.md).
+
+## Steps
+
+1. Create `_layouts/academic-cv.html` in your site. Start from the skeleton below, or copy the theme's `resume.html` for a full resume variant.
+2. Resolve `lang`, `locale`, and `lang_cfg` with the three lines shown under Language Resolution in the [layouts reference](../reference/layouts.md), and read every visible string from `locale.ui` so the layout works in every language.
+3. Load data with `{% include data-loader.html path=lang_cfg.data_path %}`.
+4. Reuse the shared includes ([`shared-head.html`](../../_includes/shared-head.html), [`avatar.html`](../../_includes/avatar.html), [`dark-mode-toggle.html`](../../_includes/dark-mode-toggle.html), [`resume-section.html`](../../_includes/resume-section.html)).
+5. Reference the layout from a page:
+   ```yaml
+   ---
+   layout: academic-cv
+   lang: en
+   ---
+   ```
+
+## A working skeleton
+
+This layout renders the resume sections in any configured language:
+
+```liquid
+{%- assign lang = page.lang | default: site.default_lang | default: 'en' -%}
+{%- assign locale = site.data.locales[lang] | default: site.data.locales[site.default_lang] -%}
+{%- assign lang_cfg = site.languages[lang] -%}
+{% include data-loader.html path=lang_cfg.data_path %}
+<!DOCTYPE html>
+<html lang="{{ lang }}" dir="{{ locale.direction }}">
+  <head>
+    {% include shared-head.html %}
+    <link rel="stylesheet" href="{{ 'assets/css/cv-' | append: locale.direction | append: '.css' | relative_url }}">
+    {% seo %}
+  </head>
+  <body>
+    <a href="#main-content" class="skip-link no-print">{{ locale.ui.skip_to_content }}</a>
+    {% include dark-mode-toggle.html %}
+    {% include language-switcher.html %}
+    <main id="main-content" role="main" tabindex="-1">
+      <h1>{{ lang_cfg.name }}</h1>
+      {%- for section_name in site.resume_section_order -%}
+        {% include resume-section.html section_name=section_name lang=lang %}
+      {%- endfor -%}
+    </main>
+  </body>
+</html>
+```
+
+What each part does:
+
+- The first four lines resolve the language and load that language's data into `resume_data`.
+- `dir="{{ locale.direction }}"` and the stylesheet name come from the locale, so one layout serves left-to-right and right-to-left languages: the page links `cv-ltr.css` or `cv-rtl.css`.
+- `shared-head.html` adds the charset, viewport, favicons, and the script that applies a saved dark-mode choice before the page paints.
+- The loop renders each section listed in `resume_section_order` that is switched on under `resume_section:` in `_config.yml`.
+
+## Check it
+
+1. Create one page per language, for example `academic.md` (`layout: academic-cv`, `lang: en`, `permalink: /academic/`) and `academic-ar.md` (`lang: ar`, `permalink: /ar/academic/`).
+2. Build the site with `bundle exec jekyll build`.
+3. Open `_site/academic/index.html` and `_site/ar/academic/index.html`. The English page starts with `<html lang="en" dir="ltr">` and links `cv-ltr.css`. The Arabic page starts with `<html lang="ar" dir="rtl">`, links `cv-rtl.css`, and its section headings are in Arabic.
+
+A page that sets no `lang` uses `default_lang`. Keep every visible string in `locale.ui` so nothing in the layout stays in one language.