bilingual-jekyll-resume-theme 0.3.1 → 0.5.0

data/docs/DATA_GUIDE.md

@@ -2,6 +2,14 @@
 
 This document explains all data file structures used by the bilingual Jekyll resume theme. Each section of your resume is stored in a separate YAML file in the `_data/` directory.
 
+**For beginners:** All your resume content (experience, education, skills, etc.) goes in YAML files in the `_data/` folder. 
+
+**Recommended approach:** Use language-specific folders (`_data/en/` for English and `_data/ar/` for Arabic). This is the recommended approach even if you're only using one language, as it makes it easier to add more languages in the future and keeps your data organized. 
+
+**Advanced users:** If you prefer, you can place files directly in `_data/` (root), but you'll need to set `active_resume_path_en: ""` and `active_resume_path_ar: ""` in your `_config.yml`.
+
+You can copy sample files from `docs/_data/en/` and `docs/_data/ar/` to get started. The theme reads these files and displays them on your resume pages.
+
 Key Features:
 
 1. Complete coverage of all 12 data types with commented YAML examples
@@ -40,13 +48,16 @@ Highlights:
 10. [Languages](#languages)
 11. [Links](#links)
 12. [Interests](#interests)
-13. [General Guidlines](#general-guidelines)
+13. [Header Intro](#header-intro)
+14. [General Guidlines](#general-guidelines)
 
 ---
 
 ## Experience
 
-**File:** `_data/experience.yml`
+**File:** `_data/en/experience.yml` (English) or `_data/ar/experience.yml` (Arabic)
+
+**Recommended:** Use `_data/en/experience.yml` for English and `_data/ar/experience.yml` for Arabic. This keeps your data organized and makes it easy to add more languages later.
 
 Jobs are grouped by company name. Multiple roles at the same company will be displayed together. Roles are sorted by `startdate` (most recent first).
 
@@ -93,7 +104,9 @@ Jobs are grouped by company name. Multiple roles at the same company will be dis
 
 ## Education
 
-**File:** `_data/education.yml`
+**File:** `_data/en/education.yml` (English) or `_data/ar/education.yml` (Arabic)
+
+**Recommended:** Use `_data/en/education.yml` for English and `_data/ar/education.yml` for Arabic.
 
 ```yaml
 - degree: "Bachelor of Business"  # Required: Degree name and details
@@ -125,7 +138,9 @@ Jobs are grouped by company name. Multiple roles at the same company will be dis
 
 ## Certifications
 
-**File:** `_data/certifications.yml`
+**File:** `_data/en/certifications.yml` (English) or `_data/ar/certifications.yml` (Arabic)
+
+**Recommended:** Use `_data/en/certifications.yml` for English and `_data/ar/certifications.yml` for Arabic.
 
 ```yaml
 - name: "Business Certificate"        # Required: Certification name
@@ -165,7 +180,9 @@ Jobs are grouped by company name. Multiple roles at the same company will be dis
 
 ## Courses
 
-**File:** `_data/courses.yml`
+**File:** `_data/en/courses.yml` (English) or `_data/ar/courses.yml` (Arabic)
+
+**Recommended:** Use `_data/en/courses.yml` for English and `_data/ar/courses.yml` for Arabic.
 
 ```yaml
 - name: "Certificate of Course Completion"  # Required: Course name
@@ -200,7 +217,9 @@ Jobs are grouped by company name. Multiple roles at the same company will be dis
 
 ## Volunteering
 
-**File:** `_data/volunteering.yml`
+**File:** `_data/en/volunteering.yml` (English) or `_data/ar/volunteering.yml` (Arabic)
+
+**Recommended:** Use `_data/en/volunteering.yml` for English and `_data/ar/volunteering.yml` for Arabic.
 
 Structure is identical to Experience section. Volunteer positions are grouped by organization.
 
@@ -232,7 +251,9 @@ Same as Experience section - grouped by organization, sorted by date.
 
 ## Projects
 
-**File:** `_data/projects.yml`
+**File:** `_data/en/projects.yml` (English) or `_data/ar/projects.yml` (Arabic)
+
+**Recommended:** Use `_data/en/projects.yml` for English and `_data/ar/projects.yml` for Arabic.
 
 ```yaml
 - project: "Closed Source Project"                        # Required: Project name
@@ -269,7 +290,9 @@ Same as Experience section - grouped by organization, sorted by date.
 
 ## Skills
 
-**File:** `_data/skills.yml`
+**File:** `_data/en/skills.yml` (English) or `_data/ar/skills.yml` (Arabic)
+
+**Recommended:** Use `_data/en/skills.yml` for English and `_data/ar/skills.yml` for Arabic.
 
 ```yaml
 - skill: "Organizational leadership"           # Required: Skill name/title
@@ -298,7 +321,9 @@ Same as Experience section - grouped by organization, sorted by date.
 
 ## Recognition
 
-**File:** `_data/recognitions.yml`
+**File:** `_data/en/recognitions.yml` (English) or `_data/ar/recognitions.yml` (Arabic)
+
+**Recommended:** Use `_data/en/recognitions.yml` for English and `_data/ar/recognitions.yml` for Arabic.
 
 ```yaml
 - award: "Outstanding Achievement"             # Required: Award name
@@ -331,7 +356,9 @@ Same as Experience section - grouped by organization, sorted by date.
 
 ## Associations
 
-**File:** `_data/associations.yml`
+**File:** `_data/en/associations.yml` (English) or `_data/ar/associations.yml` (Arabic)
+
+**Recommended:** Use `_data/en/associations.yml` for English and `_data/ar/associations.yml` for Arabic.
 
 ```yaml
 - organization: "Internet Sociaity"  # Required: Organization name
@@ -368,7 +395,9 @@ Same as Experience section - grouped by organization, sorted by date.
 
 ## Languages
 
-**File:** `_data/languages.yml`
+**File:** `_data/en/languages.yml` (English) or `_data/ar/languages.yml` (Arabic)
+
+**Recommended:** Use `_data/en/languages.yml` for English and `_data/ar/languages.yml` for Arabic.
 
 ```yaml
 - language: English                            # Required: Language name
@@ -408,7 +437,9 @@ Same as Experience section - grouped by organization, sorted by date.
 
 ## Links
 
-**File:** `_data/links.yml`
+**File:** `_data/en/links.yml` (English) or `_data/ar/links.yml` (Arabic)
+
+**Recommended:** Use `_data/en/links.yml` for English and `_data/ar/links.yml` for Arabic.
 
 ```yaml
 - description: "Resume"       # Required: Link description/title
@@ -441,7 +472,9 @@ Same as Experience section - grouped by organization, sorted by date.
 
 ## Interests
 
-**File:** `_data/interests.yml`
+**File:** `_data/en/interests.yml` (English) or `_data/ar/interests.yml` (Arabic)
+
+**Recommended:** Use `_data/en/interests.yml` for English and `_data/ar/interests.yml` for Arabic.
 
 Simple list of interests/hobbies.
 
@@ -463,6 +496,33 @@ Simple list of interests/hobbies.
 
 ---
 
+## Header Intro
+
+**File:** `_data/en/header.yml` (English) or `_data/ar/header.yml` (Arabic)
+
+**Recommended:** Use `_data/en/header.yml` for English and `_data/ar/header.yml` for Arabic.
+
+Contains the executive summary/intro paragraph that appears below your name and title in the resume header.
+
+```yaml
+# Header intro paragraph
+# Enable this in _config.yml with: resume_header_intro_en: true (for English)
+# or resume_header_intro_ar: true (for Arabic)
+
+intro: "Your professional summary or elevator pitch goes here. This is the English version."
+```
+
+**Display Format:**
+- Appears as a paragraph below your name, title, and social links
+- Only shows if `resume_header_intro_en: true` (English) or `resume_header_intro_ar: true` (Arabic) is set in `_config.yml`
+- Supports basic HTML formatting
+
+**Important:** 
+- Create separate files for each language: `_data/en/header.yml` for English and `_data/ar/header.yml` for Arabic
+- Sample files are available in `docs/_data/en/header.yml` and `docs/_data/ar/header.yml`
+
+---
+
 ## General Guidelines
 
 ### Date Formats
@@ -470,7 +530,8 @@ Simple list of interests/hobbies.
 **For startdate/enddate fields:**
 - Always use ISO format: `YYYY-MM-DD` (e.g., `2024-03-15`)
 - These auto-format to "Mon YYYY" in English (e.g., "Mar 2024")
-- Arabic layout uses custom date formatting
+- Arabic layout uses custom date formatting via `ar-date.html` which reads from `site.data.ar.months`
+- **Note:** The theme already includes `_data/ar/months.yml` with Arabic month names, so you don't need to create this file manually.
 
 **For display text fields (year, duration):**
 - Use any text format you want
@@ -506,23 +567,41 @@ url: https://example.com
 
 ### File Location
 
-All data files go in the `_data/` directory or a subdirectory based on the `_config.yml`:
+**Recommended approach (for beginners):** Place all data files in language-specific folders (`_data/en/` and `_data/ar/`). This is the recommended approach even if you're only using one language, as it:
+- Keeps your data organized
+- Makes it easy to add more languages in the future
+- Follows the same structure as the sample files
+
+**Advanced approach:** You can place files directly in `_data/` (root), but you'll need to set `active_resume_path_en: ""` and `active_resume_path_ar: ""` in your `_config.yml`. This approach is not recommended for beginners.
+
+**Recommended structure (use language folders):**
 ```
 _data/
-├── experience.yml
-├── education.yml
-├── certifications.yml
-├── courses.yml
-├── volunteering.yml
-├── projects.yml
-├── skills.yml
-├── recognitions.yml
-├── associations.yml
-├── languages.yml
-├── links.yml
-└── interests.yml
+├── en/
+│   ├── header.yml        # Executive summary/intro paragraph
+│   ├── experience.yml
+│   ├── education.yml
+│   ├── certifications.yml
+│   ├── courses.yml
+│   ├── volunteering.yml
+│   ├── projects.yml
+│   ├── skills.yml
+│   ├── recognitions.yml
+│   ├── associations.yml
+│   ├── languages.yml
+│   ├── links.yml
+│   └── interests.yml
+└── ar/
+    ├── header.yml        # Executive summary/intro paragraph (Arabic)
+    ├── experience.yml
+    ├── education.yml
+    └── ... (same files as en/)
 ```
 
+**Note:** The theme includes `_data/ar/months.yml` in the theme itself (not in your site), so Arabic month names are available automatically. You don't need to create this file in your site's `_data/` folder.
+
+**Sample files:** You can copy sample data files from `docs/_data/en/` and `docs/_data/ar/` to get started. These contain commented examples showing the structure for each section type.
+
 ### Enabling Sections in _config.yml
 
 To control which sections appear on your resume, edit `_config.yml`:

data/docs/INCLUDES_GUIDE.md

@@ -52,6 +52,8 @@ In this theme, includes are used for:
 - Social icons
 - Fine-grained rendering of resume sections in English and Arabic
 
+**For beginners:** Includes are like small reusable code snippets. Instead of copying the same HTML code in multiple places, you put it in an include file and reference it. The theme uses includes to organize code into logical pieces (like the header, social links, analytics, etc.).
+
 ---
 
 ## How includes fit into this theme
@@ -79,14 +81,17 @@ Typical include usage inside layouts:
 
 ### Data flow and configuration
 
-The resume layouts compute a `resume_data` object that points to the active data subtree in `_data/`, based on `active_resume_path` configured in your site’s `_config.yml`. This lets you organize multiple datasets (e.g., different roles/versions) and switch without editing templates.
+The resume layouts compute a `resume_data` object that points to the active data subtree in `_data/`, based on `active_resume_path_en` (for English) and `active_resume_path_ar` (for Arabic) configured in your site's `_config.yml`. This lets you organize multiple datasets (e.g., different roles/versions) and switch without editing templates.
 
 Examples:
 - No path (empty or nil): `resume_data == site.data`
-- `active_resume_path: en`: `resume_data == site.data.en`
-- Nested path with dots: `active_resume_path: 2025-06.20250621-PM` → `resume_data == site.data['2025-06']['20250621-PM']`
+- `active_resume_path_en: "en"`: `resume_data == site.data.en` (English layout)
+- `active_resume_path_ar: "ar"`: `resume_data == site.data.ar` (Arabic layout)
+- Nested path with dots: `active_resume_path_en: "2025-06.20250621-PM"` → `resume_data == site.data['2025-06']['20250621-PM']`
+
+Most resume includes read from `resume_data.<section>` (e.g., `experience`, `skills`, `languages`). Feature flags and ordering live in `_config.yml` (see "Dynamic section rendering" below).
 
-Most resume includes read from `resume_data.<section>` (e.g., `experience`, `skills`, `languages`). Feature flags and ordering live in `_config.yml` (see “Dynamic section rendering” below).
+**For beginners:** The `resume_data` object is like a pointer to your data files. **Recommended:** Set `active_resume_path_en: "en"` and `active_resume_path_ar: "ar"` to use language-specific folders. This way, the theme will look for your data in `_data/en/experience.yml`, `_data/en/education.yml`, etc. for English, and `_data/ar/experience.yml`, etc. for Arabic. This keeps your English and Arabic data separate and organized, and is the recommended approach even if you're only using one language.
 
 ---
 
@@ -196,7 +201,9 @@ Usage in templates:
   - `style`: `MDY` → “Month Day, Year”; anything else → “Month Year”
 - Looks up the Arabic month name via `site.data.ar.months[m]`.
 
-Data requirement in your `_data/` (one of these structures):
+Data requirement: The theme includes `_data/ar/months.yml` by default, so you don't need to create this file manually. The months are already defined in the theme.
+
+If you're using a custom data path structure, you can define months in one of these ways:
 ```yaml
 # Option A: _data/ar.yml
 months:
@@ -215,12 +222,14 @@ months:
 ```
 or
 ```yaml
-# Option B: _data/ar/months.yml
+# Option B: _data/ar/months.yml (already included in theme)
 "1": يناير
 "2": فبراير
 # ...
 ```
 
+**Note:** Since the theme already includes `_data/ar/months.yml`, you typically don't need to add this file unless you're using a completely custom data structure.
+
 ---
 
 ### 9) social-links.html
@@ -319,7 +328,7 @@ The layout loops this array and includes the matching block.
 
 Example: Add “publications”.
 
-1) Data: create `_data/publications.yml` (or inside your active subtree) like:
+1) Data: create `_data/en/publications.yml` (or `_data/ar/publications.yml` for Arabic, or inside your active subtree) like:
 ```yaml
 - active: true
   title: Building Scalable Systems
@@ -474,7 +483,7 @@ To add a network not yet supported (e.g., Mastodon):
 - Respect configuration-driven behavior:
   - Feature flags under `resume_section.*`
   - Section order via `resume_section_order`
-  - Data path via `active_resume_path`
+  - Data path via `active_resume_path_en` and `active_resume_path_ar`
 - Localize: if you add a section in EN, consider adding the AR counterpart with translated labels and RTL visual checks.
 - SVG hygiene: strip unnecessary attributes/metadata; keep icons lightweight.
 - Printing: if something is important for PDF/print, add a print-only variant similar to `print-social-links.html`.

data/docs/LAYOUTS_GUIDE.md

@@ -13,7 +13,7 @@ A comprehensive, contributor-friendly overview of `_layouts/` in this theme: wha
   - [resume-en.html](#3-_layoutsresume-enhtml)
   - [resume-ar.html](#4-_layoutsresume-arhtml)
 - [Resume data loading (the `resume_data` object)](#resume-data-loading-the-resume_data-object)
-  - [Configuring `active_resume_path`](#configuring-active_resume_path)
+  - [Configuring `active_resume_path_en` and `active_resume_path_ar`](#configuring-active_resume_path_en-and-active_resume_path_ar)
   - [Dot-path traversal and bracket-notation](#dot-path-traversal-and-bracket-notation)
   - [Examples](#examples)
 - [Rendering flow inside resume layouts](#rendering-flow-inside-resume-layouts)
@@ -33,6 +33,8 @@ A comprehensive, contributor-friendly overview of `_layouts/` in this theme: wha
 
 Layouts wrap pages. A page chooses a layout via its front matter (e.g., `layout: resume-en`). The layout defines the overall HTML structure and where page content or reusable includes appear. This theme ships with specialized layouts for the resume (EN/AR) and a general-purpose base layout.
 
+**For beginners:** If you're new to Jekyll, think of layouts as templates that define the structure of your pages. You create a page file (like `resume-en.md`) and tell it which layout to use. The layout then handles all the HTML structure, styling, and includes the content from your data files.
+
 ---
 
 ## Layout inventory and responsibilities
@@ -88,21 +90,26 @@ Purpose: Arabic (RTL) resume layout. It mirrors `resume-en.html` with language-a
 
 Both resume layouts compute a single variable, `resume_data`, which points to the active subtree under `_data/`. This allows switching datasets without touching templates.
 
-### Configuring `active_resume_path`
+### Configuring `active_resume_path_en` and `active_resume_path_ar`
 
-Set a site-level key in `_config.yml`:
+Set site-level keys in `_config.yml`:
 
 ```yaml
-# Choose which subtree of _data/ to use for the resume
+# Choose which subtree of _data/ to use for each language
 # Examples below in the next section
-active_resume_path: ""
+active_resume_path_en: "en"  # Path for English resume
+active_resume_path_ar: "ar"  # Path for Arabic resume
 ```
 
-- If `active_resume_path` is empty or nil → `resume_data = site.data`
-- If `active_resume_path` is a single key (e.g., `en`) → `resume_data = site.data.en`
-- If `active_resume_path` is a dotted path (e.g., `2025-06.20250621-PM`) → the layout walks down each segment safely
+- If set to a single key (e.g., `"en"`) → `resume_data = site.data.en` (**recommended for beginners**)
+- If set to a dotted path (e.g., `"2025-06.20250621-PM"`) → the layout walks down each segment safely (advanced)
+- If `active_resume_path_en` or `active_resume_path_ar` is empty or nil → `resume_data = site.data` (uses root `_data/`, **advanced users only**)
+
+**Important:** The English layout (`resume-en.html`) reads `site.active_resume_path_en`, and the Arabic layout (`resume-ar.html`) reads `site.active_resume_path_ar`. This allows you to use different data folders for each language.
 
-Note: The layouts read `site.active_resume_path`. If you maintain multiple variants (time-boxed, roles, locales) under `_data/`, this switch lets you pick the current one at build time.
+**Recommended approach (for beginners):** Always use `"en"` and `"ar"` to place files in `_data/en/` and `_data/ar/` folders. 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:** If you maintain multiple variants (time-boxed, roles, locales) under `_data/`, you can use nested paths or root paths, but this is not recommended for beginners.
 
 ### Dot-path traversal and bracket-notation
 
@@ -115,17 +122,23 @@ Implementation highlights inside the layouts:
 ### Examples
 
 ```yaml
-# 1) Use files directly under _data/
-active_resume_path: ""
-# resume_data.experience == site.data.experience
-
-# 2) Use a language subtree
-active_resume_path: en
-# resume_data.experience == site.data.en.experience
-
-# 3) Use nested subtrees for versioning
-active_resume_path: 2025-06.20250621-PM
+# 1) Recommended: Use language subtrees (recommended for beginners)
+active_resume_path_en: "en"
+active_resume_path_ar: "ar"
+# EN: resume_data.experience == site.data.en.experience
+# AR: resume_data.experience == site.data.ar.experience
+# This is the recommended approach even if you're only using one language
+
+# 2) Advanced: Use nested subtrees for versioning
+active_resume_path_en: "2025-06.20250621-PM"
+active_resume_path_ar: "2025-06.20250621-PM"
 # resume_data.experience == site.data['2025-06']['20250621-PM'].experience
+
+# 3) Advanced: Use files directly under _data/ (not recommended for beginners)
+active_resume_path_en: ""
+active_resume_path_ar: ""
+# resume_data.experience == site.data.experience
+# Only use this if you place files directly in _data/ root (advanced users only)
 ```
 
 ---
@@ -146,7 +159,7 @@ active_resume_path: 2025-06.20250621-PM
   - Small inline icons are included from `vendors/lineicons-v4.0/`
 - Title bar with `site.resume_title` (or `resume_title_ar` for AR)
 - Social icon list when `site.social_links` is configured (see `_includes/social-links.html`)
-- Executive summary from `site.resume_header_intro`
+- Executive summary (controlled by `resume_header_intro_en`/`resume_header_intro_ar` flags, reads from `resume_data.header.intro`)
 - CTA button controlled by `site.resume_looking_for_work`
 
 ### 3) Dynamic section rendering
@@ -180,7 +193,8 @@ name:
   last: "Last"
 resume_title: "Job Title"
 resume_title_ar: "المسمّى الوظيفي"
-resume_header_intro: "Short executive summary paragraph."
+resume_header_intro_en: true  # Enable English intro (reads from resume_data.header.intro)
+resume_header_intro_ar: true  # Enable Arabic intro (reads from resume_data.header.intro)
 resume_avatar: true
 
 # Header contact toggles
@@ -236,8 +250,9 @@ resume_section_order:
 # Print behavior
 resume_print_social_links: true
 
-# Active data subtree for resume_data
-active_resume_path: ""
+# Active data subtree for resume_data (separate for each language)
+active_resume_path_en: "en"
+active_resume_path_ar: "ar"
 ```
 
 Per-page front matter (for multilingual SEO):
@@ -304,8 +319,8 @@ Tip: Keep date formatting and “present” text consistent with the target lang
 ## Common pitfalls and troubleshooting
 
 - Sections not rendering? Check `resume_section_order`, `resume_section.<name>` flags, and `active: true` on data items.
-- Wrong data showing? Confirm `active_resume_path` and your `_data/` structure.
-- Arabic months not displayed? Ensure `site.data.ar.months` is defined (see includes guide: `ar-date.html`).
+- Wrong data showing? Confirm `active_resume_path_en`/`active_resume_path_ar` and your `_data/` structure.
+- Arabic months not displayed? The theme includes `_data/ar/months.yml` by default. If you're using a custom data path, ensure `site.data.ar.months` is accessible (see includes guide: `ar-date.html`).
 - Icons missing? Verify the SVG exists under `/_includes/vendors/lineicons-*/` and the include path is correct.
 - SEO alternates missing? Ensure both pages share the same `t_id`, and each has a `lang` value.
 

data/docs/PROJECT_OVERVIEW.md

@@ -0,0 +1,69 @@
+## Project overview
+
+**bilingual-jekyll-resume-theme** is a Jekyll theme for creating bilingual (English & Arabic) resumes. Created by Khaldoon Mutahar.
+
+## Features
+
+1. Bilingual support
+   - Separate layouts for English (`_layouts/resume-en.html`) and Arabic (`_layouts/resume-ar.html`)
+   - RTL support for Arabic (SCSS in `_sass/_resume-rtl.scss`)
+   - Arabic date formatting via `_includes/ar-date.html` (uses `_data/ar/months.yml`)
+   - Separate name fields objects: `site.name.{first,middle,last}` and `site.name_ar.{first,middle,last}`
+   - Optional language chips in header via `resume_section.lang_header`
+
+2. Data-driven architecture
+   - Resume content in YAML files in `_data/`
+   - Supports nested data folders (e.g., `_data/en/`, `_data/ar/`, or versioned/custom paths)
+   - Dynamic data loader (in both layouts) resolves dot-separated paths using bracket notation, e.g., `"2025-06.20250621-PM"`
+   - Configurable data paths via `_config.yml` keys `active_resume_path_en` and `active_resume_path_ar`
+
+3. Resume sections (13 types)
+   - Experience, Education, Certifications, Courses, Volunteering, Projects, Skills, Recognition, Associations, Languages, Links, Interests, Header (Executive Summary)
+   - Ordering via `resume_section_order` and toggles via `resume_section.*` in `_config.yml`
+   - Active/inactive flags per entry across all sections
+
+4. Design and UX
+   - Print-friendly styling (print-only/no-print classes); optional print-only social links block
+   - Social links integration via `_includes/social-links.html` (GitHub, LinkedIn, X, YouTube, etc.)
+   - SVG icon set via Lineicons (bundled in `_includes/vendors/lineicons-*`)
+   - Profile avatar support
+   - Header contact info toggle (`display_header_contact_info`)
+   - Live vs print contact info (`enable_live`) for phone/email variants
+   - "Looking for work" contact button
+   - Languages can appear in header or separate section
+
+5. Technical features
+   - Jekyll 4.4+ compatibility
+   - SEO via `jekyll-seo-tag`; alternate language links via `_includes/hreflang.html`
+   - Analytics hooks in head/body includes (Google Tag Manager/GA4 supported)
+   - Sitemap and feed generation (`jekyll-sitemap`, `jekyll-feed`), redirects via `jekyll-redirect-from`
+   - Schema.org markup for `Person` and various sections
+
+## Project structure
+
+- `_layouts/`: HTML templates (`default.html`, `resume-en.html`, `resume-ar.html`, `profile.html`)
+- `_includes/`: Reusable components (sections, headers, social links, analytics, `hreflang.html`, SVG vendors)
+- `_sass/`: SCSS stylesheets (base, layout, resume, RTL, print)
+- `_data/`: Theme data files (Arabic month names in `ar/months.yml`)
+- `assets/`: CSS, images, favicons
+- `docs/`: Documentation (config, data, includes, layouts, SASS guides) and sample `_data/` content
+
+## Notable implementation details
+
+1. Dynamic data loading: In both `resume-en.html` and `resume-ar.html`, Liquid bracket notation iterates over a dot-separated path to resolve nested data objects (handles numeric or hyphenated keys like `"2025-06"`).
+2. Conditional rendering: Sections render from `resume_section_order` and respect per-section toggles and data availability; optional header intro blocks (`resume_header_intro_en`/`_ar`).
+3. Date formatting: Arabic dates via `_includes/ar-date.html` with month name lookup from `_data/ar/months.yml`.
+4. Print behavior: Print-only URL echoes for links and optional print-only social links block.
+
+## Documentation
+
+Includes guides for:
+- Configuration (`docs/CONFIG_GUIDE.md`)
+- Data structure (`docs/DATA_GUIDE.md`)
+- Includes (`docs/INCLUDES_GUIDE.md`)
+- Layouts (`docs/LAYOUTS_GUIDE.md`)
+- SASS (`docs/SASS_GUIDE.md`)
+
+Sample data is provided under `docs/_data/en/` and `docs/_data/ar/` and a sample `_config` at `docs/_data/_config.sample.yml`.
+
+The theme is production-ready and well-documented for creating bilingual resumes with Jekyll.

data/docs/SASS_GUIDE.md

@@ -1,6 +1,8 @@
 # SCSS/SASS Guide (_sass)
 
-A contributor- and user-friendly tour of the theme’s styling system: how styles are organized, how entrypoints compile, what each partial does, and safe ways to customize or extend.
+A contributor- and user-friendly tour of the theme's styling system: how styles are organized, how entrypoints compile, what each partial does, and safe ways to customize or extend.
+
+**For beginners:** This guide explains how the theme's CSS/SCSS works. If you're new to CSS or just want to change colors/fonts, start with the [Customization recipes](#customization-recipes) section. You can override styles without modifying the theme files directly.
 
 ---
 

data/docs/{_config.sample.yml → _data/_config.sample.yml}

@@ -72,7 +72,8 @@ active_resume_path_ar: "ar" # ath to Arabic data (empty = root _data/)
 # Header and intro
 resume_avatar: true # Show profile picture
 display_header_contact_info: true # Show contact info in header
-resume_header_intro: "<p>Your professional summary or elevator pitch goes here.</p>"
+resume_header_intro_en: true # Show English intro paragraph below name/title in header
+resume_header_intro_ar: false # Show Arabic intro paragraph below name/title in header
 
 # Job search status
 # use "true" to display the email contact button,

data/docs/_data/ar/associations.yml

@@ -0,0 +1,27 @@
+# العضويات
+# الملف: _data/ar/associations.yml
+# المنظمات أو المجموعات المهنية أو العضويات
+
+# كل إدخال يمثل عضوية أو جمعية
+- organization: ""  # مطلوب: اسم المنظمة
+  active: true      # مطلوب: اضبط على false لإخفاء هذا الإدخال
+  role: ""          # مطلوب: دورك/منصبك في المنظمة
+  year: ""          # مطلوب: الفترة الزمنية (كنص عرض، مثلاً "2020 — الحاضر" أو "يوليو 2022 — الحاضر")
+  url: ""           # اختياري: رابط المنظمة (اتركه فارغاً إذا لم يكن هناك رابط)
+  summary: ""       # اختياري: وصف لانخراطك
+
+# مثال مع رابط
+- organization: ""
+  active: true
+  role: ""
+  year: ""
+  url: "https://example.com"
+  summary: ""
+
+# مثال بدون رابط
+- organization: ""
+  active: true
+  role: ""
+  year: ""
+  url: ""
+  summary: ""

data/docs/_data/ar/certifications.yml

@@ -0,0 +1,73 @@
+# الشهادات والتراخيص
+# الملف: _data/ar/certifications.yml
+# الشهادات والتراخيص المهنية
+
+# كل إدخال يمثل شهادة أو ترخيص
+- name: ""                    # مطلوب: اسم الشهادة
+  active: true                # مطلوب: اضبط على true للعرض في السيرة الذاتية، false للإخفاء
+  issuing_organization: ""    # مطلوب: المنظمة التي أصدرت الشهادة
+  credential_id: ""          # اختياري: رقم اعتماد/شهادة (اتركه فارغاً إذا لم يكن هناك)
+  credential_url: ""          # اختياري: رابط للتحقق من الاعتماد (اتركه فارغاً إذا لم يكن هناك)
+  issue_date:                 # مطلوب: تاريخ الإصدار (تنسيق YYYY-MM-DD، مثلاً 2024-03-15)
+  expiration:                 # اختياري: تاريخ الانتهاء (تنسيق YYYY-MM-DD، اتركه فارغاً إذا لم يكن هناك تاريخ انتهاء)
+  courses:                    # اختياري: للاستخدام الداخلي فقط - لا يتم عرضه في السيرة الذاتية
+                              # هذه الدورات المتداخلة هي للاحتفاظ بالسجلات الشخصية فقط
+                              # تربط الدورات بشهادتها الأصلية ولكن لا يتم عرضها أبداً
+    - name: ""               # اسم الدورة (للسجلات الشخصية فقط)
+      active: false           # حالة النشاط (للسجلات الشخصية فقط)
+      issuing_organization: "" # المنظمة (للسجلات الشخصية فقط)
+      credential_id: ""       # رقم الاعتماد (للسجلات الشخصية فقط)
+      credential_url: ""      # رابط الاعتماد (للسجلات الشخصية فقط)
+      issue_date:             # تاريخ الإصدار (تنسيق YYYY-MM-DD، للسجلات الشخصية فقط)
+      expiration:             # تاريخ الانتهاء (تنسيق YYYY-MM-DD، اتركه فارغاً إذا لم يكن هناك، للسجلات الشخصية فقط)
+
+# مثال مع رقم اعتماد ورابط
+- name: ""
+  active: true
+  issuing_organization: ""
+  credential_id: ""
+  credential_url: "https://example.com/cert/123"
+  issue_date:
+  expiration:
+  courses:
+    - name: ""
+      active: false
+      issuing_organization: ""
+      credential_id: ""
+      credential_url: ""
+      issue_date:
+      expiration:
+
+# مثال مع رقم اعتماد بدون رابط
+- name: ""
+  active: true
+  issuing_organization: ""
+  credential_id: ""
+  credential_url: ""
+  issue_date:
+  expiration:
+  courses:
+    - name: ""
+      active: false
+      issuing_organization: ""
+      credential_id: ""
+      credential_url: ""
+      issue_date:
+      expiration:
+
+# مثال بدون تاريخ انتهاء
+- name: ""
+  active: true
+  issuing_organization: ""
+  credential_id: ""
+  credential_url: ""
+  issue_date:
+  expiration:
+  courses:
+    - name: ""
+      active: false
+      issuing_organization: ""
+      credential_id: ""
+      credential_url: ""
+      issue_date:
+      expiration: