jekyll-theme-resume 1.3.0

data/docs/how-to/enable-dark-mode.md

@@ -0,0 +1,43 @@
+# Enable dark mode
+
+*Audience: site owners and theme developers*
+
+Show the dark mode toggle site-wide or on individual pages. For why the design works this way, see [dark mode approach](../explanation/dark-mode-approach.md); for the `dark_mode` option values, see the [config reference](../reference/config.md).
+
+## Show the toggle on every page
+
+1. In `_config.yml`, set:
+   ```yaml
+   dark_mode: enabled      # or true
+   ```
+2. Restart `bundle exec jekyll serve`; changes to `_config.yml` are not picked up while it runs.
+3. Open any page. A round button appears fixed in the top-right corner of the window.
+
+The default, `dark_mode: auto`, shows no toggle: the page follows the visitor's system setting. Any value other than `enabled` or `true` also means no toggle.
+
+## Show or hide the toggle on one page
+
+Set `dark_mode` in the page's front matter. It overrides the site setting for that page:
+
+```yaml
+---
+layout: default
+dark_mode: true     # show the toggle on this page; false hides it on this page
+---
+```
+
+## Add the toggle to a custom layout
+
+The theme's own layouts already include the toggle. In a layout of your own, add `{% include dark-mode-toggle.html %}` inside `<body>`, and make sure `<head>` contains `{% include shared-head.html %}`. That include holds the script that applies a saved choice before the page paints, so visitors do not see a flash of the wrong theme.
+
+## Check that it works
+
+1. Click the button. The page switches to the opposite of your system's current setting: dark if your system is light, light if your system is dark.
+2. Reload the page. The choice is kept. The browser stores it in `localStorage` under the key `color-scheme`, with the value `dark` or `light`.
+3. Click the button again. The saved choice is cleared and the page follows your system setting again.
+4. To clear a saved choice by hand, delete the `color-scheme` entry in your browser's developer tools (the storage or application tab).
+5. Print the page, or open the print preview. The toggle is hidden and the page prints black on white.
+
+## Limits
+
+Hiding the toggle does not force a light palette. A visitor whose system prefers dark still gets the dark palette, and a choice saved earlier still applies. The reasons are in [Dark mode approach](../explanation/dark-mode-approach.md).

data/docs/how-to/link-translations-with-hreflang.md

@@ -0,0 +1,25 @@
+# Link translations with hreflang
+
+*Audience: site owners*
+
+Make the language switcher and the `hreflang` tags connect the translations of a page.
+
+Give every translation of a page the same `t_id`:
+
+```yaml
+---
+layout: resume
+lang: en
+permalink: /en/cv/
+t_id: resume
+---
+```
+
+```yaml
+---
+layout: resume
+lang: ar
+permalink: /ar/cv/
+t_id: resume
+---
+```

data/docs/how-to/migrate-v0.9-to-v1.0.md

