bilingual-jekyll-resume-theme 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82f9ca0be84e6576a493181eb0efe5878302db7196f3843f8468d2048a975995
-  data.tar.gz: 9b477efb312e3a1e6d71c3ac8e6ab4e95c04f3a2053ec7042412fc659b6148df
+  metadata.gz: 6a564ca7ea40cba9ce7787387ec40f652ba6d372c20efc4e1ea7d4ca96c7fc07
+  data.tar.gz: f1bda2da34e9b4655a74a4e08657cb56ae52b8d735bb42e705c59c369fd1bd29
 SHA512:
-  metadata.gz: 4cb13f53c7a175d3e353ad4bf169786d314c79c838b0aafafba6d57fec578b82fecf5171ae4cbac95f9c2ea2080146e7ae74d0b8067e4c834932af60c4172325
-  data.tar.gz: 14a87ccc8f9ed64072ac5b210ed74e0047753a274987e2fd52c527cb728c7bb2f6e3aab22a091299051b8bdefbd8387966b524d0f61302ef835516fee4f9b19f
+  metadata.gz: da02b5f0d81a45531f55151bc1eec5eb9bf0acb74229d40cac47a41a452bfac4c6da21f0ee970930e5b4b40128b56189978c01809301f0673c1ba94e88c0b9fd
+  data.tar.gz: ae3a25641c914cfd40894c7484453aa6535cc61f906f9c4c0ffb6653736534fe424ff7d27ccaa859bd1defb0315407950b8c60ed43b9b5dcf48fc246144ebfe5

data/CHANGELOG.md

