bilingual-jekyll-resume-theme 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2f374813b4f778e031ea8979e3f995f8fd800e511c65418a88fc524ca8db793
-  data.tar.gz: dddb715d231b8795b4dad38fe31c5ee066400460913768bd602440e4a7c5e0ad
+  metadata.gz: 0456f04d40f87607d0b9eea63b2fabbf1256e5ca0a7e6903ac1cd4fbb8465575
+  data.tar.gz: 840d1d5addfdf72448dfd04765875ceed5c319ba8d3548b26ec89f1d82c34ec2
 SHA512:
-  metadata.gz: b8551515a7d57937c754ec17ec2f5dbc1d44eb2645aa1a449210f4004a17bc3f6a4595abd5a186a483a3e5399a3786cf4c8594ad9260bb4f7084051bcb265dba
-  data.tar.gz: 368308d395c16d9cab00ccfe36a1e2c8c18118d2727b0a7d8d668ed659b3d71a001f1c0da8ec41c83b3cb8701dc19f282275c3f1248949653f67043b003d02db
+  metadata.gz: 570f411c947a9cb26c2806580405b3503fcd5d4d513dc083dce5dec2c1930cd37c241a289ca4526bb5d2282e0efb79659302b9a4b9018b88413e0057a8432aa7
+  data.tar.gz: e1d7b2184bdf67432c8edf765a18404c1590eae81b8e827da894aeee2e085843b3d37d3fffadf259e461d3d3f2e5bd8c5066fcb88e15cdca700b36a3187d72ed

data/CHANGELOG.md

@@ -4,6 +4,78 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.9.0] - 2026-09-21
+
+### Added
+* Add accessible landmark roles, skip-links, and focus styles ([`a29c480`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/a29c48087c3933c9edb71722bbb00ea12e3c9ad4))
+
+
+### Changed
+* Update active feature blueprints, issue mappings, and ignore rules ([`28dd0c3`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/28dd0c317cc869f966731c1732570b7592affb3e))
+
+* Consolidate dynamic data loader into shared include component ([`ef5cc4f`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/ef5cc4fa1e979024a0fbc8efebef5105706aa1df))
+
+* Consolidate profile styles with shared partials and remove redundant forwarder ([`0d1fbd0`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/0d1fbd04b427c4ee334d64558d6275ec64f71e9c))
+
+* Simplify resume section conditions with direct Liquid blank checks ([`c9a6ada`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/c9a6ada2089b9b686d510edfffe0d196dca5f051))
+
+* Clean up legacy mixins, remove IE zoom hacks, and eliminate dead table classes ([`2800d0a`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/2800d0ab1553ee14e59c6eaae441d4de83c5b35f))
+
+* Encapsulate dark mode activation cascade into toggle include ([`405b493`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/405b4933ea0640951fd8a24a21151574bb0ab11a))
+
+* Implement interactive bilingual language switcher ([`c56e50f`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/c56e50fa6f7e64a58ff7930a3bfb4a7275b7e134))
+
+* Apply living-docs framework, add code comments, browser QA verified ([`d1535b9`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/d1535b9f22d79eab1cd7f4078c0db2d86a74f7b6))
+
+* Update release notes for version automation ([`fc9ead1`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/fc9ead129df08b3698264b9da5a07378e1543aa3))
+
+* Preserve bump-only releases in git-cliff template ([`ba334a5`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/ba334a54fa8d63aeea1a72ad646b2bb71ff6f0a7))
+
+* Automate gem publishing and release workflow ([`f4bd096`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/f4bd096ae44bfc42cb14c9635a0e9803e297a0ba))
+
+
+### Fixed
+* Render language header summary on a dedicated line ([`d3352dc`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/d3352dcb6833f8bc48d2d799774757a42325a711))
+
+
+### Removed
+* Remove redundant Gem::Specification monkey-patch ([`a78efd6`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/a78efd68e70c0848f78bb5b25ab51f848c437c1d))
+
+## [0.8.0] - 2026-09-19
+
+### Added
+* Add global .sr-only utility class for accessible icons ([`f25fcb6`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/f25fcb618c399a54039b00cb56e1d09724592516))
+
+* Add error pages generator plugin and gem autoloading ([`9238b5a`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/9238b5ace273c9c64de5c90bbd8a19fe6ac5a27b))
+
+* Add .agents/ to ignore list ([`568b874`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/568b874c290ae1673fe6c3e44b97a4c0c8e0b553))
+
+* Add configurable avatar URL, bilingual alt text, and reusable include ([`a17cc60`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/a17cc603a3633bb5dc67589bcc01ce7ef886d88c))
+
+
+### Changed
+* Improve accessibility, icon contrast, mobile responsiveness, and RTL typography ([`add2625`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/add2625599027eb1f88ca6e1ec66c3bf2b334757))
+
+* Populate comprehensive bilingual example data across all sections ([`1555d41`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/1555d41efef50cd9010d4bf08223fb81060bc8f3))
+
+* Standardize recognition section toggle to plural with fallback ([`dccee09`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/dccee09c65e95a140281633342a09d58b236b888))
+
+* Modernize all guides and master sample configuration ([`08f8823`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/08f8823f91984891e55dff0dcc8488601c185aea))
+
+* Establish master feature roadmap and archive completed audit ([`f6d28a3`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/f6d28a354115fa6a0ce5e29250cd1b40be0c4dfd))
+
+* Establish AGENTS.md master manual and refactor pointers ([`24ecf7e`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/24ecf7e751eebff79ac9e805d7a7de8696c52b43))
+
+
+### Fixed
+* Render section detail bullets conditionally with proper spacing ([`e4564cc`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/e4564cc43b5e5cec31ed704918cddbc124ec76ca))
+
+* Enhance error layout usability, add sr-only styles, and maintain LTR/RTL parity ([`18a9b5b`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/18a9b5bbd18c52456a5a0dfd958d09187686a003))
+
+* Restore standalone profile layout and eliminate icon underline artifacts ([`5bed5dd`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/5bed5ddc9b59bbfcb820df7793c2098ee0762d69))
+
+* Resolve Liquid truthiness, unclosed tags, and Arabic date parsing ([`90a0750`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/90a075077c812bc56d31ac9622abdf2f3278dc98))
+
 ## [0.7.0] - 2026-09-12
 
 ### Added
