pages/.github/instructions/yaml-configuration.instructions.md

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:

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

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.

cv.yml

CV content in RenderCV format (recommended approach for generating professional CVs).

Format: RenderCV YAML format — human-readable and designed specifically for professional resumes with automatic PDF generation capability.

Key Files:

• _data/cv.yml — Main CV content in RenderCV format
• assets/rendercv/design.yaml — Design and styling customization
• assets/rendercv/locale.yaml — Localization and text formatting
• 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 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 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:

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:

"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:

   my_feature:
     enabled: true
   

2. In Liquid templates use:

   {% 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:

   # 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:

   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