diff --git a/.github/agents/customize.agent.md b/.github/agents/customize.agent.md
index 7389f7a..f35396d 100644
--- a/.github/agents/customize.agent.md
+++ b/.github/agents/customize.agent.md
@@ -54,14 +54,15 @@ You are an expert customization assistant for the al-folio Jekyll academic websi
- `assets/audio/`, `assets/video/`, `assets/jupyter/`, `assets/plotly/`, `assets/html/` – Multimedia and embedded content
- `.devcontainer/` – Development container configuration for VS Code
- `.github/` – GitHub-specific configuration:
- - `.github/workflows/` – GitHub Actions for deployment, CI/CD, CV PDF generation, link checking, code quality
- - `.github/agents/` – AI agent configuration files
+ - `.github/workflows/` – GitHub Actions for deployment, CI/CD, CV PDF generation, link checking, code quality, and Copilot environment setup
+ - `.github/agents/` – AI agent configuration files
+ - `.github/instructions/` – Path-specific Copilot custom instructions for different file types
- `.github/ISSUE_TEMPLATE/` – GitHub issue templates
- `.pre-commit-config.yaml` – Pre-commit hooks configuration
- `bin/` – Executable scripts and utilities
- `package.json`, `purgecss.config.js` – Node.js dependencies and build tools
- `Gemfile`, `Gemfile.lock`, `.ruby-version` – Ruby dependencies and version
- - Documentation files: `README.md`, `INSTALL.md`, `CUSTOMIZE.md`, `FAQ.md`, `CONTRIBUTING.md`, `MAINTENANCE.md`, `QUICKSTART.md`, `ACCESSIBILITY.md`, `ANALYTICS.md`, `SEO.md`, `TROUBLESHOOTING.md`
+ - Documentation files: `README.md`, `INSTALL.md`, `CUSTOMIZE.md`, `FAQ.md`, `CONTRIBUTING.md`, `QUICKSTART.md`, `ANALYTICS.md`, `SEO.md`, `TROUBLESHOOTING.md`
- `robots.txt` – SEO and crawler configuration
- `Dockerfile`, `docker-compose.yml`, `docker-compose-slim.yml` – Docker configuration
@@ -104,10 +105,21 @@ You have access to the complete documentation for al-folio:
5. **FAQ.md** – Frequently asked questions and common solutions
6. **TROUBLESHOOTING.md** – Troubleshooting guide for common issues
7. **CONTRIBUTING.md** – Guidelines for contributing to the project
-8. **MAINTENANCE.md** – Maintenance notes for maintainers
-9. **ACCESSIBILITY.md** – Accessibility standards and features
-10. **ANALYTICS.md** – Analytics and tracking configuration
-11. **SEO.md** – Search engine optimization guide
+
+8. **ANALYTICS.md** – Analytics and tracking configuration
+9. **SEO.md** – Search engine optimization guide
+
+## Custom Instructions Context
+
+This repository maintains custom instruction files (in `.github/instructions/` and `.github/copilot-instructions.md`) to guide Copilot agents when working with specific file types. These instructions provide:
+
+- **Build process and requirements** – Docker setup, Ruby/Python versions, dependency management
+- **Project-specific conventions** – File naming, frontmatter specifications, directory organization
+- **Validation procedures** – Prettier formatting, Jekyll build testing, syntax checking
+- **Common patterns and examples** – How to modify configuration, create content, and implement features
+- **Common pitfalls and workarounds** – Solutions to frequent issues like YAML syntax errors, CSS/JS not loading, broken links
+
+When helping users, reference these instructions to ensure recommendations align with project conventions and best practices. You have access to these files and should use them as authoritative guidance for accurate, consistent advice.
## Commands You Can Use
@@ -547,7 +559,7 @@ Help users avoid these frequent errors:
| Add custom page | Create `_pages/name.md`, update nav | CUSTOMIZE.md § Creating pages |
| Customize fonts/spacing | `_sass/_variables.scss` | CUSTOMIZE.md § Customization |
| Improve SEO | `_config.yml`, `robots.txt` | SEO.md |
-| Ensure accessibility | Check markup, alt text, contrast | ACCESSIBILITY.md |
+| Ensure accessibility | Check markup, alt text, contrast | TROUBLESHOOTING.md |
## Using Community Context in Your Responses
diff --git a/.github/agents/docs.agent.md b/.github/agents/docs.agent.md
index 6420ad7..e333452 100644
--- a/.github/agents/docs.agent.md
+++ b/.github/agents/docs.agent.md
@@ -18,7 +18,7 @@ You are a documentation specialist for the al-folio Jekyll theme project.
- **Key Dependencies:** jekyll-scholar, jekyll-archives-v2, jekyll-paginate-v2, MathJax, Bootstrap, Prettier, pre-commit hooks
- **File Structure:**
- `_config.yml` – Main Jekyll configuration file
- - `*.md` (root) – Documentation files: `README.md`, `INSTALL.md`, `CUSTOMIZE.md`, `FAQ.md`, `CONTRIBUTING.md`, `MAINTENANCE.md`, `QUICKSTART.md`, `ACCESSIBILITY.md`, `ANALYTICS.md`, `SEO.md`, `TROUBLESHOOTING.md`
+ - `*.md` (root) – Documentation files: `README.md`, `INSTALL.md`, `CUSTOMIZE.md`, `FAQ.md`, `CONTRIBUTING.md`, `QUICKSTART.md`, `ANALYTICS.md`, `SEO.md`, `TROUBLESHOOTING.md`
- `_pages/` – Website pages (Markdown with frontmatter)
- `_posts/` – Blog posts
- `_projects/`, `_news/`, `_books/`, `_teachings/` – Jekyll collections
@@ -46,8 +46,9 @@ You are a documentation specialist for the al-folio Jekyll theme project.
- `assets/bibliography/`, `assets/libs/` – Support files
- `assets/audio/`, `assets/video/`, `assets/jupyter/`, `assets/plotly/`, `assets/html/` – Multimedia and embedded content
- `.github/` – GitHub configuration:
- - `.github/workflows/` – GitHub Actions (deployment, CI/CD, CV PDF generation, link checking, code quality)
- - `.github/agents/` – AI agent configuration files
+ - `.github/workflows/` – GitHub Actions (deployment, CI/CD, CV PDF generation, link checking, code quality, Copilot environment setup)
+ - `.github/agents/` – AI agent configuration files (customize.agent.md, docs.agent.md)
+ - `.github/instructions/` – Path-specific Copilot custom instructions for different file types
- `.github/ISSUE_TEMPLATE/` – GitHub issue templates
- `_scripts/` – Helper scripts and utilities
- `bin/` – Executable scripts
@@ -103,11 +104,37 @@ You are a documentation specialist for the al-folio Jekyll theme project.
## Documentation file purposes
-- `README.md` – Project overview, features showcase, quick start links
-- `INSTALL.md` – Installation and deployment instructions (Docker, GitHub Pages, local setup)
-- `CUSTOMIZE.md` – Customization guide (configuration, adding content, styling)
-- `FAQ.md` – Frequently asked questions and troubleshooting
-- `CONTRIBUTING.md` – Guidelines for contributors
+- `ANALYTICS.md` – Analytics and tracking configuration options
+- `CONTRIBUTING.md` – Guidelines for contributors and development
+- `CUSTOMIZE.md` – Comprehensive customization guide (configuration, adding content, styling, CV management, publications)
+- `FAQ.md` – Frequently asked questions and common issues
+- `INSTALL.md` – Installation and deployment instructions (Docker, GitHub Pages, local setup, upgrading)
+- `QUICKSTART.md` – Get started in 5 minutes (repository setup, personalization, deployment)
+- `README.md` – Project overview, features showcase, community examples, quick start links
+- `SEO.md` – Search engine optimization guide
+- `TROUBLESHOOTING.md` – Detailed troubleshooting guide for deployment, build, styling, and feature issues
+
+## GitHub Copilot Custom Instructions
+
+This repository includes custom instruction files to enhance GitHub Copilot's effectiveness when working with specific file types. These files are located in `.github/instructions/` and `.github/copilot-instructions.md`:
+
+**Main Instructions:**
+
+- `.github/copilot-instructions.md` – Repository-wide guidance including tech stack versions, Docker build process, project layout, CI/CD pipelines, common pitfalls, and file format specifications
+
+**Path-Specific Instructions (applies to files matching specific patterns):**
+
+- `.github/instructions/liquid-templates.instructions.md` (applies to `**/*.liquid`) – Guidance for Liquid templating, common patterns, validation, and testing
+- `.github/instructions/yaml-configuration.instructions.md` (applies to `_config.yml,_data/**/*.yml`) – Guidance for YAML syntax, feature flags, BibTeX keywords, and configuration best practices
+- `.github/instructions/bibtex-bibliography.instructions.md` (applies to `**/*.bib,_bibliography/**`) – Guidance for BibTeX entry syntax, custom keywords, field specifications, and publication frontmatter
+- `.github/instructions/markdown-content.instructions.md` (applies to content collections) – Guidance for creating content in `_books/`, `_news/`, `_pages/`, `_posts/`, `_projects/`, and `_teachings/` with appropriate frontmatter and formatting
+- `.github/instructions/javascript-scripts.instructions.md` (applies to `_scripts/**/*.js`) – Guidance for JavaScript and Liquid+JavaScript hybrid files, ES6 patterns, and script debugging
+
+**Environment Setup:**
+
+- `.github/workflows/copilot-setup-steps.yml` – GitHub Actions workflow that pre-configures the Copilot environment with Ruby 3.3.5, Python 3.13, Node.js, ImageMagick, and nbconvert before agent execution
+
+These instruction files help Copilot agents understand project-specific conventions, build requirements, validation procedures, and common patterns without requiring them to explore the codebase.
## Writing style
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..3609656
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,253 @@
+# Copilot Coding Agent Instructions
+
+## Repository Overview
+
+**al-folio** is a simple, clean, and responsive [Jekyll](https://jekyllrb.com/) theme for academics and researchers. It enables users to create professional portfolio and blog websites with minimal configuration. The repository serves both as a template and as a reference implementation.
+
+- **Type:** Jekyll static site generator template
+- **Target Users:** Academics, researchers, and professionals
+- **Key Features:** CV display, publication bibliography, blog posts, projects, news/announcements, course listings
+
+## Tech Stack & Versions
+
+**Core Technologies:**
+
+- **Jekyll:** v4.x (Ruby static site generator)
+- **Ruby:** 3.3.5 (primary CI/CD version), 3.2.2 (some workflows)
+- **Python:** 3.13 (for nbconvert, jupyter notebook support)
+- **Node.js:** Latest (for purgecss and prettier)
+- **Docker:** Uses prebuilt image `amirpourmand/al-folio:v0.16.3` (Ruby slim-based)
+
+**Build Dependencies (from Gemfile):**
+
+- `classifier-reborn` – Related posts calculation
+- `jekyll-archives-v2` – Archive page generation
+- `jekyll-jupyter-notebook` – Jupyter notebook embedding
+- `jekyll-minifier` – CSS/JS minification
+- `jekyll-paginate-v2` – Pagination
+- `jekyll-scholar` – Bibliography management
+- `jekyll-tabs` – Tab UI components
+- `jekyll-toc` – Table of contents generation
+- `jemoji` – Emoji support
+- Multiple other specialized jekyll plugins
+
+**Code Quality Tools:**
+
+- **Prettier:** v3.8.0+ with `@shopify/prettier-plugin-liquid` – Code formatter (mandatory for PRs)
+- **Purgecss:** CSS purification for production builds
+
+## Building & Local Development
+
+### Docker (Recommended Approach)
+
+**Always use Docker for local development.** This ensures consistency with CI/CD and avoids Ruby/Python environment issues.
+
+**Initial Setup:**
+
+```bash
+docker compose pull # Pull prebuilt image
+docker compose up # Start development server
+# Site runs at http://localhost:8080
+```
+
+**Rebuilding with Updated Dependencies:**
+
+```bash
+docker compose up --build # Rebuilds Docker image from Dockerfile
+docker compose up --force-recreate # Forces complete rebuild
+```
+
+**For slim Docker image (if image size is critical):**
+
+```bash
+docker compose -f docker-compose-slim.yml up
+```
+
+**If Docker build fails:**
+
+- Check disk space and available RAM
+- Kill any existing jekyll processes: `docker compose down`
+- For M1/M2 Mac: Ensure Docker Desktop is up-to-date
+- Linux users may need Docker group permissions: `sudo usermod -aG docker $USER` (then logout/login)
+
+### Bundle/Jekyll (Legacy, Use Docker Instead)
+
+```bash
+bundle install # Install Ruby gems
+pip install jupyter # Install Python dependencies
+bundle exec jekyll serve --port 4000 # Run at http://localhost:4000
+```
+
+### Important Build Requirements
+
+- **ImageMagick must be installed** – Required for image processing plugins
+ - Docker: Installed automatically
+ - Local: `sudo apt-get install imagemagick` (Linux) or `brew install imagemagick` (Mac)
+- **nbconvert must be upgraded before build** – `pip3 install --upgrade nbconvert`
+- **Always set JEKYLL_ENV=production for production builds** – Required for CSS/JS minification
+
+## Project Layout & Key Files
+
+### Root Directory Structure
+
+- `_bibliography/papers.bib` – BibTeX bibliography for publications
+- `_config.yml` – **Primary configuration file** (title, author, URLs, baseurl, feature flags)
+- `_data/` – YAML data files (socials.yml, coauthors.yml, cv.yml, citations.yml, venues.yml, repositories.yml)
+- `_includes/` – Reusable Liquid template components
+- `_layouts/` – Page layout templates (about.liquid, post.liquid, bib.liquid, distill.liquid, cv.liquid, etc.)
+- `_news/` – News/announcement entries
+- `_pages/` – Static pages (about.md, cv.md, publications.md, projects.md, teaching.md, etc.)
+- `_posts/` – Blog posts (format: YYYY-MM-DD-title.md)
+- `_projects/` – Project showcase entries
+- `_sass/` – SCSS stylesheets
+- `_scripts/` – JavaScript files for functionality
+- `_teachings/` – Course and teaching entries
+- `assets/img/` – Images, profile pictures
+- `docker-compose.yml` – Docker compose configuration
+- `Dockerfile` – Docker image definition
+- `Gemfile` & `Gemfile.lock` – Ruby dependency specifications
+- `package.json` – Node.js dependencies (prettier only)
+- `purgecss.config.js` – PurgeCSS configuration for production CSS optimization
+
+### Configuration Priority
+
+When making changes:
+
+1. **Always start with `_config.yml`** for site-wide settings
+2. **Feature flags are in `_config.yml`** – Look for `enabled: true/false` options
+3. **Social media links:** `_data/socials.yml`
+4. **Content data:** Respective `_data/*.yml` files
+5. **Styling:** `_sass/` directory (uses SCSS)
+
+## CI/CD Pipeline & Validation
+
+### GitHub Workflows (in `.github/workflows/`)
+
+- **deploy.yml** – Main deployment workflow (runs on push/PR to main/master)
+ - Sets up Ruby 3.3.5, Python 3.13
+ - Installs imagemagick, nbconvert
+ - Runs `bundle exec jekyll build` with JEKYLL_ENV=production
+ - Runs purgecss for CSS optimization
+ - Commits built site to gh-pages branch
+ - **Triggers on:** Changes to site files, assets, config (NOT documentation files alone)
+- **prettier.yml** – Code formatting validation (mandatory)
+ - Runs prettier on all files
+ - **Fails PRs if code is not properly formatted**
+ - Generates HTML diff artifact on failure
+ - Must install prettier locally to avoid failures: `npm install prettier @shopify/prettier-plugin-liquid`
+- **broken-links.yml, broken-links-site.yml** – Link validation
+- **axe.yml** – Accessibility testing
+- **codeql.yml** – Security scanning
+- **update-citations.yml** – Automatic citation updates
+- **render-cv.yml** – CV rendering from RenderCV format
+
+### Pre-commit Requirements
+
+**You must run these locally before pushing:**
+
+1. **Prettier formatting (mandatory):**
+
+```bash
+npm install --save-dev prettier @shopify/prettier-plugin-liquid
+npx prettier . --write
+```
+
+2. **Local build test with Jekyll:**
+
+```bash
+docker compose pull && docker compose up
+# Let it build (wait 30-60 seconds)
+# Visit http://localhost:8080 and verify site renders correctly
+# Exit with Ctrl+C
+```
+
+3. **Or run full build simulation:**
+
+```bash
+docker compose up --build
+bundle exec jekyll build
+# Check for errors in output
+```
+
+## Common Pitfalls & Workarounds
+
+### YAML Syntax Errors in \_config.yml
+
+- **Problem:** Special characters (`:`, `&`, `#`) in values cause parse errors
+- **Solution:** Quote string values: `title: "My: Cool Site"`
+- **Debug:** Run locally to see detailed error: `bundle exec jekyll build`
+
+### "Unknown tag 'toc'" Error on Deployment
+
+- **Problem:** Deploy succeeds locally but fails on GitHub Actions
+- **Cause:** Jekyll plugins don't load properly
+- **Solution:** Verify gh-pages branch is set as deployment source in Settings → Pages
+
+### CSS/JS Not Loading After Deploy
+
+- **Problem:** Site loads but has no styling
+- **Cause:** Incorrect `url` and `baseurl` in `_config.yml`
+- **Fix:**
+ - Personal site: `url: https://username.github.io`, `baseurl:` (empty)
+ - Project site: `url: https://username.github.io`, `baseurl: /repo-name/`
+ - Clear browser cache (Ctrl+Shift+Del or private browsing)
+
+### Prettier Formatting Failures
+
+- **Problem:** PR fails prettier check after local builds passed
+- **Solution:** Run prettier before committing:
+ ```bash
+ npx prettier . --write
+ git add . && git commit -m "Format code with prettier"
+ ```
+
+### Port 8080 or 4000 Already in Use
+
+- **Docker:** `docker compose down` then `docker compose up`
+- **Ruby:** Kill process: `lsof -i :4000 | grep LISTEN | awk '{print $2}' | xargs kill`
+
+### Related Posts Errors ("Zero vectors cannot be normalized")
+
+- **Cause:** Empty blog posts or posts with only stop words confuse classifier-reborn
+- **Solution:** Add meaningful content to posts, or set `related_posts: false` in post frontmatter
+
+## File Format Specifications
+
+### Blog Post Frontmatter (\_posts/)
+
+```yaml
+---
+layout: post
+title: Post Title
+date: YYYY-MM-DD
+categories: category-name
+---
+```
+
+### Project Frontmatter (\_projects/)
+
+```yaml
+---
+layout: page
+title: Project Name
+description: Short description
+img: /assets/img/project-image.jpg
+importance: 1
+---
+```
+
+### BibTeX Format (papers.bib)
+
+- Standard BibTeX format
+- al-folio supports custom keywords: `pdf`, `code`, `preview`, `doi`, etc.
+- Check CUSTOMIZE.md for custom bibtex keyword documentation
+
+## Trust These Instructions
+
+This guidance documents the tested, working build process and project structure. **Trust these instructions and only perform additional searches if:**
+
+1. Specific information contradicts what you observe in the codebase
+2. You need implementation details beyond what's documented
+3. Error messages reference features or files not mentioned here
+
+The instructions are designed to reduce unnecessary exploration and allow you to focus on code changes.
diff --git a/.github/instructions/bibtex-bibliography.instructions.md b/.github/instructions/bibtex-bibliography.instructions.md
new file mode 100644
index 0000000..c059643
--- /dev/null
+++ b/.github/instructions/bibtex-bibliography.instructions.md
@@ -0,0 +1,174 @@
+---
+applyTo: "**/*.bib,_bibliography/**"
+excludeAgent: "code-review"
+---
+
+# BibTeX Bibliography Instructions
+
+## BibTeX Format Basics
+
+The al-folio repository uses BibTeX for managing publications. All entries are stored in `_bibliography/papers.bib`.
+
+### Standard BibTeX Entry Types
+
+```bibtex
+@article{key,
+ title={Title},
+ author={Author, A. and Author, B.},
+ journal={Journal Name},
+ volume={10},
+ pages={1--20},
+ year={2023},
+ publisher={Publisher Name}
+}
+
+@inproceedings{key,
+ title={Title},
+ author={Author, A.},
+ booktitle={Proceedings of Conference},
+ year={2023}
+}
+
+@book{key,
+ title={Book Title},
+ author={Author, A.},
+ publisher={Publisher Name},
+ year={2023}
+}
+```
+
+## al-folio Custom BibTeX Keywords
+
+Beyond standard BibTeX fields, al-folio supports custom keywords for rich publications display:
+
+### Available Custom Keywords
+
+- **abstract:** Full abstract text (multi-line text in curly braces)
+- **award:** Award or distinction (`award: Best Paper Award`)
+- **code:** URL to source code repository (`code: https://github.com/user/repo`)
+- **dimensions:** Dimensions badge ID for citation metrics
+- **doi:** Digital Object Identifier (`doi: 10.1234/example`)
+- **html:** URL to full text or project page (`html: https://example.com`)
+- **pdf:** URL or path to PDF file (`pdf: /assets/papers/2023-paper.pdf`)
+- **poster:** URL to conference poster (`poster: /assets/posters/poster.pdf`)
+- **preview:** URL to preview image (`preview: /assets/img/papers/paper-preview.jpg`)
+- **selected:** Boolean to feature on publications page (`selected: true`)
+- **slides:** URL to presentation slides (`slides: /assets/slides/2023.pdf`)
+
+### Example Entry with Custom Keywords
+
+```bibtex
+@article{smith2023important,
+ title={Important Research},
+ author={Smith, John and Doe, Jane},
+ journal={Nature},
+ volume={100},
+ pages={1--10},
+ year={2023},
+ publisher={Nature Publishing Group},
+ abstract={This is the full abstract text. It can span multiple lines.},
+ pdf={smith2023.pdf},
+ code={https://github.com/example/repo},
+ preview={smith2023.jpg},
+ doi={10.1234/nature.12345},
+ selected={true}
+}
+```
+
+## Formatting Rules
+
+### Key Considerations
+
+1. **Unique keys:** Each entry must have a unique key (first parameter)
+2. **Author names:** Separate multiple authors with `and`
+3. **Curly braces:** Protect capitalized words in titles with `{Curly Braces}` to preserve capitalization
+4. **Special characters:** Use LaTeX escape sequences (`{\`e}`for é,`{\~n}` for ñ)
+5. **URLs:** Place URLs in `{curly braces}` to prevent issues
+6. **Alphabetical order:** Keep entries alphabetically sorted by key
+
+### Common Mistakes to Avoid
+
+- ❌ `author=Smith, John` → ✅ `author={Smith, John}`
+- ❌ `journal=Science` → ✅ `journal={Science}` or `journal = "Science"`
+- ❌ `title=Deep Learning` (loses capitalization) → ✅ `title={Deep Learning}` or `title={{D}eep {L}earning}`
+- ❌ `pdf=http://...` → ✅ `pdf={http://...}`
+
+## Jekyll-Scholar Integration
+
+The `jekyll-scholar` plugin processes BibTeX and generates bibliography pages.
+
+### How it Works
+
+1. Entries in `_bibliography/papers.bib` are read
+2. Pages marked with `layout: bib` render the bibliography
+3. Posts/pages can reference entries using `{% cite key %}`
+4. Custom keywords control what displays on publication entries
+
+### Displaying Publications
+
+In pages/posts, use:
+
+- `{% cite key %}` – Cite an entry inline
+- `{% bibliography %}` – Display full bibliography
+
+## File Paths in BibTeX
+
+When using `pdf`, `poster`, `preview`, or similar fields:
+
+- **PDF files:** Use just the filename (automatically resolved to `assets/pdf/`)
+ - Example: `pdf={smith2023.pdf}` → resolves to `assets/pdf/smith2023.pdf`
+- **Preview images:** Use just the filename (automatically resolved to `assets/img/publication_preview/`)
+ - Example: `preview={smith2023.jpg}` → resolves to `assets/img/publication_preview/smith2023.jpg`
+- **Absolute URLs:** Include full URL for external resources
+ - Example: `code={https://github.com/user/repo}`
+ - Example: `html={https://example.com/paper}`
+
+## Validation
+
+### Before Committing BibTeX Changes
+
+1. **Syntax check:** Verify no unclosed braces or quotes
+2. **Build test:**
+ ```bash
+ docker compose down
+ docker compose up
+ # Check output for "ERROR" or "Invalid bibtex"
+ # Publications should render at http://localhost:8080/publications/
+ ```
+3. **Publication page:** Open publications page and verify entries display correctly
+
+### Common BibTeX Build Errors
+
+- `Invalid bibtex reference 'key'` – Key doesn't exist in papers.bib
+- `Unmatched braces` – Missing closing brace in entry
+- `Unknown entry type` – Entry type (after @) is misspelled
+- `PDF not found` – Path in pdf field is incorrect
+
+## Editing and Maintenance
+
+### Adding New Entries
+
+1. Add entry to `_bibliography/papers.bib`
+2. Use consistent key naming (e.g., `LastnameYear` or `Lastname2023details`)
+3. Ensure all required fields are present
+4. Test build: `docker compose up`
+
+### Modifying Existing Entries
+
+- Can change any BibTeX field without breaking Jekyll
+- Adding custom keywords (pdf, code, etc.) enriches display
+- Test build after modifications to verify display
+
+### Removing Entries
+
+- Delete or comment out (prefix with `%`) the entire entry
+- No broken reference check needed; Jekyll-Scholar handles missing keys gracefully
+
+## Trust These Instructions
+
+When working with BibTeX:
+
+- Follow the standard format shown in examples above
+- Always test locally with `docker compose up` after changes
+- Check the publications page at http://localhost:8080/publications to verify display
+- Only search for additional details if encountering error messages not mentioned here
diff --git a/.github/instructions/javascript-scripts.instructions.md b/.github/instructions/javascript-scripts.instructions.md
new file mode 100644
index 0000000..2e2fd34
--- /dev/null
+++ b/.github/instructions/javascript-scripts.instructions.md
@@ -0,0 +1,248 @@
+---
+applyTo: "_scripts/**/*.js"
+---
+
+# JavaScript Scripts Instructions
+
+## Overview
+
+The `_scripts/` directory contains JavaScript files that provide frontend functionality for the al-folio website. These scripts handle:
+
+- **Search functionality** – Ninja-keys integration for search bar
+- **Analytics setup** – Google Analytics, Cronitor, Open Panel integrations
+- **Gallery functionality** – PhotoSwipe lightbox initialization
+- **Liquid template processing** – Files with `.liquid.js` extension process Jekyll Liquid syntax
+
+## Key Script Files
+
+### `search.liquid.js`
+
+- **Purpose:** Generates searchable navigation data for the Ninja-keys search component
+- **Type:** Liquid + JavaScript hybrid (Jekyll processes `.liquid.js` files)
+- **Output:** Compiled to `/assets/js/search-data.js` via permalink frontmatter
+- **Content:** Builds `ninja.data` array from site pages, posts, and navigation structure
+- **Usage:** Included in `_includes/scripts.liquid` and loaded in layouts
+
+### `photoswipe-setup.js`
+
+- **Purpose:** Initializes PhotoSwipe lightbox for image galleries
+- **Type:** Pure JavaScript with ES6 imports
+- **Output:** Compiled to `/assets/js/photoswipe-setup.js`
+- **Dependencies:** PhotoSwipe library (referenced via `site.third_party_libraries`)
+- **Functionality:** Automatically converts `.pswp-gallery` elements into interactive lightbox galleries
+
+### `google-analytics-setup.js`, `cronitor-analytics-setup.js`, `open-panel-analytics-setup.js`
+
+- **Purpose:** Initialize third-party analytics services
+- **Type:** Conditional setup scripts (may be excluded from production builds)
+- **Usage:** Loaded conditionally based on `_config.yml` feature flags
+- **Integration:** Each sets up tracking code for respective analytics platforms
+
+## File Structure & Frontmatter
+
+All scripts in `_scripts/` may include Jekyll frontmatter:
+
+```javascript
+---
+permalink: /assets/js/filename.js
+---
+// JavaScript code here
+```
+
+**Key frontmatter fields:**
+
+- `permalink:` – Specifies output path in compiled site (e.g., `/assets/js/search-data.js`)
+- Comments/empty – Files with only JavaScript and no frontmatter are processed as-is
+
+**Processing:**
+
+- `.liquid.js` files – Processed by Jekyll's Liquid engine before JavaScript compilation
+- `.js` files – Processed normally, passed through to assets directory
+- **Note:** Files in `_scripts/` are ignored by Prettier (see `.prettierignore`) because `.liquid.js` files mix Liquid template syntax with JavaScript, which Prettier doesn't support
+
+## JavaScript Patterns in al-folio
+
+### Liquid + JavaScript Mixing (in `.liquid.js` files)
+
+Example from `search.liquid.js`:
+
+```javascript
+---
+permalink: /assets/js/search-data.js
+---
+// Regular JavaScript
+const ninja = document.querySelector('ninja-keys');
+
+// Liquid processing - Jekyll loops and variables
+ninja.data = [
+ {%- for page in site.pages -%}
+ {
+ id: "nav-{{ page.title | slugify }}",
+ title: "{{ page.title }}",
+ handler: () => {
+ window.location.href = "{{ page.url | relative_url }}";
+ },
+ },
+ {%- endfor -%}
+];
+```
+
+**Important:**
+
+- Use Liquid filters (`| slugify`, `| relative_url`, `| escape`) to process Jekyll variables
+- Curly braces `{{ }}` output variables
+- Use `{%- -%}` (with hyphens) to control whitespace in generated output
+- Keep JSON structures valid after Liquid processing
+
+### ES6 Modules & Imports
+
+Scripts use modern JavaScript with ES6 imports:
+
+```javascript
+import PhotoSwipeLightbox from "{{ site.third_party_libraries.photoswipe-lightbox.url.js }}";
+import PhotoSwipe from "{{ site.third_party_libraries.photoswipe.url.js }}";
+```
+
+- Import third-party libraries via `site.third_party_libraries` configuration
+- Libraries resolved from `_config.yml` CDN or local paths
+
+### DOM Manipulation & Event Handlers
+
+Scripts attach to specific DOM elements:
+
+```javascript
+const element = document.querySelector(".selector");
+element.addEventListener("click", (event) => {
+ // Handle event
+});
+```
+
+## Common Modification Patterns
+
+### Adding a New Analytics Service
+
+1. Create new file `_scripts/myservice-setup.js`:
+
+```javascript
+---
+permalink: /assets/js/myservice-setup.js
+---
+(function() {
+ // Initialize your service
+ if (window.myService) {
+ console.log('MyService loaded');
+ }
+})();
+```
+
+2. Add conditional loading to `_includes/scripts.liquid`:
+
+```liquid
+{% if site.myservice_enabled %}
+
+{% endif %}
+```
+
+3. Add feature flag to `_config.yml`:
+
+```yaml
+myservice_enabled: false
+```
+
+### Modifying Search Data Structure
+
+In `search.liquid.js`:
+
+1. Identify the Liquid loop building `ninja.data` array
+2. Add new properties to each object:
+
+```javascript
+{
+ id: "nav-{{ title | slugify }}",
+ title: "{{ title }}",
+ newField: "{{ page.new_property }}", // Add new field
+ handler: () => { ... }
+}
+```
+
+3. Rebuild: `docker compose up` will regenerate `/assets/js/search-data.js`
+
+### Updating Gallery Functionality
+
+In `photoswipe-setup.js`:
+
+1. Modify gallery selector or initialization options
+2. Reference [PhotoSwipe documentation](https://photoswipe.com/) for available options
+3. Update any CSS classes used in gallery markup
+
+## Code Style Notes
+
+**Prettier and \_scripts/:**
+
+Files in `_scripts/` are **excluded from Prettier formatting** (defined in `.prettierignore`) because:
+
+- `.liquid.js` files contain mixed Liquid template syntax and JavaScript
+- Prettier doesn't understand or support this hybrid format
+- Manual formatting consistency is required for these files
+
+**When modifying \_scripts/ files:**
+
+- Follow existing code style in the file (indentation, spacing, quotes)
+- Maintain readability for Liquid + JavaScript mixed code
+- Do NOT run Prettier on the `_scripts/` directory
+- **DO run Prettier on the rest of the project** when making other changes: `npx prettier . --write`
+
+## Validation & Testing
+
+### Local Build Test
+
+```bash
+docker compose up
+# Wait 30 seconds for Jekyll to build
+# Check for errors in terminal output
+# Visit http://localhost:8080 and verify functionality
+```
+
+### Checking Generated Output
+
+After `docker compose up`, verify scripts compiled correctly:
+
+```bash
+# Check if script files exist in _site/assets/js/
+ls _site/assets/js/
+
+# Verify no Liquid syntax in generated output (should be pure JavaScript)
+cat _site/assets/js/search-data.js | head -20
+```
+
+### Debugging Script Issues
+
+**Script not loading:**
+
+- Check browser DevTools Console for HTTP 404 errors
+- Verify `permalink:` frontmatter matches script inclusion paths
+- Check that script is actually in `_site/assets/js/` after build
+
+**Liquid syntax errors:**
+
+- Jekyll build will fail with "Liquid Exception" messages
+- Check file for unclosed `{% %}` or `{{ }}` tags
+- Ensure Liquid filters exist (`| relative_url`, `| slugify`, etc.)
+
+**JavaScript errors:**
+
+- Check browser console for runtime errors
+- Verify all imported libraries are defined in `site.third_party_libraries` in `_config.yml`
+- Test in both Chrome and Firefox for compatibility
+
+## Trust These Instructions
+
+When modifying JavaScript scripts:
+
+- `.liquid.js` files must have valid Liquid syntax AND valid JavaScript that remains valid after Jekyll processes the Liquid
+- Do NOT run Prettier on `_scripts/` files (they are in `.prettierignore` because of Liquid + JavaScript mixing)
+- Test locally with `docker compose up` to verify build succeeds and scripts work
+- For site-wide script inclusion, modify `_includes/scripts.liquid`
+- For configuration (feature flags, third-party URLs), see yaml-configuration.instructions.md
+- Reference the actual script files in `_scripts/` as examples when adding new functionality
+- Only search for additional details if errors occur during build or testing
diff --git a/.github/instructions/liquid-templates.instructions.md b/.github/instructions/liquid-templates.instructions.md
new file mode 100644
index 0000000..04d3d35
--- /dev/null
+++ b/.github/instructions/liquid-templates.instructions.md
@@ -0,0 +1,100 @@
+---
+applyTo: "**/*.liquid"
+---
+
+# Liquid Templates Instructions
+
+## Liquid Template Basics
+
+This al-folio repository uses Liquid templating extensively. When modifying `.liquid` files:
+
+### Key Directories
+
+- `_includes/` – Reusable template components (imported with `{% include %}`)
+- `_layouts/` – Page layout templates (specified in frontmatter with `layout: name`)
+
+### Common Liquid Tags in al-folio
+
+- `{% include filename.liquid %}` – Includes template component
+- `{% for item in collection %}...{% endfor %}` – Loops
+- `{% if condition %}...{% endif %}` – Conditionals
+- `{{ variable }}` – Output variable
+- `{% assign var = value %}` – Assign variable
+- `{% capture %}...{% endcapture %}` – Capture output to variable
+- `| date: format` – Date filtering
+- `| where: "key", "value"` – Collection filtering
+
+### Important al-folio Liquid Components
+
+- `_includes/citation.liquid` – Bibliography entry rendering
+- `_includes/distill_scripts.liquid` – Distill.pub specific scripts
+- `_includes/footer.liquid` – Site footer
+- `_includes/head.liquid` – Page section
+- `_includes/header.liquid` – Site header/navigation
+- `_includes/projects.liquid` – Project display
+- `_includes/scripts.liquid` – Global scripts
+- `_includes/selected_papers.liquid` – Featured publications display
+
+### Prettier Formatting for Liquid
+
+Prettier with `@shopify/prettier-plugin-liquid` enforces formatting:
+
+- Single quotes around strings in Liquid tags
+- Consistent spacing
+- Indentation with 2 spaces
+- Run `npx prettier . --write` before committing
+
+## Common Modification Patterns
+
+### Modifying Site Header/Navigation
+
+- Edit `_includes/header.liquid`
+- Add links to navigation array in `_config.yml` (see yaml-configuration.instructions.md)
+- Test by viewing site in browser: `docker compose up` → http://localhost:8080
+
+### Adding a New Component Include
+
+1. Create new file in `_includes/mycomponent.liquid`
+2. Use Liquid syntax for conditionals, loops, and variable output
+3. Call it from templates: `{% include mycomponent.liquid %}`
+4. Test: `docker compose up`
+
+### Adjusting Styling with Liquid
+
+- Some SCSS variables can be controlled via Liquid logic
+- Avoid mixing complex Liquid with CSS; keep templates focused
+
+## Validation Before Committing
+
+**Always run these checks:**
+
+1. **Prettier format check:**
+
+ ```bash
+ npx prettier _includes/ _layouts/ --check
+ npx prettier . --write # Fix formatting
+ ```
+
+2. **Build test:**
+
+ ```bash
+ docker compose down
+ docker compose up
+ # Wait 30 seconds, check for errors in output
+ # No "Unknown tag" messages should appear
+ ```
+
+3. **Visual verification:**
+ - Open http://localhost:8080
+ - Check that your changes rendered correctly
+ - Verify no broken layout or missing content
+
+## Trust These Instructions
+
+When working with Liquid templates:
+
+- Use `_includes/` and `_layouts/` as reference for syntax patterns
+- Follow existing formatting in files (Prettier will enforce consistency)
+- Always test locally before pushing (build must succeed)
+- For configuration changes, see yaml-configuration.instructions.md
+- Only search for additional details if error messages reference unfamiliar Liquid tags or Jekyll concepts
diff --git a/.github/instructions/markdown-content.instructions.md b/.github/instructions/markdown-content.instructions.md
new file mode 100644
index 0000000..cce3769
--- /dev/null
+++ b/.github/instructions/markdown-content.instructions.md
@@ -0,0 +1,277 @@
+---
+applyTo: "_books/**/*.md,_news/**/*.md,_pages/**/*.md,_posts/**/*.md,_projects/**/*.md,_teachings/**/*.md"
+---
+
+# Content Files (Markdown) Instructions
+
+## File Organization
+
+Content in al-folio is organized by type:
+
+- **\_books/** – Book reviews and summaries
+- **\_news/** – News/announcements
+- **\_pages/** – Static pages (about, CV, publications, projects, etc.)
+- **\_posts/** – Blog posts (format: `YYYY-MM-DD-title.md`)
+- **\_projects/** – Project showcase entries
+- **\_teachings/** – Course and teaching information
+
+## Frontmatter Structure
+
+Every markdown file requires YAML frontmatter at the top. The structure varies by content type.
+
+### Book Frontmatter (\_books/)
+
+```yaml
+---
+layout: book-review
+title: Book Title
+author: Book Author Name
+publisher: Publisher Name
+year: 2023
+rating: 8/10
+img: /assets/img/book-cover.jpg
+---
+```
+
+### News Frontmatter (\_news/)
+
+```yaml
+---
+layout: post
+title: News Title
+date: YYYY-MM-DD
+---
+```
+
+### Page Frontmatter (\_pages/)
+
+```yaml
+---
+layout: page
+title: Page Title
+permalink: /pathname/
+description: Brief description for metadata
+---
+```
+
+### Blog Post Frontmatter (\_posts/)
+
+```yaml
+---
+layout: post
+title: Post Title
+date: YYYY-MM-DD
+categories: category-name
+description: Brief description
+---
+```
+
+**Important:** Post filenames MUST follow format: `YYYY-MM-DD-title.md` (hyphen-separated words)
+
+### Project Frontmatter (\_projects/)
+
+```yaml
+---
+layout: page
+title: Project Name
+description: Short description
+img: /assets/img/project-image.jpg
+importance: 1
+---
+```
+
+### Teaching/Course Frontmatter (\_teachings/)
+
+```yaml
+---
+layout: page
+title: Course Title
+description: Course description
+---
+```
+
+## Special Frontmatter Fields
+
+### For Books
+
+- **author:** Author name or comma-separated list
+- **publisher:** Publisher name
+- **year:** Publication year
+- **rating:** Personal rating (e.g., `8/10`)
+- **img:** Path to book cover image (`/assets/img/...`)
+
+### For Blog Posts
+
+- **categories:** Tag for post organization (single word, no spaces)
+- **related_posts:** Set to `false` to disable related posts display (useful for short posts)
+
+### For Projects
+
+- **importance:** Integer (1, 2, 3...) – higher = featured first
+- **img:** Path to thumbnail image (`/assets/img/...`)
+- **featured:** Set to `true` to display on main projects section
+
+### Date Format
+
+Always use ISO 8601: `YYYY-MM-DD` (e.g., `2023-12-25`)
+
+## Markdown Content
+
+### Basic Markdown Syntax
+
+```markdown
+# Heading 1
+
+## Heading 2
+
+### Heading 3
+
+**bold text**
+_italic text_
+`inline code`
+
+- List item 1
+- List item 2
+
+[Link text](https://url.com)
+
+
+```
+
+### al-folio-Specific Features
+
+#### Includes/Shortcodes
+
+- `{% include figure.liquid ... %}` – Responsive images with captions
+- `{% include audio.liquid ... %}` – Audio player
+- `{% include video.liquid ... %}` – Video player
+- `{% include bib_search.liquid ... %}` – Bibliography search
+- `{% include calendar.liquid ... %}` – Event calendar
+
+#### Math Support
+
+```markdown
+Inline: $E = mc^2$
+
+Display mode:
+$$\int_0^1 f(x) dx$$
+```
+
+#### Code Blocks
+
+````markdown
+```python
+def hello():
+ print("Hello, world!")
+```
+````
+
+#### Blockquotes
+
+```markdown
+> This is a quote
+>
+> > Nested quote
+```
+
+### Jekyll Features Available
+
+- **Liquid variables:** `{{ site.title }}`, `{{ page.title }}`
+- **Collections:** `{{ site.posts }}`, `{{ site.projects }}`
+- **Filters:** `| date: format`, `| where: key value`
+- **Tags:** `{% if condition %} ... {% endif %}`
+
+## Common Content Patterns
+
+### Creating a Blog Post
+
+1. Create file: `_posts/YYYY-MM-DD-my-post.md`
+2. Add frontmatter with `layout: post`, `title`, `date`, `categories`
+3. Write markdown content
+4. Test: `docker compose up` → http://localhost:8080/blog
+5. Post will appear in reverse chronological order
+
+### Creating a Project Entry
+
+1. Create file: `_projects/project-name.md`
+2. Add frontmatter with `layout: page`, `title`, `description`, `img`, `importance`
+3. Write markdown content describing the project
+4. Test: `docker compose up` → http://localhost:8080/projects
+
+### Adding Images
+
+```markdown
+{% include figure.liquid path="/assets/img/example.jpg" title="Image caption" %}
+```
+
+### Linking to Other Pages
+
+```markdown
+[About Me](/about/)
+[My CV](/cv/)
+[Blog Post]({% link _posts/2023-01-15-my-post.md %})
+```
+
+## Testing & Validation
+
+### Before Committing
+
+1. **Frontmatter syntax:** Verify YAML is valid (no unclosed quotes, proper indentation)
+2. **Date format:** Check `YYYY-MM-DD` format is correct
+3. **Build test:**
+ ```bash
+ docker compose down
+ docker compose up
+ # Wait for "Server running" message
+ # Navigate to your content in browser
+ # Verify formatting, images, and links work
+ ```
+
+### Common Issues
+
+- **Post not appearing:** Check `date` is today or earlier, filename format is correct
+- **Images not loading:** Verify path starts with `/assets/`, file exists
+- **Related posts error:** Content has no meaningful words; add more text or set `related_posts: false`
+
+## File Naming Conventions
+
+### Blog Posts
+
+- Format: `YYYY-MM-DD-title-with-hyphens.md`
+- Example: `2023-12-25-christmas-post.md`
+- Words separated by hyphens, no spaces
+
+### Projects
+
+- Format: `project-name.md`
+- Example: `my-research-project.md`
+- Use hyphens for readability
+
+### Pages
+
+- Format: `descriptive-name.md`
+- Example: `about.md`, `teaching.md`, `cv.md`
+
+## Markdown Linting & Formatting
+
+The Prettier formatter applies to markdown files:
+
+- **Line length:** Soft wrap at 88 characters
+- **Lists:** Consistent bullet formatting
+- **Code blocks:** Proper fence syntax
+- **Spacing:** Consistent blank lines
+
+**Always run before committing:**
+
+```bash
+npx prettier --write .
+```
+
+## Trust These Instructions
+
+When creating or editing content:
+
+- Follow the frontmatter structure for your content type
+- Test locally with `docker compose up` to verify appearance
+- Check date format, filename format, and image paths
+- Only search for advanced features if frontmatter or markdown error messages appear
diff --git a/.github/instructions/yaml-configuration.instructions.md b/.github/instructions/yaml-configuration.instructions.md
new file mode 100644
index 0000000..10a074f
--- /dev/null
+++ b/.github/instructions/yaml-configuration.instructions.md
@@ -0,0 +1,250 @@
+---
+applyTo: "_config.yml,_data/**/*.yml"
+---
+
+# YAML Configuration Instructions
+
+## YAML Configuration (\_config.yml)
+
+### Critical Settings for Agents
+
+When modifying `_config.yml`, always update these in pairs:
+
+- **url** and **baseurl** must be consistent:
+ - Personal site: `url: https://username.github.io`, `baseurl:` (leave empty)
+ - Project site: `url: https://username.github.io`, `baseurl: /projectname/`
+- **title, first_name, last_name** – Site header and metadata
+- **description** – Used in RSS feeds and metadata
+- **lang** – Language code (e.g., "en", "fr")
+
+### Feature Flags in \_config.yml
+
+Look for `enabled: false/true` patterns. Common ones:
+
+- `blog.enabled`
+- `news.enabled`
+- `profile.image_circular`
+- `profile.show_social_links`
+- `projects.enabled`
+- `publications.enabled`
+- `related_blog_posts`
+
+### YAML Syntax Rules
+
+- Quote string values containing special characters: `":"`
+- Use `>` for multi-line strings (ignore newlines)
+- Use `|` for multi-line strings (preserve newlines)
+- Indentation matters: always use spaces (2 spaces), never tabs
+- No tabs allowed; use only spaces
+
+### Testing YAML Syntax
+
+If you modify `_config.yml`, verify syntax by running:
+
+```bash
+docker compose up
+# Site should start without YAML parse errors
+# Check output for "YAML parse error" or "valid YAML"
+```
+
+## Data Files (\_data/\*.yml)
+
+Data files provide structured content that templates can access via Liquid. Each file serves a specific purpose.
+
+### socials.yml
+
+Defines social media links and contact information displayed on the site.
+
+**Format:** Entries are displayed in the order they are defined (not alphabetically sorted)
+
+**For standard socials:** Use the key with the appropriate value. Common built-in socials include:
+
+- `email:` – Email address
+- `cv_pdf:` – Path to CV PDF file
+- `scholar_userid:` – Google Scholar ID
+- `inspirehep_id:` – Inspire HEP author ID
+- `rss_icon:` – Boolean to show/hide RSS icon
+- And many others (see [jekyll-socials documentation](https://github.com/george-gca/jekyll-socials) for full list)
+
+**For custom socials:** Define a custom entry with nested fields:
+
+- `logo:` – URL or path to logo image
+- `title:` – Display name
+- `url:` – Profile or website URL
+
+**Example:**
+
+```yaml
+cv_pdf: /assets/pdf/example_pdf.pdf
+email: you@example.com
+scholar_userid: qc6CJjYAAAAJ
+github_username: username
+linkedin_username: username
+
+custom_social:
+ logo: https://example.com/logo.png
+ title: Custom Profile
+ url: https://example.com/
+```
+
+For more information, see the [jekyll-socials documentation](https://github.com/george-gca/jekyll-socials).
+
+### cv.yml
+
+CV content in **RenderCV format** (recommended approach for generating professional CVs).
+
+**Format:** [RenderCV](https://rendercv.com/) YAML format — human-readable and designed specifically for professional resumes with automatic PDF generation capability.
+
+**Key Files:**
+
+- [`_data/cv.yml`](_data/cv.yml) — Main CV content in RenderCV format
+- [`assets/rendercv/design.yaml`](assets/rendercv/design.yaml) — Design and styling customization
+- [`assets/rendercv/locale.yaml`](assets/rendercv/locale.yaml) — Localization and text formatting
+- [`assets/rendercv/settings.yaml`](assets/rendercv/settings.yaml) — RenderCV-specific settings
+
+**Usage:** Rendered by `cv.liquid` layout on CV page; displayed in `about.liquid` on home page.
+
+**Automatic PDF Generation:** When using RenderCV format, a GitHub Actions workflow (`render-cv.yml`) automatically generates a PDF version whenever you push changes to `_data/cv.yml`. The generated PDF is saved to `assets/rendercv/rendercv_output/` and can be linked via `cv_pdf` setting in `_config.yml`.
+
+**Alternative Format (JSONResume):** For an alternative format, see `assets/json/resume.json` which uses the [JSONResume](https://jsonresume.org/) standard. Switch between formats using the `cv_format` frontmatter variable in `_pages/cv.md` (options: `rendercv` or `jsonresume`).
+
+**For more details:** See [CUSTOMIZE.md § Modifying the CV information](CUSTOMIZE.md#modifying-the-cv-information) for setup, switching formats, and PDF generation configuration.
+
+### citations.yml
+
+Social media citation counts and metrics.
+
+**Format:** Varies by platform (Google Scholar, ORCID, etc.)
+
+**Example:**
+
+```yaml
+scholar_userid: YOUR_SCHOLAR_ID
+```
+
+### repositories.yml
+
+GitHub repository listing for the repositories page.
+
+**Format:** List of repository information
+
+**Usage:** Used by repositories page to display GitHub projects
+
+### coauthors.yml
+
+Co-author information for bibliography/publications.
+
+**Mapping:** Author names to profile URLs and affiliations
+
+**Format:** Maps full names to contact info
+
+**Example:**
+
+```yaml
+"Einstein, Albert":
+ url: https://en.wikipedia.org/wiki/Albert_Einstein
+ affiliation: Princeton University
+```
+
+## Common Modification Patterns
+
+### Adding a New Feature Flag
+
+1. Add to `_config.yml`:
+
+ ```yaml
+ my_feature:
+ enabled: true
+ ```
+
+2. In Liquid templates use:
+
+ ```liquid
+ {% if site.my_feature.enabled %}
+ ... content ...
+ {% endif %}
+ ```
+
+3. Document the flag in CUSTOMIZE.md
+
+### Updating Social Media Links
+
+1. Edit `_data/socials.yml`
+2. Keep entries alphabetically sorted
+3. Ensure `icon` identifiers match available icons (Academicons or Font Awesome)
+4. Use full profile URLs in `url` field
+5. Test: `docker compose up` → check social icons on site
+
+### Modifying Site Metadata
+
+Update these in `_config.yml`:
+
+- **title** – Site name
+- **first_name, last_name** – Your name
+- **email** – Contact email
+- **description** – Site tagline (used in RSS, metadata)
+- **keywords** – Search keywords
+
+### Adding Co-authors
+
+1. Edit `_data/coauthors.yml`
+2. Add entry with author name as key
+3. Include `url:` and `affiliation:` fields
+4. This maps author names in BibTeX to profile links
+
+## Validation Before Committing
+
+**Always run these checks:**
+
+1. **YAML syntax check:**
+
+ ```bash
+ # Run Jekyll build to validate YAML
+ docker compose down
+ docker compose up
+ # Wait for "Server running" message
+ # Check output for "YAML parse error" messages
+ ```
+
+2. **Prettier format check:**
+
+ ```bash
+ npx prettier _config.yml _data/ --check
+ npx prettier . --write # Fix formatting
+ ```
+
+3. **Visual verification:**
+ - Open http://localhost:8080
+ - Check that your changes appear correctly
+ - Verify navigation, social links, and metadata work
+ - Check site title and description in page source
+
+## Common Issues
+
+### "YAML parse error"
+
+- Check for unquoted special characters (`:`, `&`, `#`, `|`, `>`)
+- Verify indentation uses only spaces (2 spaces per level)
+- Ensure closing quotes and braces are present
+
+### Feature flag not working
+
+- Check syntax: `feature: enabled: true` (colon after feature name)
+- Verify spelling in Liquid template: `{% if site.feature.enabled %}`
+- Clear browser cache if using old cached pages
+
+### Social links not appearing
+
+- Verify `_data/socials.yml` has correct entries
+- Check icon identifiers exist in Font Awesome or Academicons
+- Ensure `url:` field is not empty
+
+## Trust These Instructions
+
+When working with YAML configuration:
+
+- Always test locally with `docker compose up` after changes
+- Quote any string containing special characters
+- Keep indentation consistent (2 spaces)
+- Check output for YAML parse errors before committing
+- Only search for additional details if encountering error messages not mentioned here
diff --git a/.github/workflows/broken-links.yml b/.github/workflows/broken-links.yml
index d23c011..ce7b9e8 100644
--- a/.github/workflows/broken-links.yml
+++ b/.github/workflows/broken-links.yml
@@ -51,4 +51,4 @@ jobs:
with:
fail: true
# removed md files that include liquid tags
- args: --user-agent 'curl/7.54' --exclude-path README.md --exclude-path _pages/404.md --exclude-path _pages/blog.md --exclude-path _posts/2018-12-22-distill.md --exclude-path _posts/2023-04-24-videos.md --exclude-path _books/the_godfather.md --verbose --no-progress './**/*.md' './**/*.html'
+ args: --user-agent 'curl/7.54' --exclude-path README.md --exclude-path _pages/404.md --exclude-path _pages/blog.md --exclude-path _posts/2018-12-22-distill.md --exclude-path _posts/2023-04-24-videos.md --exclude-path _books/the_godfather.md --exclude-path .github/instructions/bibtex-bibliography.instructions.md --exclude-path .github/instructions/yaml-configuration.instructions.md --exclude-path .github/instructions/markdown-content.instructions.md --exclude-path .github/instructions/liquid-templates.instructions.md --exclude-path AGENTS.md --exclude-path SEO.md --verbose --no-progress './**/*.md' './**/*.html'
diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml
new file mode 100644
index 0000000..e1b652e
--- /dev/null
+++ b/.github/workflows/copilot-setup-steps.yml
@@ -0,0 +1,58 @@
+name: "Copilot Setup Steps"
+
+# Automatically run the setup steps when they are changed to allow for easy validation, and
+# allow manual testing through the repository's "Actions" tab
+on:
+ workflow_dispatch:
+ push:
+ paths:
+ - .github/workflows/copilot-setup-steps.yml
+ pull_request:
+ paths:
+ - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+ # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
+ copilot-setup-steps:
+ runs-on: ubuntu-latest
+
+ # Set the permissions to the lowest permissions possible needed for your steps.
+ # Copilot will be given its own token for its operations.
+ permissions:
+ contents: read
+
+ # You can define any steps you want, and they will run before the agent starts.
+ # If you do not check out your code, Copilot will do this for you.
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Setup Ruby
+ uses: ruby/setup-ruby@v1
+ with:
+ ruby-version: "3.3.5"
+ bundler-cache: true
+
+ - name: Setup Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: "3.13"
+ cache: "pip"
+
+ - name: Setup Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: "latest"
+ cache: "npm"
+
+ - name: Install system dependencies
+ run: |
+ sudo apt-get update
+ sudo apt-get install -y imagemagick
+
+ - name: Install Python dependencies
+ run: |
+ pip3 install --upgrade nbconvert
+
+ - name: Install Node.js dependencies
+ run: npm ci
diff --git a/.lycheeignore b/.lycheeignore
index b736879..64194b5 100644
--- a/.lycheeignore
+++ b/.lycheeignore
@@ -1,2 +1,14 @@
-linkedin.com
-reddit.com
\ No newline at end of file
+.github/instructions/bibtex-bibliography.instructions.md
+.github/instructions/liquid-templates.instructions.md
+.github/instructions/markdown-content.instructions.md
+.github/instructions/yaml-configuration.instructions.md
+_books/the_godfather.md
+_pages/404.md
+_pages/blog.md
+_posts/2018-12-22-distill.md
+_posts/2023-04-24-videos.md
+AGENTS.md
+https://www.linkedin.com/
+https://www.reddit.com/
+README.md
+SEO.md
diff --git a/ACCESSIBILITY.md b/ACCESSIBILITY.md
deleted file mode 100644
index 015e591..0000000
--- a/ACCESSIBILITY.md
+++ /dev/null
@@ -1,401 +0,0 @@
-# Accessibility Guide
-
-This guide helps you ensure your al-folio website is accessible to all visitors, including people with disabilities.
-
-
-
-- [Accessibility Guide](#accessibility-guide)
- - [Overview](#overview)
- - [Why Accessibility Matters](#why-accessibility-matters)
- - [Built-in Accessibility](#built-in-accessibility)
- - [Accessibility Checking](#accessibility-checking)
- - [Run Automated Tests Locally](#run-automated-tests-locally)
- - [Manual Testing](#manual-testing)
- - [Common Accessibility Issues & Fixes](#common-accessibility-issues--fixes)
- - [Images Missing Alt Text](#images-missing-alt-text)
- - [Links Not Descriptive](#links-not-descriptive)
- - [Color Contrast Too Low](#color-contrast-too-low)
- - [Keyboard Navigation Not Working](#keyboard-navigation-not-working)
- - [Missing Form Labels](#missing-form-labels)
- - [Heading Hierarchy Broken](#heading-hierarchy-broken)
- - [Accessibility Best Practices](#accessibility-best-practices)
- - [Writing Content](#writing-content)
- - [Images and Media](#images-and-media)
- - [Links](#links)
- - [Code and Math](#code-and-math)
- - [PDFs and Documents](#pdfs-and-documents)
- - [Testing Tools](#testing-tools)
- - [Resources](#resources)
-
-
-## Overview
-
-Accessibility means ensuring your website works for everyone, regardless of ability. This includes:
-
-- **Visual impairments** – Screen reader users, low vision
-- **Hearing impairments** – Captions for video, transcripts for audio
-- **Motor impairments** – Keyboard navigation, large buttons
-- **Cognitive impairments** – Clear language, simple navigation
-- **Other** – Slow connections, old devices, non-native speakers
-
----
-
-## Why Accessibility Matters
-
-1. **Ethical:** Making your research accessible to everyone
-2. **Legal:** Some jurisdictions require web accessibility (ADA in US, AODA in Canada, WCAG in EU)
-3. **SEO:** Accessible sites rank better in search engines
-4. **Usability:** Accessible sites are easier for everyone to use
-5. **Academic integrity:** More people can read and build on your research
-
----
-
-## Built-in Accessibility
-
-al-folio includes several accessibility features out of the box:
-
-- ✅ **Semantic HTML** – Proper heading structure, landmarks
-- ✅ **Responsive design** – Works on phones, tablets, desktops
-- ✅ **Color contrast** – Meets WCAG AA standards
-- ✅ **Keyboard navigation** – Navigate without a mouse
-- ✅ **Screen reader support** – Works with NVDA, JAWS, VoiceOver
-- ✅ **Dark mode** – Reduces eye strain for some users
-- ✅ **Focus indicators** – Clear focus states for keyboard users
-
----
-
-## Accessibility Checking
-
-### Run Automated Tests Locally
-
-al-folio includes **axe (automated testing)** to check for accessibility issues.
-
-**Using GitHub Actions (easiest):**
-
-1. Push changes to your repository
-2. Go to **Actions** tab
-3. Look for the **"Axe - a11y tests"** workflow
-4. Click on the completed run to see results
-5. Expand any failures to see details and fixes
-
-**Running locally:**
-
-```bash
-# Check a specific file
-axe _pages/about.md
-
-# Or use the GitHub Actions workflow
-# Results are posted as a comment on pull requests
-```
-
-**Interpreting results:**
-
-- 🔴 **Critical** – Must fix (breaks functionality)
-- 🟠 **Serious** – Should fix (impacts many users)
-- 🟡 **Moderate** – Nice to fix (affects some users)
-- 🔵 **Minor** – Polish (edge cases)
-
----
-
-### Manual Testing
-
-Automated tools catch ~30% of issues. Manual testing catches the rest.
-
-**Test keyboard navigation:**
-
-1. Hide your mouse/trackpad
-2. Use **Tab** to navigate through all interactive elements
-3. Use **Enter** or **Space** to activate buttons/links
-4. Use arrow keys for dropdown menus
-5. Ensure you can access all features
-
-**Test with a screen reader:**
-
-**Windows:**
-
-- Use built-in **Narrator**: `Windows + Ctrl + N`
-
-**Mac:**
-
-- Use built-in **VoiceOver**: `Cmd + F5`
-
-**Linux:**
-
-- Use **NVDA** (free download): https://www.nvaccess.org/
-
-**Checklist:**
-
-- [ ] All page content is readable
-- [ ] Links are descriptive (screen reader reads link text)
-- [ ] Images have alt text
-- [ ] Headings make sense when read aloud
-- [ ] Form fields have labels
-
-**Test color contrast:**
-
-- Use [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
-- Ensure text is readable (especially on custom theme colors)
-- Minimum contrast ratio: 4.5:1 for normal text, 3:1 for large text
-
----
-
-## Common Accessibility Issues & Fixes
-
-### Images Missing Alt Text
-
-**Problem:** Images have no description for screen reader users.
-
-**Fix in Markdown:**
-
-```markdown
-# Bad ❌
-
-
-
-# Good ✅
-
-
-```
-
-**Fix in BibTeX:**
-
-```bibtex
-# Add descriptions for paper thumbnails
-@article{mykey,
- # ... other fields ...
- alt={Diagram showing the three-layer neural network architecture}
-}
-```
-
-**Good alt text:**
-
-- Describes the content and purpose
-- About 125 characters max
-- Doesn't say "image of" (screen readers already say that)
-- For charts: describe the data, not just "chart"
-
-**Examples:**
-
-```markdown
-❌ "Photo"
-✅ "Alice Chen presenting her research on climate modeling"
-
-❌ "Graph of results"
-✅ "Bar chart showing publication counts by year from 2015 to 2024"
-
-❌ "Logo"
-✅ "University of Example logo"
-```
-
----
-
-### Links Not Descriptive
-
-**Problem:** Links like "click here" don't make sense to screen reader users.
-
-**Fix:**
-
-```markdown
-# Bad ❌
-
-See my paper [here](assets/pdf/paper.pdf).
-
-# Good ✅
-
-Read my [analysis of climate policy](assets/pdf/paper.pdf).
-```
-
-**Why this matters:** Screen reader users often skip through links quickly. Links must be meaningful out of context.
-
----
-
-### Color Contrast Too Low
-
-**Problem:** Text is hard to read against background color.
-
-**Fix:**
-
-1. Use the [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
-2. Enter your text color and background color
-3. Ensure ratio is at least **4.5:1** (normal text) or **3:1** (large text)
-4. Adjust colors in `_config.yml` or `_sass/_themes.scss`
-
-**al-folio default colors meet WCAG AA standards**, so this is usually only an issue if you customize colors heavily.
-
----
-
-### Keyboard Navigation Not Working
-
-**Problem:** Some buttons or links can't be accessed with keyboard.
-
-**Fix:**
-
-- Ensure all interactive elements use semantic HTML: `