@@ -38,8 +110,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.6.1] - 2026-08-21
 
 ### Changed
-* Version bump since v0.6.0 gemspec had incorrect version number and release was pushed to RubyGems incorrectly and it was yanked; re-releasing under v0.6.1.
-
+* Version bump release with no structural code changes.
 ## [0.6.0] - 2026-08-21
 
 ### Added
@@ -194,6 +265,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Initial commit (New Theme Template) ([`00af662`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/00af6628dfec7aefe0ef7d7083bf98c9713a5ffd))
 
+[0.9.0]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.6.1...v0.7.0
+[0.6.1]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.5.2...v0.6.0
 [0.5.2]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.5.0...v0.5.1

data/README.md

@@ -80,14 +80,22 @@ Understanding the theme's include system, how sections render, and how to add ne
 ### 🎨 [SASS/SCSS Guide](docs/SASS_GUIDE.md)
 Complete guide to the theme's styling system, how to customize colors/fonts, and how to override styles without forking the theme.
 
+### 🗺️ [Project Overview](docs/PROJECT_OVERVIEW.md)
+High-level architecture summary, repository conventions, layout hierarchy, and design philosophy.
+
+### 📜 [Completed Historical Audit](docs/COMPLETED_AUDIT.md)
+Permanent engineering record of historical bug fixes, security hardening, and architectural upgrades.
+
 ## Project Structure
 
-```
+```text
 bilingual-jekyll-resume-theme/
-├── _layouts/          # HTML templates (default, resume-en, resume-ar, profile)
-├── _includes/          # Reusable components (sections, headers, analytics)
-├── _sass/             # SCSS stylesheets (RTL support, print styles)
-├── _data/             # Theme data (includes ar/months.yml)
+├── _layouts/          # HTML templates (default, resume-en, resume-ar, profile, error)
+├── _includes/         # Reusable components (sections, headers, analytics, avatar, toggle)
+├── _sass/             # SCSS stylesheets (RTL support, dark mode tokens, print styles)
+├── _plugins/          # Dynamic generators (error_pages_generator.rb)
+├── lib/               # Gem entrypoint and runtime extensions
+├── _data/             # Theme data (includes ar/months.yml, error_pages.yml)
 ├── assets/            # CSS, images, favicons
 └── docs/              # Documentation and sample files
     ├── _data/         # Sample data files (copy to your site's _data/)