@@ -0,0 +1,46 @@
+# Migrate from v0.9 to v1.0
+
+*Audience: site owners*
+
+Upgrade a site built on v0.9.0 to v1.0.0. v1.0.0 is a hard break: no aliases, shims, or fallback keys remain for the names below. Replace each one in your site.
+
+## 1. Replace removed names
+
+| Removed (v0.9.0) | Replacement (v1.0.0) |
+|---|---|
+| `layout: resume-en` / `layout: resume-ar` | `layout: resume` + `lang: <code>` |
+| `_includes/resume-section-en.html` / `-ar.html` | `_includes/resume-section.html` |
+| `_includes/resume-head-en.html` / `-ar.html` | Head logic inside `_layouts/resume.html` |
+| `_includes/ar-date.html` | `_includes/date-formatter.html` |
+| `_data/ar/months.yml` | `months:` in `_data/locales/ar.yml` |
+| `_data/error_pages.yml` | `error_pages:` in each `_data/locales/<lang>.yml` |
+| `assets/css/cv.css` / `cv-ar.css` | `assets/css/cv-ltr.css` / `cv-rtl.css` |
+| `active_resume_path_en` / `_ar` | `languages.<lang>.data_path` |
+| `resume_en_url` / `resume_ar_url` | `languages.<lang>.url` |
+| `resume_header_intro_en` / `_ar` | `languages.<lang>.header_intro` |
+| `name` / `name_ar` | `languages.<lang>.name` |
+| `resume_title` / `resume_title_ar` | `languages.<lang>.resume_title` |
+| `contact_info.address` / `address_ar` | `languages.<lang>.address` |
+| `avatar_alt_en` / `avatar_alt_ar` / `avatar_alt` | `languages.<lang>.avatar_alt` |
+| `site.avatar` | `site.avatar_url` |
+| `analytics.ga` | `analytics.gtag` or `analytics.gtm` |
+| `resume_section.recognition` (singular) | `resume_section.recognitions` |
+| `required_ruby_version >= 3.0.0` | `>= 3.3.0` |
+| A plain `gem "jekyll-theme-resume"` line (no longer enough on its own) | Put the line inside `group :jekyll_plugins do ... end`, or list the theme under `plugins:` in `_config.yml`, to load its generators and validator |
+
+## 2. Apply the additional removals
+
+- `languages.<lang>.name` is a plain string (`"Jane Doe"`), not the old `first` / `middle` / `last` hash.
+- The site-level `lang` and `dir` keys no longer affect any layout; direction comes from the locale file and language from `page.lang` or `default_lang`.
+- `font_ar_url` is gone. Override `font_url` in your site's `_data/locales/ar.yml` instead.
+- Error page front matter overrides (`title_en`, `desc_en`, `title_ar`, `desc_ar`) are gone. Override `error_pages` in a site locale file instead.
+- Build-time validation is now on by default. Set `validate_resume: false` to opt out (see [validator CLI reference](../reference/validator-cli.md)).
+
+## 3. Validate and build
+
+Run `bundle exec validate-resume _data` and `bundle exec jekyll build`.
+
+Watch for two silent failures:
+
+- A leftover `layout: resume-en` page only logs a Jekyll "layout does not exist" warning and renders unstyled.
+- A page whose `lang` has no `languages:` entry renders without a name, title, or resume data.

data/docs/how-to/override-locale-strings.md