@@ -4,6 +4,48 @@ 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.5.0] - 2025-11-06
+
+### Added
+* Add sample configuration file for bilingual Jekyll resume theme ([`ce25360`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/ce25360b10bcc8bd1a26e4d3b3abb20a9f0d4e04))
+
+* Add conditional Mastodon link for social verification ([`5bb7f62`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/5bb7f62586871c904df10003fe17f5f9fce9fce4))
+
+* Add default Arabic months i18n files ([`1c3cac6`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/1c3cac6c4f0179f0447c746d6d950c3addc33907))
+
+
+### Changed
+* Add project overview for bilingual Jekyll resume theme ([`6708f50`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/6708f50bc84a6dd62fb7f77e5ed7797d7a97bd08))
+
+* Revise README for bilingual Jekyll resume theme ([`7efff88`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/7efff88b81d48aa9fac5d70cd4501e05f888e1db))
+
+* Update configuration and data guides for bilingual resume theme ([`9c0f9e9`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/9c0f9e9c20633970ffeb795cc6bd581caf7a4e62))
+
+* Add Arabic and English resume data samples ([`a86a668`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/a86a6680bb1384bc58053b502157aa0ae568a039))
+
+* Enhance ar-date include with detailed comments and usage instructions ([`5f297d1`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/5f297d1f2184b24e7feef8257a8bd9d73295d321))
+
+* Update bilingual-jekyll-resume-theme.gemspec ([`ca84a88`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/ca84a886bcdb7d8a41c1ed60dffd477207db9739))
+
+* Rename CODE_OF_CONDUCT.MD to CODE_OF_CONDUCT.md ([`127813b`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/127813b4f6acb867dff576977b899d1b46d20241))
+
+* Use ar-date include for Date of Birth ([`0b2ec85`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/0b2ec854638e9ceaefddc5b87f6a855cdeb0b596))
+
+## [0.4.0] - 2025-11-05
+
+### Added
+* Add logger as explicit dependency ([`327702b`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/327702beb3383375172401d8f5869ee3ab3f50a9))
+
+
+### Changed
+* Move intro text from _config to data file ([`d026de9`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/d026de92817b3de76843e18b8770c20136ae0691))
+
+* Make summary optional in association.yml ([`a12cdc8`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/a12cdc8b9d64db5c3368db6dc270c03a4f353538))
+
+* Make summary optional in recognition.yml ([`34b4661`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/34b46613dc561a3d1868fdf8d64f7cfd80e02e5d))
+
+* Make description optional in skills.yml ([`601dbf9`](https://github.com/kmutahar/bilingual-jekyll-resume-theme/commit/601dbf9d81a621366d3a0e46f7079da42aa73e75))
+
 ## [0.3.1] - 2025-11-03
 
 ### Added
@@ -83,6 +125,8 @@ 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.5.0]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/kmutahar/bilingual-jekyll-resume-theme/compare/v0.1.1...v0.2.0

data/README.md

@@ -1,50 +1,161 @@
 # bilingual-jekyll-resume-theme
 
-Welcome to your new Jekyll theme! In this directory, you'll find the files you need to be able to package up your theme into a gem. Put your layouts in `_layouts`, your includes in `_includes`, your sass files in `_sass` and any other assets in `assets`.
+[![Latest release](https://img.shields.io/github/v/release/kmutahar/bilingual-jekyll-resume-theme?display_name=tag)](https://github.com/kmutahar/bilingual-jekyll-resume-theme/releases) [![Gem Version](https://badge.fury.io/rb/bilingual-jekyll-resume-theme.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/bilingual-jekyll-resume-theme)
 
-To experiment with this code, add some sample content and run `bundle exec jekyll serve` – this directory is setup just like a Jekyll site!
+A flexible Jekyll theme for creating clean, data-driven, bilingual (English & Arabic) resume/CV websites. Created and maintained by Khaldoon Mutahar. See the latest version on the [Releases page](https://github.com/kmutahar/bilingual-jekyll-resume-theme/releases).
+Inspired by and originally forked from [Joel Glovier’s resume template](https://github.com/jglovier/resume-template/). Joel’s version was a basic English-only theme with limited customization (e.g., no section reordering); this project has since evolved into a fully separate theme authored by Khaldoon.
 
-TODO: Delete this and the text above, and describe your gem
+## Features
 
-## Installation
+- **Bilingual support**: Separate layouts for English (`resume-en.html`) and Arabic (`resume-ar.html`) with full RTL support
+- **Data-driven architecture**: All resume content stored in YAML files, supporting multiple data paths and versioning
+- **12 resume sections**: Experience, Education, Certifications, Courses, Volunteering, Projects, Skills, Recognition, Associations, Languages, Links, Interests
+- **Print-friendly**: Optimized for PDF generation and printing
+- **SEO ready**: Built-in support for multilingual SEO, sitemap, and feed generation
+- **Arabic month support**: Arabic date formatting included out of the box (`_data/ar/months.yml`)
 
-Add this line to your Jekyll site's `Gemfile`:
+## Quick Start
 
+### Installation
+
+1. Add to your Jekyll site's `Gemfile`:
 ```ruby
 gem "bilingual-jekyll-resume-theme"
 ```
 
-And add this line to your Jekyll site's `_config.yml`:
-
+2. Add to your `_config.yml`:
 ```yaml
 theme: bilingual-jekyll-resume-theme
 ```
 
-And then execute:
+3. Install dependencies:
+```bash
+bundle install
+```
+
+### Basic Setup
+
+1. **Copy sample configuration**: Use `docs/_data/_config.sample.yml` as a starting point for your `_config.yml`
 
-    $ bundle
+2. **Copy sample data files**: 
+   - English data: Copy files from `docs/_data/en/` to your `_data/en/` directory (includes `header.yml` for the intro paragraph)
+   - Arabic data: Copy files from `docs/_data/ar/` to your `_data/ar/` directory (includes `header.yml` for the Arabic intro paragraph)
 
-Or install it yourself as:
+3. **Create resume pages**: Create pages using the `resume-en` and `resume-ar` layouts:
+```yaml
+---
+layout: resume-en
+permalink: /resume/en/
+lang: en
+t_id: resume
+---
+```
 
-    $ gem install bilingual-jekyll-resume-theme
+4. **Run the development server**:
+```bash
+bundle exec jekyll serve
+```
 
-## Usage
+Visit `http://localhost:4000` to see your resume!
 
-TODO: Write usage instructions here. Describe your available layouts, includes, sass and/or assets.
+## Documentation
 
-## Contributing
+This theme is fully documented. Choose the guide that fits your needs:
+
+### 📘 [Configuration Guide](docs/CONFIG_GUIDE.md)
+Complete guide to `_config.yml` settings. Learn how to configure sections, contact info, social links, analytics, and more. **Start here for beginners.**
+
+### 📊 [Data Structure Guide](docs/DATA_GUIDE.md)
+Detailed documentation of all 12 data file types (experience, education, skills, etc.) with examples. Learn how to structure your YAML files and what fields are required vs optional.
+
+### 🎨 [Layouts Guide](docs/LAYOUTS_GUIDE.md)
+Deep dive into how layouts work, how data flows through them, and how to create custom layouts. Useful for advanced customization.
+
+### 🧩 [Includes Guide](docs/INCLUDES_GUIDE.md)
+Understanding the theme's include system, how sections render, and how to add new sections or customize existing ones.
+
+### 🎨 [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 Structure
+
+```
+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)
+├── assets/            # CSS, images, favicons
+└── docs/              # Documentation and sample files
+    ├── _data/         # Sample data files (copy to your site's _data/)
+    └── *.md           # Documentation guides
+```
+
+## Key Concepts
+
+### Data Paths
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/bilingual-jekyll-resume-theme. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](https://www.contributor-covenant.org/) code of conduct.
+**Recommended approach (for beginners):** Use language-specific folders. The theme supports separate data paths for English and Arabic:
+```yaml
+active_resume_path_en: "en"  # Uses _data/en/* (recommended)
+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.
+
+### Sample Files
+
+The theme includes sample data files in `docs/_data/en/` and `docs/_data/ar/` that you can copy to your site. These files contain:
+- Commented examples for all 12 section types
+- Required vs optional field explanations
+- Multiple examples per section
+
+### Arabic Month Support
+
+The theme includes `_data/ar/months.yml` with Arabic month names already configured. You don't need to create this file manually—it's included in the theme.
 
 ## Development
 
-To set up your environment to develop this theme, run `bundle install`.
+To develop this theme locally:
+
+```bash
+# Install dependencies
+bundle install
+
+# Run development server
+bundle exec jekyll serve
 
-Your theme is setup just like a normal Jekyll site! To test your theme, run `bundle exec jekyll serve` and open your browser at `http://localhost:4000`. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.
+# Build the gem
+gem build bilingual-jekyll-resume-theme.gemspec
+```
+
+For more details, see [WARP.md](WARP.md) or the [Development section](#development) below.
+
+## Requirements
+
+- Jekyll 4.4+ (specified in `bilingual-jekyll-resume-theme.gemspec`)
+- Required plugins (automatically included):
+  - `jekyll-feed`
+  - `jekyll-seo-tag`
+  - `jekyll-sitemap`
+  - `jekyll-redirect-from`
+
+## Contributing
 
-When your theme is released, only the files in `_layouts`, `_includes`, `_sass` and `assets` tracked with Git will be bundled.
-To add a custom directory to your theme-gem, please edit the regexp in `bilingual-jekyll-resume-theme.gemspec` accordingly.
+Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](https://www.contributor-covenant.org/) code of conduct.
 
 ## License
 
-The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The theme is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+## Support
+
+- 📖 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
+
+---
+
+**Created by Khaldoon Mutahar** | Version 0.4.0 | MIT License

data/_data/ar/months.yml

@@ -0,0 +1,12 @@
+"1": يناير
+"2": فبراير
+"3": مارس
+"4": أبريل
+"5": مايو
+"6": يونيو
+"7": يوليو
+"8": أغسطس
+"9": سبتمبر
+"10": أكتوبر
+"11": نوفمبر
+"12": ديسمبر

data/_includes/ar-date.html

@@ -1,7 +1,39 @@
+{% 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.
+
+  Usage:
+    {% include ar-date.html date=page.date style="MDY" %}
+    {% include ar-date.html date=page.date %}
+
+  Parameters:
+    - date: The date to format (required)
+    - style: "MDY" for "Month Day, Year" format, or any other value for "Month Year" format (optional)
+{% endcomment %}
+
+{% comment %}
+  Extract date components from the provided date using Jekyll date filters:
+  - "%-m": Month as a number (1-12) without leading zeros
+  - "%-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" %}
+
+{% 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] %}
+
+{% 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 %}

data/_includes/resume-section-ar.html

@@ -200,7 +200,7 @@
         {% for project in resume_data.projects %}
             {% if project.active == true %}
                 <div class="resume-item" itemscope itemtype="http://schema.org/CreativeWork">
-                    <meta itemprop="creator" content="{{ site.name_ar.first }} {{ site.name_ar.middle }} {{ site.name_ar.last }}" itemtype="http://schema.org/Person" />
+                    <meta itemprop="creator" content="{{ site.name.first }} {{ site.name.middle }} {{ site.name.last }}" itemtype="http://schema.org/Person" />
                     <h3 class="resume-item-title" itemprop="name" style="display: inline-block;">
                         {% if project.url %}
                             <a href="{{ project.url }}" target="_blank" rel="noopener nofollow noreferrer" itemprop="url">{{ project.project }}</a>
@@ -232,7 +232,9 @@
             {% if skill.active == true %}
                 <div class="resume-item">
                     <h4 class="resume-item-details">{{ skill.skill }}</h4>
-                    <p class="resume-item-copy">{{ skill.description }}</p>
+                    {% if skill.description %}
+                        <p class="resume-item-copy">{{ skill.description }}</p>
+                    {% endif %}
                 </div>
             {% endif %}
         {% endfor %}
@@ -251,7 +253,9 @@
                 <div class="resume-item">
                     <h3 class="resume-item-title" itemprop="award">{{ recognition.award }}</h3>
                     <h4 class="resume-item-details">{{ recognition.organization }} &bull; {{ recognition.year }}</h4>
-                    <p class="resume-item-copy">{{ recognition.summary }}</p>
+                    {% if recognition.summary %}
+                        <p class="resume-item-copy">{{ recognition.summary }}</p>
+                    {% endif %}
                 </div>
             {% endif %}
         {% endfor %}
@@ -281,7 +285,9 @@
                     {% endif %}
 
                     <h4 class="resume-item-details" itemprop="description">{{ association.role }} &bull; {{ association.year }}</h4>
-                    <p class="resume-item-copy">{{ association.summary }}</p>
+                    {% if association.summary %}
+                        <p class="resume-item-copy">{{ association.summary }}</p>
+                    {% endif %}
                 </div>
             {% endif %}
         {% endfor %}

data/_includes/resume-section-en.html

@@ -232,8 +232,9 @@
             {% if skill.active == true %}
                 <div class="resume-item">
                     <h4 class="resume-item-details">{{ skill.skill }}</h4>
-                    <p class="resume-item-copy">{{ skill.description }}</p>
-                </div>
+                    {% if skill.description %}
+                        <p class="resume-item-copy">{{ skill.description }}</p>
+                    {% endif %}                </div>
             {% endif %}
         {% endfor %}
     </section>
@@ -251,7 +252,9 @@
                 <div class="resume-item">
                     <h3 class="resume-item-title" itemprop="award">{{ recognition.award }}</h3>
                     <h4 class="resume-item-details">{{ recognition.organization }} &bull; {{ recognition.year }}</h4>
-                    <p class="resume-item-copy">{{ recognition.summary }}</p>
+                    {% if recognition.summary %}
+                        <p class="resume-item-copy">{{ recognition.summary }}</p>
+                    {% endif %}
                 </div>
             {% endif %}
         {% endfor %}
@@ -281,7 +284,9 @@
                     {% endif %}
 
                     <h4 class="resume-item-details" itemprop="description">{{ association.role }} &bull; {{ association.year }}</h4>
-                    <p class="resume-item-copy">{{ association.summary }}</p>
+                    {% if association.summary %}
+                        <p class="resume-item-copy">{{ association.summary }}</p>
+                    {% endif %}
                 </div>
             {% endif %}
         {% endfor %}

data/_layouts/default.html

@@ -21,8 +21,10 @@
         <!-- Analytics head snippet (GTM or gtag). Configured in _config.yml -->
         {% include analytics-head.html %}
 
+        {% if site.social_links.mastodon %}
         <!-- rel="me" for Mastodon verification / IndieAuth -->
         <link rel="me" href="{{ site.social_links.mastodon }}">
+        {% endif %}
     </head>
 
     <body>

data/_layouts/resume-ar.html

@@ -205,7 +205,7 @@ resume_data.experience == site.data['2025-06']['20250621-PM'].experience
                             {% endif %}
 
                             {% if site.contact_info.dob %}
-                                  تاريخ الميلاد: {{ site.contact_info.dob | date_to_long_string }}
+                                  تاريخ الميلاد: {% include ar-date.html date=site.contact_info.dob style="MDY" %}
                             {% endif %}
 
                             {% assign active_languages = resume_data.languages | where: "active", true %}
@@ -235,9 +235,11 @@ resume_data.experience == site.data['2025-06']['20250621-PM'].experience
                     {% endif %}
                 </div>
 
+                {% if site.resume_header_intro_ar == true %}
                 <div class="executive-summary" itemprop="description">
-                    {{ site.resume_header_intro }}
+                    <p>{{ resume_data.header.intro }}</p>
                 </div>
+                {% endif %}
 
                 {% if site.resume_looking_for_work == true %}
                     <a href="mailto:{{ site.contact_info.email }}" class="contact-button no-print" itemprop="email">تواصل معي</a>

data/_layouts/resume-en.html

@@ -235,9 +235,11 @@ resume_data.experience == site.data['2025-06']['20250621-PM'].experience
                     {% endif %}
                 </div>
 
+                {% if site.resume_header_intro_en == true %}
                 <div class="executive-summary" itemprop="description">
-                    {{ site.resume_header_intro }}
+                    <p>{{ resume_data.header.intro }}</p>
                 </div>
+                {% endif %}
 
                 {% if site.resume_looking_for_work == true %}
                     <a href="mailto:{{ site.contact_info.email }}" class="contact-button no-print" itemprop="email">Contact me</a>

data/docs/CONFIG_GUIDE.md

@@ -24,6 +24,8 @@ Make your site render correctly with this theme. This guide matches the shipped
 
 ## Quick start
 
+**For beginners:** This guide explains every setting in `_config.yml`. Start with the basics below, then add more sections as you need them. You can find sample configuration files in `docs/_data/_config.sample.yml` and sample data files in `docs/_data/en/` and `docs/_data/ar/`.
+
 Copy, paste, and customize the ALL-CAPS values:
 
 ```yaml
@@ -89,30 +91,39 @@ That’s enough to render a working resume using data from `_data/`.
 
 The layouts read resume data from a subtree of `_data/` using dot-separated paths.
 
-- active_resume_path_en: Path for English pages.
-- active_resume_path_ar: Path for Arabic pages.
-- If the value is an empty string (`""`) or not set, the root of `_data/` is used.
+**Recommended approach (for beginners):** Use language-specific folders. Set `active_resume_path_en: "en"` and `active_resume_path_ar: "ar"` to use `_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 approach:** If you place files directly in `_data/` (root), set `active_resume_path_en: ""` and `active_resume_path_ar: ""`. This approach is not recommended for beginners.
+
+- active_resume_path_en: Path for English pages (recommended: `"en"` for `_data/en/`).
+- active_resume_path_ar: Path for Arabic pages (recommended: `"ar"` for `_data/ar/`).
+- If the value is an empty string (`""`) or not set, the root of `_data/` is used (advanced users only).
 
 Examples:
 
 ```yaml
-active_resume_path_en: "en"          # -> uses _data/en/*
-active_resume_path_ar: "ar"          # -> uses _data/ar/*
-# Nested example:
+# Recommended: Use language-specific folders
+active_resume_path_en: "en"          # -> uses _data/en/* (recommended for beginners)
+active_resume_path_ar: "ar"          # -> uses _data/ar/* (recommended for beginners)
+
+# Advanced: Nested example for versioning
 active_resume_path_en: "2025-06.PM"   # -> uses _data/2025-06/PM/*
-# Root example (use files directly under _data/ not suggested unless using one language only):
+
+# Advanced: Root example (not recommended for beginners)
+# Only use this if you place files directly under _data/ (not in language folders)
 active_resume_path_en: ""
 active_resume_path_ar: ""
 ```
 
-Note: This theme uses the two keys above (there is no single `active_resume_path`).
+**Note:** This theme uses the two keys above (there is no single `active_resume_path`). For beginners, always use `"en"` and `"ar"` to keep your data organized in language folders.
 
 ---
 
 ## Header and contact
 
 - resume_avatar (bool): Show/hide avatar in the header.
-- resume_header_intro (HTML string): Short paragraph under your header; basic HTML supported.
+- resume_header_intro_en (bool): Enable/disable the English intro paragraph below name/title. When enabled, reads from `resume_data.header.intro` (create `_data/en/header.yml` with an `intro:` field). **Recommended:** Use `_data/en/header.yml` for English.
+- resume_header_intro_ar (bool): Enable/disable the Arabic intro paragraph below name/title. When enabled, reads from `resume_data.header.intro` (create `_data/ar/header.yml` with an `intro:` field). **Recommended:** Use `_data/ar/header.yml` for Arabic.
 - resume_looking_for_work (bool | omitted):
   - true → Shows “Contact me” button using `contact_info.email`.
   - false → Shows a neutral “I’m not looking for work” pill.
@@ -146,8 +157,9 @@ Helpful toggles:
 
 - resume_title_ar: Arabic job title for the Arabic layout.
 - address_ar: Arabic address line for the Arabic header contact row.
-- Arabic dates: `_includes/ar-date.html` expects `site.data.ar.months` to map 1–12 to Arabic month names (define in `_data/ar.yml` or `_data/ar/months.yml`).
-- Present text: English shows “Present”; Arabic shows “حتى الآن”.
+- Arabic dates: `_includes/ar-date.html` expects `site.data.ar.months` to map 1–12 to Arabic month names. **The theme already includes `_data/ar/months.yml`, so you don't need to create this file manually.**
+- Present text: English shows "Present"; Arabic shows "حتى الآن".
+- Header intro: To add an intro paragraph below your name/title, create `_data/en/header.yml` for English (or `_data/ar/header.yml` for Arabic) with an `intro:` field containing your text. Then enable `resume_header_intro_en: true` or `resume_header_intro_ar: true` in `_config.yml`. **Recommended:** Always use language-specific folders (`_data/en/` and `_data/ar/`). Sample files are available in `docs/_data/en/header.yml` and `docs/_data/ar/header.yml`.
 
 ---
 
@@ -228,7 +240,8 @@ contact_info:
 
 display_header_contact_info: true
 resume_avatar: true
-resume_header_intro: "<p>Building products customers love through clear strategy and measurable outcomes.</p>"
+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_looking_for_work: true
 
 # Data paths
@@ -316,6 +329,8 @@ exclude:
 - Contact button shows but nothing happens.
   - Set `contact_info.email` or set `resume_looking_for_work: false`.
 - Arabic months appear as numbers.
-  - Define Arabic month names under `site.data.ar.months` (e.g., `_data/ar/months.yml`).
+  - The theme includes `_data/ar/months.yml` by default. If you're using a custom data path, ensure `site.data.ar.months` is accessible.
+- Header intro not showing.
+  - Enable `resume_header_intro_en: true` or `resume_header_intro_ar: true` in `_config.yml`, and create `_data/en/header.yml` (or `_data/ar/header.yml` for Arabic) in your active data path with an `intro:` field. You can copy sample files from `docs/_data/en/header.yml` and `docs/_data/ar/header.yml`.
 - Data for EN/AR lives in different folders.
   - Point `active_resume_path_en` and `active_resume_path_ar` at the right subtrees (e.g., `en` and `ar`).