Added copilot instructions, AGENTS.md, improved README files

.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
 

.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
 

.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.