@@ -106,7 +114,7 @@ active_resume_path_ar: "ar"  # Uses _data/ar/* (recommended)
 
 This is the recommended approach even if you're only using one language, as it keeps your data organized and makes it easy to add more languages later. **Advanced users:** You can place files directly in `_data/` (root) by setting these to empty strings, but this is not recommended for beginners.
 
-See the [Configuration Guide](docs/CONFIG_GUIDE.md#data-source-active_resume_path_en_ar) for details.
+See the [Configuration Guide](docs/CONFIG_GUIDE.md#7-resume-display--behavior-controls) for details.
 
 ### Sample Files
 
@@ -127,8 +135,11 @@ To develop this theme locally:
 # Install dependencies
 bundle install
 
-# Run development server
-bundle exec jekyll serve
+# Run development server in this repo (uses sample config to activate required plugins)
+bundle exec jekyll serve --config docs/_data/_config.sample.yml
+
+# Build static output
+bundle exec jekyll build --config docs/_data/_config.sample.yml
 
 # Build the gem
 gem build bilingual-jekyll-resume-theme.gemspec
@@ -157,8 +168,10 @@ The theme is available as open source under the terms of the [MIT License](LICEN
 
 - 📖 Check the [documentation guides](docs/) for detailed information
 - 🐛 Report issues on [GitHub Issues](https://github.com/kmutahar/bilingual-jekyll-resume-theme/issues)
-- 💡 See [project_overview.md](project_overview.md) for a high-level architecture overview
+- 💡 See [PROJECT_OVERVIEW.md](docs/PROJECT_OVERVIEW.md) for a high-level architecture overview
+- 📜 See [COMPLETED_AUDIT.md](docs/COMPLETED_AUDIT.md) for historical remediations and architectural decisions
 
 ---
 
-**Created by Khaldoon Mutahar** | Version 0.4.0 | MIT License
+**Created by Khaldoon Mutahar** | Version 0.8.0 | MIT License
+

data/_includes/ar-date.html

@@ -1,4 +1,4 @@
-{% comment %}
+{%- comment -%}
   Arabic Date Formatter Include
   This include file formats a date in Arabic format by looking up the Arabic month name
   from the site data and formatting it according to the specified style.
@@ -8,34 +8,45 @@
     {% include ar-date.html date=page.date %}
 
   Parameters:
-    - date: The date to format (required)
+    - date: The date to format (required). Accepts ISO 8601 strings (YYYY-MM-DD, YYYY-MM), Jekyll date objects, or Ruby Time instances.
     - style: "MDY" for "Month Day, Year" format, or any other value for "Month Year" format (optional)
-{% endcomment %}
 
-{% comment %}
+  Architecture & Portability Notes:
+    - Pure Liquid Implementation: Standard Jekyll on GitHub Pages runs in safe mode without custom Ruby plugins or system locale C-extensions. This pure Liquid dictionary lookup provides 100% portable Arabic month translation without external dependencies.
+    - Ongoing Roles & Date Ranges: This component formats single discrete timestamps. Date ranges (e.g. start date to end date) are composed in caller templates like `_includes/resume-section-ar.html`. Ongoing positions (where `present: true` or `enddate: "Present"`) are handled by callers which emit the localized phrase "حتى الآن" rather than passing non-date strings here.
+{%- endcomment -%}
+
+{%- comment -%}
   Extract date components from the provided date using Jekyll date filters:
-  - "%-m": Month as a number (1-12) without leading zeros
+  - "%-m": Month as a number (1-12) without leading zeros. Stripping the leading zero is essential because `_data/ar/months.yml` keys are formatted as "1", "2", ... "12".
   - "%-d": Day as a number (1-31) without leading zeros
   - "%Y": Year as a 4-digit number
-{% endcomment %}
-{% assign m = include.date | date: "%-m" %}
-{% assign d = include.date | date: "%-d" %}
-{% assign y = include.date | date: "%Y" %}
+{%- endcomment -%}
+{%- if include.date and include.date != "" -%}
+  {%- assign m = include.date | date: "%-m" -%}
+  {%- assign d = include.date | date: "%-d" -%}
+  {%- assign y = include.date | date: "%Y" -%}
 
-{% comment %}
+{%- comment -%}
   Look up the Arabic month name from the site data file:
   - site.data.ar.months is a YAML file containing month names in Arabic
   - The month number (m) is used as the key to retrieve the corresponding Arabic month name
-{% endcomment %}
-{% assign month_name = site.data.ar.months[m] %}
+  - Resilience: If the date cannot be parsed or month key is not found, fallback logic outputs raw `include.date` to prevent build failures.
+{%- endcomment -%}
+  {%- assign month_name = site.data.ar.months[m] -%}
 
-{% comment %}
+{%- comment -%}
   Format the date output based on the style parameter:
-  - If style is "MDY": Output "Month Day, Year" (e.g., "يناير 15, 2024")
-  - Otherwise: Output "Month Year" (e.g., "يناير 2024")
-{% endcomment %}
-{% if include.style == "MDY" %}
-  {{ month_name }} {{ d }}, {{ y }}
-{% else %}
-  {{ month_name }} {{ y }}
-{% endif %}
+  - If style is "MDY": Output "Month Day, Year" (e.g., "يناير 15, 2024") - used for certifications, awards, and birthdates.
+  - Otherwise: Output "Month Year" (e.g., "يناير 2024") - used for employment roles, education, and volunteering.
+{%- endcomment -%}
+  {%- if month_name -%}
+    {%- if include.style == "MDY" -%}
+      {{ month_name }} {{ d }}, {{ y }}
+    {%- else -%}
+      {{ month_name }} {{ y }}
+    {%- endif -%}
+  {%- else -%}
+    {{ include.date }}
+  {%- endif -%}
+{%- endif -%}

data/_includes/avatar.html

@@ -0,0 +1,80 @@
+{%- comment -%}
+Include: Reusable Avatar Component
+- Purpose: Render accessible, configurable profile picture.
+- Parameters:
+  - lang: Optional language code ('en' | 'ar'). Defaults to page.lang or site.lang or 'en'.
+  - link: Optional boolean to override link rendering.
+  - class: Optional extra CSS classes.
+{%- endcomment -%}
+
+{%- comment -%}
+  Language Detection Cascade:
+  Resolves language in order of specificity: explicit include parameter -> page front matter -> site default -> 'en'.
+{%- endcomment -%}
+{% assign current_lang = include.lang | default: page.lang | default: site.lang | default: 'en' %}
+
+{%- comment -%}
+  Image Source Resolution Hierarchy & Subpath Safety:
+  1. Priority: site.avatar_url (modern explicit configuration) -> site.avatar (legacy option) -> '/assets/images/Profile-min.jpg' (bundled default).
+  2. Subpath Safety: If the avatar path contains '://', it is treated as an absolute external CDN URL and preserved as-is.
+     Otherwise, it is piped through Liquid's `relative_url` filter to ensure correct resolution on GitHub Pages sites
+     hosted under repository subpaths (e.g. username.github.io/project-name/).
+{%- endcomment -%}
+{% assign avatar_raw = site.avatar_url | default: site.avatar | default: '/assets/images/Profile-min.jpg' %}
+{% if avatar_raw contains "://" %}
+  {% assign avatar_src = avatar_raw %}
+  {% else %}
+  {% assign avatar_src = avatar_raw | relative_url %}
+{% endif %}
+
+{%- comment -%}
+  Localized Alt Text & Title Resolution:
+  Generates meaningful alt text to satisfy WCAG 2.2 non-empty alt text requirements.
+  - For Arabic (ar): Constructs full name from `site.name_ar` fields.
+    Alt text cascade: site.avatar_alt_ar -> site.avatar_alt -> name_ar -> fallback 'الصورة الشخصية'.
+  - For English / Other (en): Constructs full name from `site.name` fields.
+    Alt text cascade: site.avatar_alt_en -> site.avatar_alt -> name_en -> fallback 'Profile photo'.
+{%- endcomment -%}
+{% if current_lang == 'ar' %}
+  {% capture name_ar %}{{ site.name_ar.first }}{% if site.name_ar.middle %} {{ site.name_ar.middle }}{% endif %}{% if site.name_ar.last %} {{ site.name_ar.last }}{% endif %}{% endcapture %}
+  {% assign name_ar = name_ar | strip %}
+  {% assign avatar_alt = site.avatar_alt_ar | default: site.avatar_alt | default: name_ar | default: 'الصورة الشخصية' %}
+  {% assign link_title = site.title | default: 'الصفحة الرئيسية' %}
+{% else %}
+  {% capture name_en %}{{ site.name.first }}{% if site.name.middle %} {{ site.name.middle }}{% endif %}{% if site.name.last %} {{ site.name.last }}{% endif %}{% endcapture %}
+  {% assign name_en = name_en | strip %}
+  {% assign avatar_alt = site.avatar_alt_en | default: site.avatar_alt | default: name_en | default: 'Profile photo' %}
+  {% assign link_title = site.title | default: 'Homepage' %}
+{% endif %}
+
+{%- comment -%}
+  Hyperlink Wrapping Toggle:
+  Defaults to true. Disabling can occur globally via `site.avatar_link: false` or locally via `include.link: false`.
+{%- endcomment -%}
+{% assign render_link = true %}
+{% if site.avatar_link == false or include.link == false %}
+  {% assign render_link = false %}
+{% endif %}
+
+{%- comment -%}
+  Avatar Markup Rendering:
+  - If linked: Wraps <img> in <a> with subpath-safe href and tab-nabbing security (rel="noopener" if target != '_self').
+  - If unlinked: Renders standalone <img>.
+  Both branches include class="no-print" and itemprop="image".
+{%- endcomment -%}
+{% if render_link %}
+  {% assign avatar_link_raw = site.avatar_link | default: '/' %}
+  {% if avatar_link_raw contains "://" %}
+    {% assign avatar_href = avatar_link_raw %}
+  {% else %}
+    {% assign avatar_href = avatar_link_raw | relative_url %}
+  {% endif %}
+  {% assign avatar_target = site.avatar_link_target | default: '_self' %}
+
+  <a href="{{ avatar_href }}" title="{{ link_title }}" class="avatar-link no-print"{% if avatar_target != '_self' %} target="{{ avatar_target }}" rel="noopener"{% endif %}>
+    <img src="{{ avatar_src }}" alt="{{ avatar_alt }}" class="avatar no-print{% if include.class %} {{ include.class }}{% endif %}" itemprop="image">
+  </a>
+{% else %}
+  <img src="{{ avatar_src }}" alt="{{ avatar_alt }}" class="avatar no-print{% if include.class %} {{ include.class }}{% endif %}" itemprop="image">
+{% endif %}
+

data/_includes/dark-mode-toggle.html

@@ -1,3 +1,26 @@
+{%- comment -%}
+  Component: Dark Mode Toggle Widget
+  - Purpose: Provides an accessible, persistent floating toggle button for switching between Light and Dark color themes.
+  - Activation Cascade:
+    1. Evaluates site-level switches: `site.dark_mode` or `site.resume_dark_mode` (boolean or "enabled").
+    2. Applies page-level override if specified in front matter (`page.dark_mode: true/false/enabled`).
+    3. Renders button markup and client controller only when enabled.
+  - Visual Design: Floating circular action button fixed in the viewport.
+  - Print Media: Decorated with `class="no-print"` to ensure it is excluded from printed resumes or PDF generation.
+  - CSS Integration: Operates with CSS custom properties defined in `_sass/_dark-mode.scss`.
+{%- endcomment -%}
+
+{% assign dark_mode_enabled = false %}
+{% if site.dark_mode == "enabled" or site.dark_mode == true or site.resume_dark_mode == "enabled" or site.resume_dark_mode == true %}
+  {% assign dark_mode_enabled = true %}
+{% endif %}
+{% if page.dark_mode == false %}
+  {% assign dark_mode_enabled = false %}
+{% elsif page.dark_mode == true or page.dark_mode == "enabled" %}
+  {% assign dark_mode_enabled = true %}
+{% endif %}
+
+{% if dark_mode_enabled %}
 <!-- Dark Mode Toggle Button (Two-state: System Default vs Pinned Override) -->
 <button
   id="dark-mode-toggle"
@@ -8,6 +31,12 @@
   aria-pressed="false"
   data-pinned="false"
 >
+  {%- comment -%}
+    Inline SVG Icons:
+    - Both icons have `aria-hidden="true"` and `focusable="false"` to prevent assistive technologies
+      from announcing raw vector graphics and to keep keyboard focus solely on the parent <button>.
+    - Visibility is toggled via CSS selectors based on `data-theme` or system color-scheme preference.
+  {%- endcomment -%}
   <!-- Sun Icon: Visible in dark mode / indicates switching to light mode -->
   <svg
     class="dark-mode-icon dark-mode-icon-sun"
@@ -54,12 +83,23 @@
 </button>
 
 <script>
+  /**
+   * Dark Mode Client Controller
+   * Encapsulated in an IIFE to prevent polluting the global window namespace.
+   *
+   * Two-State Logic Architecture:
+   * 1. Unpinned (System Default): Follows the OS `prefers-color-scheme`. `localStorage` contains no value.
+   *    Listens dynamically to OS dark/light mode switches.
+   * 2. Pinned (User Override): Explicit user choice saved in `localStorage.setItem('color-scheme', ...)`.
+   *    Clicking the button when pinned resets the theme back to the system default (clearing localStorage).
+   */
   (function () {
     var toggleBtn = document.getElementById('dark-mode-toggle');
     if (!toggleBtn) return;
 
     var metaTheme = document.querySelector('meta[name="color-scheme"]');
 
+    // Detects user's operating system level theme preference
     function getSystemTheme() {
       if (window.matchMedia) {
         return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
@@ -67,6 +107,8 @@
       return 'light';
     }
 
+    // Storage Error Boundary: Accesses localStorage inside try/catch to safely handle
+    // private browsing modes (e.g. Safari Private Browsing) or restricted cookie security settings.
     function getSavedTheme() {
       try {
         var val = localStorage.getItem('color-scheme');
@@ -79,6 +121,7 @@
       }
     }
 
+    // Determines if current page layout is Arabic / Right-to-Left
     function isArabicRTL() {
       var docEl = document.documentElement;
       var dir = docEl.getAttribute('dir');
@@ -86,6 +129,7 @@
       return dir === 'rtl' || lang === 'ar';
     }
 
+    // Synchronizes data attributes on <html> and <meta name="color-scheme">
     function syncState() {
       var saved = getSavedTheme();
       if (saved !== null) {
@@ -103,6 +147,7 @@
       }
     }
 
+    // Updates ARIA accessibility attributes, data-pinned status, and localized tooltips
     function updateUI() {
       var saved = getSavedTheme();
       var isPinned = (saved !== null);
@@ -114,6 +159,7 @@
       toggleBtn.setAttribute('aria-pressed', isPinned ? 'true' : 'false');
       toggleBtn.setAttribute('data-current-theme', effectiveTheme);
 
+      // Localized screen-reader announcements and tooltip titles
       if (isPinned) {
         label = isRTL
           ? 'إعادة ضبط المظهر إلى الوضع التلقائي للنظام'
@@ -135,6 +181,7 @@
       toggleBtn.setAttribute('title', label);
     }
 
+    // Toggles theme state: cycles between user-pinned override and system default
     function toggleTheme() {
       var saved = getSavedTheme();
       if (saved !== null) {
@@ -157,6 +204,7 @@
 
     toggleBtn.addEventListener('click', toggleTheme);
 
+    // Reactive System Theme Listener: Adapts UI in real-time when OS theme changes (if unpinned)
     if (window.matchMedia) {
       var darkQuery = window.matchMedia('(prefers-color-scheme: dark)');
       var mqListener = function () {
@@ -171,7 +219,10 @@
       }
     }
 
+    // Initial hydration on page load
     syncState();
     updateUI();
   })();
 </script>
+{% endif %}
+

data/_includes/data-loader.html

@@ -0,0 +1,41 @@
+{%- comment -%}
+================================================================================
+DYNAMIC DATA LOADER HELPER (_includes/data-loader.html)
+================================================================================
+PURPOSE:
+  Dynamically resolves the root data object (`resume_data`) for the current layout
+  by traversing nested YAML folders in `_data/` based on a dot-separated path.
+
+HOW IT WORKS:
+  1. Default Assignment:
+     Starts with top-level `site.data`. If no custom subpath is configured,
+     the template reads directly from root YAML files (e.g. `_data/experience.yml`).
+
+  2. Subpath Splitting (`split: '.'`):
+     Breaks dot-separated strings into array segments.
+     Example: "2025-06.20250621-PM" -> ["2025-06", "20250621-PM"]
+     Example: "en" -> ["en"]
+
+  3. Recursive Bracket Notation (`resume_data[part]`):
+     Liquid dot notation (site.data.2025-06) breaks on numbers and hyphens.
+     Bracket notation safely accesses arbitrary string keys at any nesting depth:
+     - Level 1: site.data["2025-06"]
+     - Level 2: site.data["2025-06"]["20250621-PM"]
+
+PARAMETERS:
+  - `path` (String, Optional): The dot-path string to resolve (e.g. "en", "ar", "2025-06.v1").
+    Defaults to `site.active_resume_path_en` if omitted.
+
+OUTPUT:
+  - Sets the global template variable `resume_data` in the calling layout context.
+================================================================================
+{%- endcomment -%}
+{%- assign data_path = include.path | default: site.active_resume_path_en -%}
+{%- assign resume_data = site.data -%}
+
+{%- if data_path != blank -%}
+  {%- assign path_parts = data_path | split: '.' -%}
+  {%- for part in path_parts -%}
+    {%- assign resume_data = resume_data[part] -%}
+  {%- endfor -%}
+{%- endif -%}

data/_includes/hreflang.html

@@ -4,6 +4,18 @@ START: HREFLANG TAGS FOR MULTILINGUAL SEO
 This logic generates the <link rel="alternate"> tags that tell
 search engines about the different language versions of this page.
 It only runs if a 't_id' (Translation ID) is set in the page's front matter.
+
+WHY THIS MATTERS:
+Search engines (Google, Bing, Yandex) require bidirectional hreflang links across
+all localized versions of equivalent content to prevent duplicate content penalties
+and to direct international visitors to the correct regional/language variant.
+
+HOW IT WORKS:
+- Pages representing the same document in different languages (e.g. English and Arabic CVs)
+  share an identical `t_id` identifier in front matter.
+- site.pages is queried to locate all translation peers.
+- Absolute URLs are required by RFC 8288 and Google Search Console standards.
+- The 'x-default' fallback is explicitly mapped to the English edition for unmatched locales.
 ==================================================================
 {% endcomment %}
 {% if page.t_id %}

data/_includes/language-switcher.html

@@ -0,0 +1,64 @@
+{%- comment -%}
+Include: Reusable Bilingual Language Switcher Component (Feature 1.2)
+- Purpose: Floating pill button that toggles between the English and Arabic resume.
+- Positioning: Fixed top-left (LTR layouts) / top-right (RTL layouts); mirrors the dark-mode toggle.
+- Link Resolution (two-tier):
+    1. Discovers the counterpart page via page.t_id + lang match (site.pages).
+    2. Falls back to site.resume_en_url / site.resume_ar_url from _config.yml.
+- Accessibility: Localized aria-label + title, visible focus ring (WCAG 2.2 AA).
+- Print Safety: Decorated with class="no-print" — hidden on printed resume sheets.
+- Toggle: Disabled via site.resume_language_switcher: false in _config.yml.
+{%- endcomment -%}
+
+{% if site.resume_language_switcher != false and page.language_switcher != false and page.layout != 'error' %}
+  {%- comment -%} Determine the current and target language {%- endcomment -%}
+  {% assign current_lang = page.lang | default: site.lang | default: 'en' %}
+  {% assign target_lang = 'ar' %}
+  {% if current_lang == 'ar' %}
+    {% assign target_lang = 'en' %}
+  {% endif %}
+
+  {%- comment -%}
+  TIER 1: Auto-discover counterpart page by matching page.t_id + target language.
+  Both pages must have the same t_id value in their front matter (e.g., t_id: cv-main).
+  {%- endcomment -%}
+  {% assign target_url = nil %}
+  {% if page.t_id %}
+    {% assign matched_page = site.pages | where: "t_id", page.t_id | where: "lang", target_lang | first %}
+    {% if matched_page %}
+      {% assign target_url = matched_page.url | relative_url %}
+    {% endif %}
+  {% endif %}
+
+  {%- comment -%}
+  TIER 2: Fall back to config-defined URLs if t_id match was not found.
+  {%- endcomment -%}
+  {% unless target_url %}
+    {% if current_lang == 'ar' %}
+      {% assign target_url = site.resume_en_url | default: '/en/cv/' | relative_url %}
+    {% else %}
+      {% assign target_url = site.resume_ar_url | default: '/ar/cv/' | relative_url %}
+    {% endif %}
+  {% endunless %}
+
+  {%- comment -%} Derive accessible labels and visible text based on direction {%- endcomment -%}
+  {% if current_lang == 'ar' %}
+    {% assign switcher_label      = 'Switch language to English' %}
+    {% assign switcher_title      = 'English' %}
+    {% assign switcher_short_text = 'EN' %}
+  {% else %}
+    {% assign switcher_label      = 'التحويل إلى اللغة العربية' %}
+    {% assign switcher_title      = 'العربية' %}
+    {% assign switcher_short_text = 'عربي' %}
+  {% endif %}
+
+  <div class="language-switcher no-print" role="navigation" aria-label="Language Selector">
+    <a href="{{ target_url }}"
+       class="lang-switch-btn"
+       aria-label="{{ switcher_label }}"
+       title="{{ switcher_title }}">
+      <span class="lang-icon" aria-hidden="true">🌐</span>
+      <span class="lang-label-target">{{ switcher_short_text }}</span>
+    </a>
+  </div>
+{% endif %}

data/_includes/main-head.html

@@ -1,2 +1,7 @@
+{%- comment -%}
+  Main Site Head Include
+  - Loaded by: `_layouts/default.html` and `_layouts/error.html`.
+  - Stylesheet: Links the compiled generic site and error page stylesheet `assets/css/main.css`.
+{%- endcomment -%}
 <!--Stylesheet-->
 <link rel="stylesheet" type="text/css" href="{{ 'assets/css/main.css' | relative_url }}">

data/_includes/print-social-links.html

@@ -1,5 +1,15 @@
+{%- comment -%}
+  Component: Print-Only Social & Contact Links
+  - Purpose: Renders full plaintext URLs for physical paper printouts and PDF exports
+    where clickable icon-only links cannot be followed.
+  - Direction & Localization: Detects Arabic context via layout or lang variables and
+    renders bilingual platform labels.
+  - Bidi Protection: Every URL is wrapped in `<span dir="ltr">` to ensure web addresses,
+    slashes, and domain names are never reversed or scrambled in an RTL reading context.
+{%- endcomment -%}
 <!-- and guess where these are defined? Yup, you guessed it: the _config.yml file -->
 {% if site.resume_print_social_links %}
+{%- comment -%} Determine whether current page context is Arabic to localize platform labels {%- endcomment -%}
 {% assign is_ar = false %}
 {% if page.layout == "resume-ar" or page.lang == "ar" or page.language == "ar" or layout.lang == "ar" %}
     {% assign is_ar = true %}

data/_includes/profile-head.html

@@ -0,0 +1,7 @@
+{%- comment -%}
+  Profile Landing Page Head Include
+  - Loaded by: `_layouts/profile.html`.
+  - Stylesheet: Links the compiled profile portfolio stylesheet `assets/css/profile.css`.
+{%- endcomment -%}
+<!-- Profile Stylesheet -->
+<link rel="stylesheet" type="text/css" href="{{ 'assets/css/profile.css' | relative_url }}">

data/_includes/resume-head-ar.html

@@ -1,3 +1,13 @@
+{%- comment -%}
+  Arabic Resume Head Include
+  - Loaded by: `_layouts/resume-ar.html` inside the HTML <head>.
+  - Typography Resolution:
+    1. Custom Font: If `site.font_ar_url` is defined, links the custom font stylesheet.
+    2. Google Fonts (Cairo): Unless disabled via `site.disable_google_fonts` or `site.resume_theme == 'no-custom-fonts'`,
+       links the Cairo Arabic typeface with `preconnect` resource hints for faster DNS resolution and TLS handshake.
+  - Stylesheet: Links the compiled Arabic RTL stylesheet `assets/css/cv-ar.css` via `relative_url`.
+  - Multilingual SEO: Includes `_includes/hreflang.html` for bidirectional search engine indexing.
+{%- endcomment -%}
 {% if site.font_ar_url %}
     <!-- Custom Arabic Font Stylesheet -->
     <link rel="stylesheet" href="{{ site.font_ar_url | relative_url }}">

data/_includes/resume-head-en.html

@@ -1,3 +1,10 @@
+{%- comment -%}
+  English Resume Head Include
+  - Loaded by: `_layouts/resume-en.html` inside the HTML <head>.
+  - Typography: Injects Google Web Fonts for Lora (serif headings) and Open Sans (sans-serif body).
+  - Stylesheet: Links the compiled English LTR stylesheet `assets/css/cv.css` using `relative_url` for subpath safety.
+  - Multilingual SEO: Includes `_includes/hreflang.html` to output alternate language annotations for search engines.
+{%- endcomment -%}
 <!-- Google font typography settings - defined in _config.yml -->
 <link href='https://fonts.googleapis.com/css?family=Lora:400,700%7COpen+Sans:400,300,800,700' rel='stylesheet' type='text/css'>