jekyll-theme-resume 1.3.0

data/docs/reference/includes.md

@@ -0,0 +1,197 @@
+# Includes reference (`_includes/`)
+
+*Audience: theme developers*
+
+The theme's reusable partials in [`_includes/`](../../_includes): what each one renders and its parameters.
+
+`avatar.html`, `date-formatter.html` and `resume-section.html` resolve language from an optional `include.lang`, then `page.lang`, `site.default_lang`, or `en`; the other locale-aware includes skip `include.lang`. See [accessibility coverage](accessibility-coverage.md) for current labeling limitations. See [`layouts.md`](layouts.md#language-resolution).
+
+---
+
+## Include Map
+
+```text
+_layouts/resume.html
+ ├── data-loader.html        (binds resume_data from languages.<lang>.data_path)
+ ├── shared-head.html        (anti-FOUC script, metadata, favicon suite)
+ ├── hreflang.html           (alternate-language links)
+ ├── analytics-head.html     (GTM / GA4 head script)
+ ├── analytics-body.html     (GTM noscript iframe)
+ ├── dark-mode-toggle.html   (floating theme toggle)
+ ├── language-switcher.html  (dropdown links to the other languages)
+ ├── avatar.html             (profile image)
+ │    └── safe-url.html      (URL scheme allowlist)
+ ├── date-formatter.html     (date of birth)
+ ├── social-links.html       (header social icons)
+ │    └── safe-url.html
+ ├── resume-section.html     (one call per entry in resume_section_order)
+ │    ├── grouped-item-list.html (Experience and Volunteering)
+ │    │    └── date-formatter.html
+ │    └── date-formatter.html
+ └── print-social-links.html (print-only text list)
+```
+
+`default.html` and `profile.html` use `shared-head.html`, their own inline stylesheet `<link>` (`main.css` / `profile.css`), the analytics includes, `dark-mode-toggle.html`, and `language-switcher.html`.
+
+---
+
+## Component Inventory
+
+### 1. `shared-head.html`
+
+- **Consumed by:** every layout.
+- Charset, viewport, and `color-scheme` meta.
+- **Anti-FOUC script:** reads `localStorage['color-scheme']` synchronously and sets `data-color-scheme` / `data-theme` on `<html>` before CSS loads.
+- **Favicons:** `favicon`, `apple_touch_icon`, `favicon_32`, `favicon_16`, and the web manifest, all through `relative_url`.
+- **Robots:** `noindex noarchive nosnippet noimageindex` when `page.noindex: true`.
+
+### 2. Stylesheet links (inline in each layout)
+
+- `default.html` (therefore also error pages) links `assets/css/main.css` directly, no include.
+- `profile.html` links `assets/css/profile.css` directly, no include.
+
+### 3. `avatar.html`
+
+- **Consumed by:** `resume.html` and `profile.html` when `site.resume_avatar == true`.
+- **Parameters:** `lang` (default: active language), `link` (`false` renders a bare `<img>`), `class` (extra CSS classes).
+- **Source:** `site.avatar_url`, default `/assets/images/Profile-min.jpg` (the theme does not ship this file; supply it or set `avatar_url`). Values containing a scheme (`:`) are used as-is; others pass through `relative_url`. Only `http` and `https` are allowed; any other scheme drops the image.
+- **Alt text:** `languages.<lang>.avatar_alt`, then `languages.<lang>.name`, then `locale.ui.photo_alt`.
+- **Link:** wraps the image in a link to `site.avatar_link` (default `/`) with `site.avatar_link_target` (default `_self`), unless `site.avatar_link: false` or `link=false`. `avatar_link` may use `http`, `https`, `mailto` or `tel`; any other scheme renders the image unlinked.
+
+### 3a. `safe-url.html`
+
+- **Consumed by:** `avatar.html`, `social-links.html`, and the Mastodon `rel="me"` link in `default.html` and `profile.html`.
+- **Parameters:** `url` (value to check), `schemes` (comma-separated allowlist, e.g. `"http,https"`).
+- **Output:** sets `safe_url` to the trimmed value, or nil when it is blank or disallowed. A value containing `:` must start with an allowed scheme (case-insensitive); a value without `:` is a relative path and passes. `ResumeValidator` applies the same rule to config.
+
+```liquid
+{% include avatar.html lang=lang %}
+{% include avatar.html link=false class="avatar-large" %}
+```
+
+### 4. `dark-mode-toggle.html`
+
+- **Consumed by:** `resume.html`, `default.html`, `profile.html`.
+- Renders only when `site.dark_mode` is `"enabled"` or `true`, or front matter `dark_mode` is `true` / `"enabled"`; front matter `dark_mode: false` suppresses it.
+- Two states: unpinned (follows `prefers-color-scheme`, live via `matchMedia`) and pinned (`"dark"` / `"light"` saved to `localStorage['color-scheme']`). Clicking a pinned toggle clears the pin.
+- `aria-label` and `title` from `locale.ui.dark_mode_toggle`. Hidden in print via `.no-print`.
+
+### 5. `language-switcher.html`
+
+- **Consumed by:** `resume.html`, `default.html`, `profile.html`. Present on error pages too. Hidden when `site.resume_language_switcher: false` or front matter sets `language_switcher: false`.
+- Renders as a `<details class="language-switcher">`/`<summary class="language-switcher-trigger">` disclosure — zero JavaScript. The trigger's visible label is the current locale's `ui.language_switcher`; opening it reveals a `<nav class="language-switcher-panel">` with one link for every entry in `site.languages` except the current one, each labelled with the target locale's `ui.language_name`.
+- **Link resolution per target language:** the page in `site.pages` with the same `t_id` and the target `lang`; otherwise `languages.<lang>.url`.
+- Fixed top-left in every locale, LTR and RTL alike (the dark mode toggle is fixed top-right); positions no longer mirror by direction. Hidden in print.
+- Loop variables are prefixed `switch_`; see [Liquid pitfalls](../explanation/architecture.md#liquid-pitfalls) for why.
+
+### 6. `date-formatter.html`
+
+- **Consumed by:** `resume-section.html` (every date) and `resume.html` (date of birth).
+- **Parameters:** `date` (required), `style` (`"MY"` default: `<month> <year>`; `"MDY"`: `<month> <day>, <year>`), `lang` (default: active language).
+- A `date` matching any of the locale's `present_values` (case-insensitive) renders `locale.ui.present`.
+- Otherwise the formatter splits the ISO value itself (it does not use Liquid's `date` filter; see [Liquid pitfalls](../explanation/architecture.md#liquid-pitfalls)): `YYYY-MM-DD` renders `<month> <year>` (or `<month> <day>, <year>` with `MDY`), `YYYY-MM` renders `<month> <year>`, `YYYY` renders the year, and anything else is printed as written. YAML date objects behave like `YYYY-MM-DD`.
+- Tested in [`test/test_rendered_site.rb`](../../test/test_rendered_site.rb).
+
+```liquid
+{% include date-formatter.html date=role.startdate %}
+{% include date-formatter.html date=site.contact_info.dob style="MDY" lang=lang %}
+```
+
+
+### 7. `social-links.html`
+
+- **Consumed by:** `resume.html` and `profile.html`, inside `<ul class="social-links">`, when `site.social_links` is set.
+- `email` renders a `mailto:` link with `itemprop="email"`. The other 14 platforms (`github`, `linkedin`, `telegram`, `twitter`, `medium`, `dribbble`, `facebook`, `instagram`, `website`, `whatsapp`, `devto`, `flickr`, `pinterest`, `youtube`) open in a new tab with `rel="noopener nofollow noreferrer"`.
+- Every icon link carries `aria-label`, `title`, and a `.sr-only` text span, all taken from the page locale's `ui.social_labels.<key>` (falling back to the English `label` in `_data/social_networks.yml`).
+- `profile.html` adds one extra email icon for `contact_info.email` only when `social_links.email` is not set, so the profile never shows two email icons.
+
+### 8. `print-social-links.html`
+
+- **Consumed by:** `resume.html` print-only section when `site.resume_print_social_links` is set.
+- One line per configured platform (including `email`), labelled from `locale.ui.social_labels`, with the value wrapped in `<span dir="ltr">`.
+
+### 9. `hreflang.html`
+
+- **Consumed by:** `resume.html` and `profile.html` heads.
+- Runs only when the page has a `t_id`. Emits `<link rel="alternate" hreflang="<lang>">` for every page sharing that `t_id`, and `hreflang="x-default"` for the one whose `lang` is `site.default_lang`. URLs are absolute (`absolute_url`), so `site.url` must be set.
+
+### 10. `data-loader.html`
+
+- **Consumed by:** `resume.html`.
+- **Parameter:** `path`, a dot-separated data path. Default: `site.languages[page.lang or default_lang].data_path`.
+- Sets `resume_data` in the caller's scope by walking `site.data` with bracket access. Details in [`layouts.md`](layouts.md#dynamic-data-resolution).
+
+### 11. `analytics-head.html` & `analytics-body.html`
+
+- **Head:** Google Tag Manager (`site.analytics.gtm`) or Google Analytics 4 (`site.analytics.gtag`). Universal Analytics (`analytics.ga`) is retired; use `analytics.gtag` for GA4.
+- **Body:** the GTM `<noscript><iframe>` right after `<body>` in every layout.
+
+### 12. `vendors/` (SVG Icons)
+
+- `vendors/svg-icons/`: one flat folder of Lineicons SVGs (MIT-licensed; see `ATTRIBUTION.md` inside it, packaged with the gem but not built into a consuming site's output) — contact row icons (`envelope`, `phone`, `postcard`) plus every social platform icon listed in [`_data/social_networks.yml`](../../_data/social_networks.yml).
+
+---
+
+## Multilingual SEO with hreflang
+
+When translations of a page share a `t_id` (see [Add a language](../how-to/add-a-language.md)) and `default_lang: en`, each page emits:
+
+```html
+<link rel="alternate" hreflang="en" href="https://your-domain.com/en/cv/" />
+<link rel="alternate" hreflang="ar" href="https://your-domain.com/ar/cv/" />
+<link rel="alternate" hreflang="x-default" href="https://your-domain.com/en/cv/" />
+```
+
+The same `t_id` also lets the language switcher find the exact counterpart page instead of falling back to `languages.<lang>.url`.
+
+---
+
+## Section Dispatcher (`resume-section.html`)
+
+`resume.html` renders sections by looping over `site.resume_section_order`:
+
+```liquid
+{%- for section_name in site.resume_section_order -%}
+  {% include resume-section.html section_name=section_name lang=lang %}
+{%- endfor -%}
+```
+
+[`_includes/resume-section.html`](../../_includes/resume-section.html) is one `{% if %} / {% elsif %}` chain. A branch renders when `include.section_name` matches and `site.resume_section.<name>` is truthy:
+
+```liquid
+{% if include.section_name == "experience" and site.resume_section.experience %}
+  <!-- Experience -->
+{% elsif include.section_name == "education" and site.resume_section.education %}
+  <!-- Education -->
+...
+```
+
+Inside every branch:
+
+- The heading is `locale.ui.section_titles.<name>`.
+- Dates go through `date-formatter.html`; a blank `enddate` renders as the locale's "Present" in Experience and Volunteering (courses omit the end date).
+- When `locale.direction == 'rtl'`, URLs and credential IDs are wrapped in `dir="ltr"`.
+- Only items with `active: true` render; an item without the flag is hidden (`interests.yml` has no flag).
+
+### Section Dispatch Inventory
+
+| `section_name` | Config toggle (`resume_section`) | Data file | Data expression |
+|---|---|---|---|
+| `experience` | `experience` | `experience.yml` | `resume_data.experience` |
+| `education` | `education` | `education.yml` | `resume_data.education` |
+| `certifications` | `certifications` | `certifications.yml` | `resume_data.certifications` |
+| `courses` | `courses` | `courses.yml` | `resume_data.courses` |
+| `volunteering` | `volunteering` | `volunteering.yml` | `resume_data.volunteering` |
+| `projects` | `projects` | `projects.yml` | `resume_data.projects` |
+| `skills` | `skills` | `skills.yml` | `resume_data.skills` |
+| `recognitions` | `recognitions` | `recognitions.yml` | `resume_data.recognitions` |
+| `associations` | `associations` | `associations.yml` | `resume_data.associations` |
+| `interests` | `interests` | `interests.yml` | `resume_data.interests` |
+| `languages` | `languages` (and `lang_header` not `true`) | `languages.yml` | `resume_data.languages` |
+| `links` | `links` | `links.yml` | `resume_data.links` |
+
+### Shared Grouped Items (`grouped-item-list.html`)
+
+Experience and Volunteering both call this include with `items` and `lang`. It filters `active: true`, groups by `company`, and sorts roles within each group by `startdate` descending. Explicit `durations[].duration` strings take precedence over formatted start/end dates. Summaries require `enable_summary: true`.
+
+To add a section, see [Add a resume section](../how-to/add-a-section.md).

data/docs/reference/json-resume-fields.md

@@ -0,0 +1,148 @@
+# JSON Resume export reference
+
+*Audience: site owners*
+
+Reference for the localized JSON Resume export: configuration, visibility, field mappings, normalization, and standard conformance.
+
+The theme generates one JSON Resume document per configured language at
+`/<lang>/resume.json`. It also generates `/resume.json` from the default language.
+These are static build outputs, prefixed by `baseurl` when served. Existing YAML
+keys and HTML layouts continue working without migration.
+
+## Configuration
+
+Exports are enabled by default. The `json_resume` and `social_usernames` settings, their defaults, and the language allowlist rules are in [JSON Resume export](config.md#13-json-resume-export) in the configuration reference.
+
+The root copy is generated only if the default language is allowed and its
+localized export succeeds. A collision with an authored page, static file,
+collection document, or existing generated page preserves that resource and logs
+a warning. A collision at the localized route also suppresses its root copy.
+A root-only collision does not suppress the localized export.
+
+Discovery links on CV pages and the `application/json` hosting requirement are covered in [Publish the JSON Resume export](../how-to/publish-json-resume.md).
+
+## Visibility and privacy
+
+- Data comes from `languages.<lang>.data_path`, including nested dot paths and an
+  empty path for root data.
+- Sections must be enabled and present in `resume_section_order`. Entries require
+  exactly `active: true`, except interests, whose HTML list has no active filter.
+- Header languages follow `display_header_contact_info` and `resume_section.lang_header`.
+  Section languages follow the existing section-placement rules.
+- The biography is `header.intro` only when `header_intro: true`; profile `about`
+  content is not used as a fallback. Work and volunteer summaries require
+  `enable_summary: true`. The avatar requires `resume_avatar: true` and uses the
+  same default image as the CV.
+- Email is exported when the contact bar or contact-me CTA is visible. Phone and
+  location are exported only when the contact bar is visible. `enable_live: true`
+  selects each live contact value independently, falling back to its base value
+  when the live key is absent or false.
+- `json_resume.privacy.export_contact_info: false` omits email, phone, the entire location object, and
+  WhatsApp profiles. `social_links.email` is never exported as a social profile.
+  This setting does not redact free-form narrative text, usernames, or arbitrary
+  URLs, and it does not change the HTML site's contact visibility.
+
+### Contact fields by privacy setting
+
+Two settings decide what personal data leaves in `resume.json`: `display_header_contact_info` (and `resume_looking_for_work`) in `_config.yml`, and `json_resume.privacy.export_contact_info`. Each cell says whether the field is exported.
+
+| Field in `resume.json` | Source | Default export | `display_header_contact_info: false` | `export_contact_info: false` |
+|---|---|---|---|---|
+| `basics.phone` | `contact_info.phone` (or `phone_live`) | Only when `display_header_contact_info: true` | Omitted | Omitted |
+| `basics.email` | `contact_info.email` (or `email_live`) | When `display_header_contact_info: true` **or** `resume_looking_for_work: true` | Omitted unless `resume_looking_for_work: true` | Omitted |
+| `basics.location.address`, `postalCode`, `city`, `region`, `countryCode` | `languages.<lang>.address`, `postal_code`, `city`, `region`, `country_code` | Only when `display_header_contact_info: true` | Whole `location` object omitted | Whole `location` object omitted |
+| `basics.profiles[]` for `whatsapp` | `social_links.whatsapp` | Exported when configured | Exported | **Omitted** |
+| `basics.profiles[]` for every other network | `social_links.<network>` | Exported when configured | Exported | **Still exported** (including `telegram`, `website`, `twitter`) |
+| `basics.profiles[].username` | `social_usernames.<network>` | Exported with its profile | Exported with its profile | Exported with its profile |
+| `contact_info.dob` | `contact_info.dob` | Never exported | Never exported | Never exported |
+
+Things to know before publishing:
+
+- A postal address is exported whenever the CV header shows contact details, even if you only meant to show it on the page. Set `export_contact_info: false` to keep address, phone and email out of the JSON.
+- `export_contact_info: false` does not touch the HTML. The CV still shows whatever `display_header_contact_info` shows.
+- Only WhatsApp is treated as a contact channel. Any other `social_links` entry (for example a Telegram handle) is public in the JSON unless you remove it from `social_links`.
+- Free-form text (summaries, references, highlights) is exported as written. The setting does not redact it.
+
+The export is a supported subset of the CV, not a lossless representation; see [the data-driven model](../explanation/data-driven-model.md).
+
+## Field mappings
+
+All field names below on the left are existing YAML names or optional additions;
+camelCase names on the right belong only to the JSON output.
+
+| Source | JSON Resume target |
+|---|---|
+| `languages.<lang>.name`, `resume_title` | `basics.name`, `basics.label` |
+| `avatar_url` or theme fallback | `basics.image` |
+| Selected `contact_info.email`, `phone` | `basics.email`, `basics.phone` |
+| Actual CV page URL, falling back to `languages.<lang>.url` | `basics.url`, `meta.canonical` |
+| `header.intro` | `basics.summary` |
+| Per-language `address`, `postal_code`, `city`, `country_code`, `region` | `basics.location.address`, `postalCode`, `city`, `countryCode`, `region` |
+| Supported `social_links.<network>` and `social_usernames.<network>` | `basics.profiles[].network`, `url`, `username` |
+| `experience.company`, `position`, `location`, `summary`, `url`, `highlights` | `work[].name`, `position`, `location`, `summary`, `url`, `highlights` |
+| `volunteering.company`, `position`, `summary`, `url`, `highlights` | `volunteer[].organization`, `position`, `summary`, `url`, `highlights` |
+| `education.uni`, `degree` (fallback `study_type`), `area`, `score` (fallback `gpa`), `courses`, `url` | `education[].institution`, `studyType`, `area`, `score`, `courses`, `url` |
+| Work, volunteer, education, project `startdate`, `enddate` | Corresponding `startDate`, `endDate` |
+| `certifications.name`, `issuing_organization`, `issue_date`, `credential_url` | `certificates[].name`, `issuer`, `date`, `url` |
+| `recognitions.award` (fallback `title`, `recognition`), `organization`, `summary`, `date` | `awards[].title`, `awarder`, `summary`, `date` |
+| Four-digit recognition `year`, when `date` is absent | `awards[].date` |
+| `skills.skill`, `level_label`, `keywords` | `skills[].name`, `level`, `keywords` |
+| `languages.language`, displayed `descrp_short` (header) or `description` (section) | `languages[].language`, `fluency` |
+| `interests.name` (fallback `description`), `keywords` | `interests[].name`, `keywords` |
+| `projects.project`, `description`, `url`, `highlights`, `keywords` | `projects[].name`, `description`, `url`, `highlights`, `keywords` |
+| Project `roles`, or scalar `role` wrapped in an array | `projects[].roles` |
+| `publications.name`, `publisher`, `release_date`, `url`, `summary` | `publications[].name`, `publisher`, `releaseDate`, `url`, `summary` |
+| `references.name`, `reference` | `references[].name`, `reference` |
+
+Experience and volunteering remain one record per role; company groups and
+newest-first role ordering follow the HTML renderer. Supported social networks
+are the ones rendered by the existing social include: GitHub, LinkedIn,
+Telegram, Twitter, Medium, Dribbble, Facebook, Instagram, Website, WhatsApp,
+Dev.to, Flickr, Pinterest, and YouTube. Their configured keys identify networks
+in the export. Social URLs remain strings; nested `{url, username}` objects are
+not introduced by this feature.
+
+## Optional enrichment
+
+The optional per-section fields that enrich the export are listed in [JSON Resume enrichment](data-schemas.md#json-resume-enrichment). A `skills.yml` example is in [Publish the JSON Resume export](../how-to/publish-json-resume.md#3-optionally-enrich-skills).
+
+## Dates, text, and URLs
+
+Dates must be real calendar dates in `YYYY`, `YYYY-MM`, or `YYYY-MM-DD` form.
+**Certificate `issue_date` is the exception:** the pinned schema requires a full
+`YYYY-MM-DD`. A partial certificate date remains valid website data but is
+omitted from JSON with a warning; the exporter never guesses a month or day.
+
+Blank end dates, `Present` (case-insensitive), and the effective locale's
+`present_values` omit `endDate` silently. Free-form `duration`, `durations`, and
+education `year` are not parsed into dates. Date of birth is not exported.
+
+Raw HTML tags are removed, block boundaries preserved as newlines, and HTML
+entities decoded to Unicode. Markdown and native multilingual characters remain.
+Liquid-like text is serialized literally; generated JSON bypasses Liquid and
+layouts during Jekyll rendering.
+
+Links must resolve to absolute HTTP(S) URLs. Local paths use `site.url` and
+`site.baseurl`; without `site.url`, relative links are omitted with a warning.
+Social profile URLs must already be absolute. Invalid email addresses, country
+codes, dates, and URLs are omitted with contextual warnings that do not print
+field values. Empty fields, arrays, objects, and sections are omitted.
+
+## Standard and omissions
+
+Validation uses the vendored [JSON Resume 1.0.0 schema](https://raw.githubusercontent.com/jsonresume/resume-schema/v1.0.0/schema.json)
+(Draft 4) through `json_schemer`. Builds perform no schema downloads. `$schema`
+points to this pinned version; `meta.version` is `1.0.0`, and `meta.lastModified`
+is the build timestamp in UTC. Schema validation is distinct from source YAML validation. If final schema validation unexpectedly fails,
+the document is skipped and no discovery link is emitted.
+
+Associations, standalone courses, generic links, date of birth, skill narrative
+descriptions, education honors/summaries, certificate IDs/expiration, and
+free-form display date ranges have no mapping in this exporter. Publications and
+references export exactly as authored, with no extra fields; a publication's `summary` is exported regardless of `enable_summary`. References are
+public once exported, so include only what each referee agreed to publish. Nested certificate courses
+remain internal data and are not exported.
+
+## Verification
+
+Test coverage for the export is described in [JSON Resume export coverage](testing-suites.md#json-resume-export-coverage).

data/docs/reference/layouts.md

@@ -0,0 +1,144 @@
+# Layouts reference (`_layouts/`)
+
+*Audience: site owners and theme developers*
+
+The theme's layouts in [`_layouts/`](../../_layouts): what each one renders, how the resume layout resolves its language and data, and where a custom layout fits. To build one, see [Create a custom layout](../how-to/create-a-custom-layout.md).
+
+---
+
+## Overview & Layout Hierarchy
+
+Hand-authored pages select a layout in front matter. The theme also generates missing CV/profile pages; see [page configuration](config.md#3-languages). A resume page is `layout: resume` plus `lang: <code>`; there is no per-language layout.
+
+```text
+_layouts/default.html   (base shell: <head>, anti-FOUC, dark mode, footer)
+ └── _layouts/error.html  (HTTP 404, 403, 500, 503)
+
+_layouts/profile.html   (standalone landing page)
+_layouts/resume.html    (standalone resume, one layout for every language and direction)
+```
+
+---
+
+## Language Resolution
+
+The common language-resolution pattern is shown below. Some includes accept `include.lang`; the default/profile layouts also fall back to the English locale if neither the page nor default locale exists:
+
+```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] %}
+```
+
+- `locale` is the merged locale file `_data/locales/<lang>.yml` (theme file with any site override on top). It supplies `direction`, fonts, line height, UI strings, month names, and error copy.
+- `lang_cfg` is the `languages.<lang>` config block. It supplies `data_path`, `url`, `header_intro`, `name`, `resume_title`, `address`, and `avatar_alt`.
+
+The active language resolves in this order: `page.lang`, then `site.default_lang`, then `en`. The repository's own demo pages are in [`demo/`](../../demo/). English and Arabic CVs are hand-authored there; Spanish, French, German, and Urdu CVs are generated.
+
+The locale schema is in [Locale keys](locale-keys.md); the `languages` schema is in [Configuration reference](config.md#3-languages).
+
+---
+
+## Layout Inventory
+
+### 1. `default.html` (Base Layout)
+
+- **File:** [`_layouts/default.html`](../../_layouts/default.html)
+- **Role:** Shell for markdown pages and error pages.
+- `<html lang="{{ lang }}" dir="{{ locale.direction }}">`, skip link text from `locale.ui.skip_to_content`.
+- Includes [`shared-head.html`](../../_includes/shared-head.html), a stylesheet link to `assets/css/main.css`, `{% seo %}`, and the analytics includes.
+- Emits `<link rel="me">` when `site.social_links.mastodon` is set.
+- Includes [`dark-mode-toggle.html`](../../_includes/dark-mode-toggle.html) and [`language-switcher.html`](../../_includes/language-switcher.html) (also present on error pages unless disabled by site/page settings), and wraps content in `<main class="main-content" id="main-content">`.
+
+### 2. `profile.html` (Portfolio Landing)
+
+- **File:** [`_layouts/profile.html`](../../_layouts/profile.html)
+- **Role:** Standalone landing page, independent of `default.html` so its centering styles do not leak.
+- Same `lang` / `dir` resolution, skip link, dark mode toggle, and language switcher as `default.html`.
+- Uses `languages.<lang>.name`, optional `name_html`, and `about` for its header; the CV button points to `languages.<lang>.url`. Calls `hreflang.html` for translated profile pages sharing `t_id: profile`.
+- Social icons come from [`social-links.html`](../../_includes/social-links.html). When `social_links` is set, `contact_info.email` is set, and `social_links.email` is not, one extra labelled email icon is added.
+- Stylesheet [`assets/css/profile.scss`](../../assets/css/profile.scss) (compiled to `assets/css/profile.css`, linked directly in the layout's `<head>`), styled by [`_sass/_profile-page.scss`](../../_sass/_profile-page.scss).
+
+### 3. `resume.html` (Resume, Every Language)
+
+- **File:** [`_layouts/resume.html`](../../_layouts/resume.html)
+- **Role:** The resume for any configured language, LTR or RTL.
+- **Head:**
+  - `<html lang="{{ lang }}" dir="{{ locale.direction }}">`.
+  - Loads `locale.font_url` when set, else the default Lora and Open Sans stylesheet; neither loads when `disable_google_fonts: true` or `resume_theme: no-custom-fonts`.
+  - Emits `--font-locale` (from `locale.font_family`, when non-empty) and `--line-height-locale` (from `locale.line_height`) in an inline `:root` style.
+  - Links `assets/css/cv-{{ locale.direction }}.css`, so LTR locales get `cv-ltr.css` and RTL locales get `cv-rtl.css`.
+  - Includes [`hreflang.html`](../../_includes/hreflang.html), `{% seo %}`, and the analytics head include.
+- **Header:** avatar (when `resume_avatar: true`), `lang_cfg.name`, the contact row (when `display_header_contact_info: true`), the header language list (when `display_header_contact_info: true` and `resume_section.lang_header` is set), `lang_cfg.resume_title`, social icons (when `social_links` is set), the `header.yml` intro (when `lang_cfg.header_intro: true`), and the contact button (per `resume_looking_for_work`).
+- **Contact row:** icon first, then text, in every direction. Phone numbers and emails carry `dir="ltr"`. The date of birth goes through [`date-formatter.html`](../../_includes/date-formatter.html).
+- **Body:** loops `site.resume_section_order` through [`resume-section.html`](../../_includes/resume-section.html), then the print-only social links section when `resume_print_social_links` is set.
+- **Footer:** localized "last generated" line and, when `enable_live == false`, a print-only footer with the page's permalink.
+
+### 4. `error.html` (Multilingual HTTP Error Suite)
+
+- **File:** [`_layouts/error.html`](../../_layouts/error.html), extends `default.html`. Used by `404.html`, `403.html`, and `500.html`.
+- Reads `page.code` (default `"404"`) and server-renders a single heading/message block in `default_lang`.
+- On `DOMContentLoaded`, the inline script removes `site.baseurl` from the start of `window.location.pathname`, then checks whether the rest begins with a configured `/<lang>/` prefix (so `/portfolio/ar/missing` on a `baseurl: /portfolio` site shows Arabic). It updates the block’s text, `lang`, and `dir`, plus the Home button’s label and destination. It does not use browser language or a stored preference.
+- With JavaScript disabled, or without a matching prefix, the default-language content remains. The script changes the error block, not the outer page’s language or switcher label.
+- The single Home link prefers the selected language’s `layout: profile` page, then `languages.<lang>.url`, then `/`. Reload is shown for `500`, `503`, or `page.show_reload: true`; its label remains in the default locale.
+- There is no search form or per-language return-link list in the current error layout. Search is not currently supported.
+- [`_plugins/error_pages_generator.rb`](../../_plugins/error_pages_generator.rb) creates missing `404.html`, `403.html`, and `500.html`. A manual `layout: error`, `code: 503` page is supported but is not generated automatically. Load the theme through the Gemfile’s `:jekyll_plugins` group or the config’s `plugins:` list.
+
+---
+
+## Dynamic Data Resolution
+
+`resume.html` calls [`_includes/data-loader.html`](../../_includes/data-loader.html) with `path=lang_cfg.data_path`. The include binds `resume_data` by walking `site.data` one dot-separated segment at a time:
+
+```liquid
+{%- assign resume_data = site.data -%}
+{%- if data_path.size > 0 -%}
+  {%- assign path_parts = data_path | split: '.' -%}
+  {%- for part in path_parts -%}
+    {%- assign resume_data = resume_data[part] -%}
+  {%- endfor -%}
+{%- endif -%}
+```
+
+See [data-driven model](../explanation/data-driven-model.md) for why presence checks avoid `!= blank` and why bracket access is used.
+
+```yaml
+languages:
+  en:
+    data_path: en              # site.data.en
+  ar:
+    data_path: "2025-06.v1-ar" # site.data["2025-06"]["v1-ar"]
+  es:
+    data_path: ""              # site.data (files directly in _data/)
+```
+
+When called without `path`, the include falls back to `site.languages[page.lang or default_lang].data_path`.
+
+---
+
+## Resume Rendering Pipeline
+
+The order of operations for one resume page:
+
+```text
+1. Resolve lang, locale, lang_cfg; load resume_data from lang_cfg.data_path
+2. <head>: shared-head, locale font + CSS variables, cv-<direction>.css, hreflang, SEO, analytics
+3. Body start: analytics-body, dark-mode-toggle, language-switcher
+4. Header: avatar, name, contact row, header languages, title, social icons, intro, contact button
+5. Sections: for each name in site.resume_section_order
+     {% include resume-section.html section_name=section_name lang=lang %}
+6. Print-only social links (print-social-links.html)
+7. Footer and print-only permalink footer
+```
+
+---
+
+## Dark Mode & Anti-FOUC Mechanics
+
+Layouts include [`dark-mode-toggle.html`](../../_includes/dark-mode-toggle.html). To configure it, see [Enable dark mode](../how-to/enable-dark-mode.md); for the anti-FOUC script and the two activation tiers, see [dark mode approach](../explanation/dark-mode-approach.md).
+
+---
+
+## Creating Custom Layouts
+
+See [Create a custom layout](../how-to/create-a-custom-layout.md).

data/docs/reference/locale-keys.md

@@ -0,0 +1,76 @@
+# Locale Keys
+
+*Audience: site owners and theme developers*
+
+Reference for the locale file schema (`_data/locales/<lang>.yml`), the shipped locales, and the rules that govern overriding them.
+
+## Shipped locales
+
+The theme ships six locales: English (`en`, LTR), Arabic (`ar`, RTL), Spanish (`es`, LTR), French (`fr`, LTR), German (`de`, LTR), and Urdu (`ur`, RTL). Any other language is added by the site alone, with no Ruby, HTML, or SCSS changes.
+
+Shipped fonts and line heights:
+
+| Locale | `direction` | `font_family` | `line_height` |
+|---|---|---|---|
+| `en`, `es`, `fr`, `de` | `ltr` | empty (theme default stacks) | 1.5 |
+| `ar` | `rtl` | `'Cairo', sans-serif` | 1.6 |
+| `ur` | `rtl` | `'Noto Nastaliq Urdu', serif` | 2.0 |
+
+## Locale file keys
+
+Every locale file has the same key set. The validator warns when a language's effective locale is missing a key that the reference locale (`en` by default) has.
+
+| Key | Purpose |
+|---|---|
+| `direction` | `ltr` or `rtl`. Sets `<html dir>` and selects `assets/css/cv-ltr.css` or `cv-rtl.css`. |
+| `font_family` | CSS font stack emitted as `--font-locale`. Empty string keeps the theme's default stacks (Lora and Open Sans). |
+| `font_url` | Stylesheet URL for the font (usually Google Fonts). Empty string loads the default Lora and Open Sans stylesheet. |
+| `line_height` | Emitted as `--line-height-locale` for resume body text. |
+| `ui.*` | Every UI string the templates render: skip link, "Present", contact button, dark mode toggle label, language switcher label, `language_name` (the language's own name, shown in the switcher and on error page return links), `list_separator`, and more. |
+| `ui.section_titles.*` | One heading per resume section (`experience`, `education`, ... `links`, `publications`, `references`). |
+| `ui.social_labels.*` | Platform names: the accessible name (`aria-label`, `title`, screen-reader text) of each social icon and the labels of the print-only contact list. |
+| `error_pages."404"` / `"403"` / `"500"` / `"503"` | `title` and `message` for each HTTP error page. |
+| `present_values` | Case-insensitive words that mean "ongoing" in `enddate` fields. A match renders `ui.present` instead of a date. |
+| `months` | The 12 month names, January first. Dates render as `<month> <year>`; a year-only date renders as the year. |
+
+Read the shipped files in [`../../_data/locales/`](../../_data/locales/) for the full key list and current values.
+
+## `error_pages`
+
+Error page text is not in the data folders. Each locale file carries an `error_pages` map, and [`../../_layouts/error.html`](../../_layouts/error.html) server-renders one block in `default_lang`. JavaScript can replace that block using a configured language prefix at the start of the requested URL:
+
+```yaml
+# _data/locales/en.yml (excerpt)
+error_pages:
+  "404":
+    title: "Page Not Found"
+    message: "The page you are looking for might have been removed, had its name changed, or is temporarily unavailable."
+  "403": { title: "...", message: "..." }
+  "500": { title: "...", message: "..." }
+  "503": { title: "...", message: "..." }
+```
+
+## "Present" values
+
+An `enddate` may be a word meaning "ongoing" instead of a date. For a given language the accepted words are that language's effective locale `present_values` plus its `ui.present` label, compared case-insensitively. A language with no locale falls back to the `default_lang` locale. The shipped values:
+
+| Language | `present_values` | `ui.present` |
+|---|---|---|
+| `en` | `present`, `current` | `Present` |
+| `ar` | `present`, `حتى الآن`, `حاليًا` | `حتى الآن` |
+
+Read the other four in [`_data/locales/`](../../_data/locales). To accept more words, see [Override locale strings](../how-to/override-locale-strings.md#accept-more-present-words).
+
+The template side ([`_includes/date-formatter.html`](../../_includes/date-formatter.html)) matches `present_values`. If you change `ui.present`, include that label in `present_values` too: the validator accepts the label automatically, but the formatter checks only the list.
+
+## Overriding theme locales
+
+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.
+
+- **Nested keys merge one by one.** A site file `_data/locales/<lang>.yml` containing only some keys changes those keys and leaves every other string intact.
+- **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.
+- **A new language has no theme file to merge with,** so its `_data/locales/<lang>.yml` must contain every key.
+
+The validator builds each locale the same way (theme file, then site file deep-merged over it) and checks key parity on the merged result. A one-line override produces no warnings; an incomplete site-only locale does.
+
+Task steps: [override locale strings](../how-to/override-locale-strings.md), [add a language](../how-to/add-a-language.md). Design background: [multilingual and RTL design](../explanation/multilingual-and-rtl-design.md).