@@ -0,0 +1,51 @@
+# Override locale strings
+
+*Audience: site owners*
+
+Change UI text, fonts, error-page copy, or accepted "present" words for a language from your consuming site, without forking the theme. The six locale files ship inside the theme gem. Jekyll reads theme data first and then deep-merges the site's `_data/` over it; the site wins. For design background, see [multilingual and RTL design](../explanation/multilingual-and-rtl-design.md).
+
+## Change a few strings
+
+1. Create `_data/locales/<lang>.yml` in your site containing only the keys to change. Nested keys merge one by one, so this file changes one heading and leaves every other Spanish string intact:
+   ```yaml
+   # consuming site: _data/locales/es.yml
+   ui:
+     section_titles:
+       experience: "Trayectoria"
+   ```
+
+## Replace a whole locale
+
+1. Copy the theme file into your site's `_data/locales/` and edit it. No fork or gem release is needed.
+
+## Add a new language
+
+1. Create a complete `_data/locales/<lang>.yml`. There is no theme file to merge with, so every key must be present.
+
+The validator checks the merged result: see [Overriding theme locales](../reference/locale-keys.md#overriding-theme-locales).
+
+Arrays are replaced whole, never merged. Overriding `months` or `present_values` requires the complete list; a one-item `months` array leaves the other eleven months blank.
+
+## Change a language's font
+
+Fonts are locale data, not config, so no SCSS edit is needed for the CV pages. The profile page uses its own font stack, set in `_sass/_profile-page.scss`; see [Override Sass partials](override-sass-partials.md).
+
+1. Override `font_family` and `font_url` in your site's `_data/locales/<lang>.yml`:
+   ```yaml
+   # consuming site: _data/locales/ar.yml
+   font_family: "'Tajawal', sans-serif"
+   font_url: "https://fonts.googleapis.com/css2?family=Tajawal:wght@400;500;700&display=swap"
+   ```
+
+## Change error-page copy
+
+1. Override `error_pages` in your site's `_data/locales/<lang>.yml`. The structure is in the [data schemas reference](../reference/data-schemas.md).
+
+## Accept more "present" words
+
+1. Override `present_values` in the site's `_data/locales/<lang>.yml`. Arrays are replaced whole, so list every word you want, including the theme's:
+   ```yaml
+   # consuming site: _data/locales/es.yml
+   present_values: ["present", "actualidad", "actualmente", "presente", "hoy"]
+   ```
+2. If you change `ui.present`, also keep that label in `present_values`; see [Present values](../reference/locale-keys.md#present-values) for why.

data/docs/how-to/override-sass-partials.md

@@ -0,0 +1,26 @@
+# Override Sass partials
+
+*Audience: site owners*
+
+Change theme styles from a consuming site without forking the gem. Jekyll prioritizes files in the consuming site's directory over gem theme assets, so a file in your site's `_sass/` folder with the same name as a theme partial replaces it. The partials are listed in the [Sass reference](../reference/sass-tokens.md).
+
+## Replace a partial
+
+1. Find the theme's copy: `bundle info --path jekyll-theme-resume` prints the gem's folder; the partials are in its `_sass/` folder.
+2. Copy the complete partial into your site's `_sass/` folder under the same name (for example `_sass/_dark-mode.scss`).
+3. Edit your copy and rebuild. A same-path file replaces the whole theme partial, so keep every definition the other partials depend on.
+
+`@use "variables" with (...)` does not work as a shortcut. The partials read only `$white` and `$text_color` from `_variables.scss`, and neither is declared with `!default`, so configuring variables changes nothing. Edit a copied partial instead.
+
+## Change the accent color
+
+The accent color is a CSS custom property, defined once per color scheme in `_sass/_dark-mode.scss`. Copy that partial as described above and change `--accent-color` and `--accent-hover` in each of the four blocks that define them:
+
+1. `:root`: the light defaults.
+2. `:root:not([data-color-scheme="light"]):not([data-theme="light"])` inside `@media (prefers-color-scheme: dark)`: the dark palette that follows the visitor's system preference.
+3. `:root[data-color-scheme="dark"]` and its aliases: the dark palette when a visitor pins dark mode.
+4. `:root[data-color-scheme="light"]` and its aliases: the light palette when a visitor pins light mode.
+
+`--accent-hover-color` and `--social-hover-color` follow `--accent-hover`, so leave them alone. Printed pages reset every color to black and white, so the accent color does not print. Pick a dark-scheme color with enough contrast against the dark background; see [Accessibility decisions](../explanation/accessibility-decisions.md).
+
+To change a language's font, do not edit SCSS; see [Override locale strings](override-locale-strings.md).

data/docs/how-to/proof-built-html.md

@@ -0,0 +1,22 @@
+# Proof the built HTML and lint the Ruby
+
+*Audience: theme developers*
+
+Check a built site for dead links and missing assets, and run Ruby static analysis. To validate resume data instead, see [Validate resume data in CI](validate-in-ci.md).
+
+Two development-only Rake tasks complement the data validator. Their gems are development dependencies and are never installed for theme consumers, so run these commands from a clone of the theme repository. To proof a consuming site, build the site first, then run the task from the theme clone and point it at the site's `_site` folder.
+
+```bash
+# Dead internal links, broken #anchors, missing images/favicons, hreflang/canonical targets.
+bundle exec jekyll build --source demo --destination _site
+bundle exec rake proof                                   # proofs ./_site
+
+# Proof a consuming site (config auto-detected next to its _site/, or passed explicitly):
+bundle exec rake "proof[../my-site/_site]"
+bundle exec rake "proof[../my-site/_site,../my-site/_config.yml]"
+
+# Ruby static analysis (lib/, _plugins/, bin/validate-resume, bin/check-data-keys, test/, Rakefile):
+bundle exec rake rubocop
+```
+
+What the proofer checks and its exemptions are described in [Testing suites](../reference/testing-suites.md#built-html-proofing-semantics).

data/docs/how-to/publish-json-resume.md

@@ -0,0 +1,38 @@
+# Publish the JSON Resume export
+
+*Audience: site owners*
+
+Serve the localized JSON Resume documents the theme generates, and make sure hosts and CV pages expose them correctly. Field mappings are in the [JSON Resume fields reference](../reference/json-resume-fields.md).
+
+The routes the theme generates (`/<lang>/resume.json` for every language, plus `/resume.json` from the default language) are described in the [JSON Resume export reference](../reference/json-resume-fields.md).
+
+## 1. Check the discovery links on CV pages
+
+Build the site and open `/en/resume.json` (for example `http://localhost:4000/en/resume.json` while serving locally). Which contact details appear depends on what the CV shows: see [Visibility and privacy](../reference/json-resume-fields.md#visibility-and-privacy), and [Contact fields by privacy setting](../reference/json-resume-fields.md#contact-fields-by-privacy-setting) for a field-by-field table. To keep address, phone and email out of the JSON while the CV still shows them, set `json_resume.privacy.export_contact_info: false`; every `social_links` entry except WhatsApp is still exported. Entries in `references.yml` are exported exactly as written, so publish only what each referee agreed to make public.
+
+CV pages advertise only successfully generated localized exports:
+
+```html
+<link rel="alternate" type="application/json" href="/en/resume.json" hreflang="en">
+```
+
+The exporter records successful routes for the shared head include. Profile and error pages do not advertise exports.
+
+## 2. Serve the files as JSON
+
+Jekyll emits `.json` files; the web host must serve them with `Content-Type: application/json`. This plugin cannot set HTTP headers on a static host.
+
+## 3. Optionally enrich skills
+
+Add `level_label` and `keywords` to a `skills.yml` entry:
+
+```yaml
+# A skills.yml entry; translate content in each language's data folder.
+- skill: Web development
+  active: true
+  level: 4
+  level_label: Advanced
+  keywords:
+    - Ruby
+    - Jekyll
+```

data/docs/how-to/show-language-proficiency-in-header.md

@@ -0,0 +1,13 @@
+# Show language proficiency in the header
+
+*Audience: site owners*
+
+Show a one-line summary of the languages you speak in the resume header, instead of a full Languages section.
+
+1. In `_config.yml`, set `resume_section.lang_header: true` and `display_header_contact_info: true`. The line sits inside the header contact block, so it does not appear without the second setting.
+2. In each language's `languages.yml`, give every language you want shown `active: true` and a `descrp_short` value (for example `descrp_short: "Native"`).
+3. Rebuild. The header shows `Language (descrp_short)` entries joined by the locale's list separator, and the standalone Languages section is hidden.
+
+To show a full Languages section instead, set `resume_section.lang_header: false` and `resume_section.languages: true`.
+
+The fields of `languages.yml` are in the [data schemas reference](../reference/data-schemas.md).

data/docs/how-to/switch-resume-versions.md

@@ -0,0 +1,42 @@
+# Switch resume versions
+
+*Audience: site owners*
+
+Load a different set of resume data (for example a dated or role-specific version) for a language, without touching the data you already have.
+
+## Steps
+
+1. Put each version in its own folder under `_data/`, holding the same files as any language folder (`header.yml`, `experience.yml`, and the rest). For example:
+   ```text
+   _data/
+     en/          # your everyday English data
+     2025-06/
+       PM/        # a June 2025 product-management version
+       Eng/       # an engineering version
+   ```
+   Folder names can contain hyphens and digits. They cannot contain a dot, because a dot separates the levels of the path in the next step.
+2. Point the language's `data_path` at the folder in `_config.yml`, separating nested folders with dots:
+   ```yaml
+   languages:
+     en:
+       data_path: "2025-06.PM"    # reads _data/2025-06/PM/*.yml
+   ```
+   Only that language changes. Every other language keeps its own `data_path`.
+3. Stop the server and run `bundle exec jekyll serve` again. Changes to `_config.yml` are not picked up while the server is running.
+4. Validate the data: `bundle exec validate-resume _data`. It should print `VALIDATION SUCCESSFUL`.
+5. Open the language's CV page (for example `/en/cv/`) and confirm it shows the content of the version you chose.
+
+To go back, set `data_path` to the original folder and restart.
+
+## If it does not work
+
+- **`Data directory '.../_data/2025-06/NOPE' for language 'en' does not exist.`** The path has a typo or the folder is missing. Check each segment of the path against the folder names.
+- **The page still shows the old content.** You did not restart after editing `_config.yml`.
+- **The validator reports a file that exists for one language but not another.** Every language's data folder should hold the same files, so copy the missing file into the version folder.
+
+## Variations
+
+- `data_path: ""` reads the files placed directly in `_data/`.
+- To use a different version for each language, give each language its own `data_path`.
+
+How the path is resolved is described in [Dynamic Data Resolution](../reference/layouts.md#dynamic-data-resolution).

data/docs/how-to/troubleshoot-builds.md

@@ -0,0 +1,39 @@
+# Troubleshoot builds
+
+*Audience: site owners and theme developers*
+
+Find the symptom you see, then work through its checks.
+
+## A section is not rendering on my resume
+
+1. `resume_section.<name>: true` is set.
+2. The name is listed in `resume_section_order`.
+3. The language's data folder (`_data/<data_path>/`) contains `<name>.yml` and its items have `active: true`.
+4. For recognitions, use the plural key `recognitions`.
+5. For the languages section, `lang_header` must not be `true`.
+
+## `Missing <language> counterpart: _data/ar/xyz.yml (exists in _data/en/)`
+
+A section file exists in the reference language and not in another (or the reverse). The message names the language by its locale `ui.language_name`. Create the missing file, or delete the extra one.
+
+## `Locale es: Missing key(s) vs. 'en' locale: ...`
+
+The merged `es` locale lacks keys the reference has. For a shipped language this means a site override replaced a parent hash with a non-hash value; for a site-only language, add the listed keys.
+
+## `No locale found for 'it'` / `Data directory '_data/it' for language 'it' does not exist.`
+
+A language is declared in `languages:` (or `--languages`) but has no locale file or data folder. Add both, or remove the entry.
+
+## `languages.it has no 'data_path'`
+
+Every `languages.<lang>` entry needs `data_path`. Use `""` to point at the data root.
+
+## `Date range error: end date (2022-01-31) is before start date (2023-01-01).`
+
+Swap or correct the dates.
+
+## `url '...' must begin with http:// or https://`
+
+An error, not a warning. Add the scheme, for example `https://github.com/user`.
+
+See the [validator CLI reference](../reference/validator-cli.md) for all checks and options.

data/docs/how-to/validate-in-ci.md

@@ -0,0 +1,38 @@
+# Validate resume data in CI
+
+*Audience: site owners and theme developers*
+
+Gate builds on resume data validation and run the checks in GitHub Actions. To proof the built HTML instead, see [Proof the built HTML](proof-built-html.md). Options are listed in the [validator CLI reference](../reference/validator-cli.md).
+
+## Configure build-time validation
+
+How build-time validation behaves is described in [Jekyll Build-Time Validation](../reference/validator-cli.md#5-jekyll-build-time-validation). To opt out or gate the build on findings, set these options in `_config.yml`:
+
+```yaml
+# _config.yml
+validate_resume: false                    # opt out entirely
+validate_resume_strict: true              # abort the build when there are errors
+validate_resume_fail_on_warnings: true    # with strict: also abort on warnings
+```
+
+## Run the validator in GitHub Actions
+
+How this repository's own workflows run the validator and the template key checker: [Continuous integration](../reference/testing-suites.md#continuous-integration).
+
+A consuming site can run the same check on every push:
+
+```yaml
+# .github/workflows/validate.yml
+name: Validate Resume Data
+on: [push, pull_request]
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+      - run: bundle exec validate-resume _data --fail-on-warnings
+```

data/docs/how-to/verify-accessibility.md

@@ -0,0 +1,28 @@
+# Verify accessibility
+
+*Audience: site owners and theme developers*
+
+Run the automated checks, then complete the manual checks before claiming conformance. Coverage details are in the [accessibility coverage reference](../reference/accessibility-coverage.md).
+
+## Run the automated checks
+
+From a clone of the theme repository (these are development tasks, not part of the installed gem):
+
+```bash
+git submodule update --init --recursive
+bundle exec jekyll build --source demo --destination _site
+bundle exec rake
+bundle exec rake "proof[_site,demo/_config.yml]"
+```
+
+What the automated checks cover and exclude: [accessibility coverage](../reference/accessibility-coverage.md).
+
+## Complete the manual checklist
+
+Before claiming conformance for a deployed site:
+
+1. Check keyboard access, skip-link focus, focus visibility, and disclosure/toggle operation on profile, CV, and error pages.
+2. Inspect accessible names and reading order with a screen reader, including the extra profile email link.
+3. Test every configured locale, including Arabic and Urdu, in both light and dark modes at narrow widths and increased zoom.
+4. Measure contrast in actual rendered states and test print output for clipping and reading order.
+5. Run an accessibility scanner and manually review its results; record browser, assistive technology, date, and remaining failures.

data/docs/reference/accessibility-coverage.md

@@ -0,0 +1,39 @@
+# Accessibility coverage
+
+*Audience: site owners and theme developers*
+
+Reference for the accessibility features the theme implements and what its automated checks cover. The reasoning and limits are in [accessibility decisions](../explanation/accessibility-decisions.md); the verification steps are in [verify accessibility](../how-to/verify-accessibility.md).
+
+## Semantic Structure and Keyboard Navigation
+
+- Resume, default, and profile layouts have a skip link to `<main id="main-content" role="main" tabindex="-1">`. Error pages inherit the default layout.
+- `_sass/_base.scss` owns `.sr-only`, skip-link styles, and `:focus-visible` outlines. The skip link becomes visible on focus.
+- The focus-ring and `.sr-only` rules are in [WCAG 2.2 Accessibility & High-Contrast Standards](sass-tokens.md#wcag-22-accessibility--high-contrast-standards).
+- `_includes/language-switcher.html` uses native `<details>`/`<summary>` and a labelled `<nav>`. Enter/Space toggles the disclosure.
+
+Known limits of the header, switcher and toggle behavior are in [accessibility decisions](../explanation/accessibility-decisions.md#structure-and-keyboard-navigation).
+
+## Labels and Locale Support
+
+- Every social icon link has an accessible name (`aria-label`, `title`, hidden text) in the page's language, from `ui.social_labels`. The profile page's extra email icon is labelled the same way. The avatar uses locale-specific alt text from configuration. These are checked in [`test/test_rendered_site.rb`](../../test/test_rendered_site.rb).
+- Direction and UI strings come from six shipped locales; fonts per locale are listed in [locale keys](locale-keys.md), and the `dir="ltr"` isolation of Latin contact details is described in [multilingual and RTL design](../explanation/multilingual-and-rtl-design.md).
+- Error pages initially render the default language. Their script can change the error block and Home button based on a leading URL language prefix. The outer page and switcher remain in the server-rendered language; see [layouts.md](layouts.md#4-errorhtml-multilingual-http-error-suite).
+
+## Color Contrast
+
+The following ratios are calculated from the current colors in `_sass/_dark-mode.scss`, rounded to two decimals. They describe these specific pairs, not all rendered states.
+
+| Foreground / background | Approximate ratio | Implication |
+|---|---:|---|
+| `#333333` / `#ffffff` | 12.63:1 | Main light-mode text has strong contrast. |
+| `#e0e0e0` / `#121212` | 14.19:1 | Main dark-mode text has strong contrast. |
+| `#999999` / `#ffffff` | 2.85:1 | Current light-mode muted/footer text is below the normal-text AA threshold. |
+| `#888888` / `#121212` | 5.28:1 | Current dark-mode muted text clears the normal-text AA threshold. |
+
+Caveats for states not in this table are in [accessibility decisions](../explanation/accessibility-decisions.md#color-contrast).
+
+## Verification
+
+Commands to run the checks and the manual pre-conformance checklist are in [verify accessibility](../how-to/verify-accessibility.md).
+
+The automated checks cover data, selected template/control behavior, Ruby quality, and internal HTML links/assets. They do not perform a full accessibility audit.