awebsite/.github/copilot-instructions.md

Copilot Instructions for AI Agents

Project Overview

• This is a Zola static site, using the "Duckquill" theme (see themes/duckquill).
• Content is organized in Markdown files under content/ (with language variants like .de.md for German).
• Static assets (images, CSS, JS) are in public/ and static/.
• Theme customizations and templates are in themes/duckquill/ and templates/.
• Configuration is managed via config.toml and language files in i18n/.

Key Workflows

• Build the site: Use Zola (zola build) to generate static files. Output goes to public/.
• Serve locally: Use zola serve for local development with live reload.
• Content updates: Add/edit Markdown files in content/ (use .de.md for German, .md for English).
• Theme changes: Edit files in themes/duckquill/ or templates/ for layout and style.
• Static assets: Place images, CSS, JS in static/ (copied as-is to output).
• SASS/SCSS: Source styles in sass/, compiled by Zola if referenced in theme.
• Scripts: Shell scripts in scripts/ automate content and frontmatter management (e.g., add_update_frontmatter.sh).

Project-Specific Conventions

• Multilingual content: Each page has .md (English) and .de.md (German) variants. Use matching filenames for translations.
• Frontmatter: All Markdown files require Zola-compatible TOML frontmatter.
• Directory structure:
  • content/pages/ for main site pages
  • content/project/ for project posts (each project in its own subfolder)
• Theme: Only modify themes/duckquill/ for theme changes; avoid editing Zola core files.
• Static files: Use static/ for assets that should be copied verbatim to the output.

Integration Points

• Zola: All builds and local serving use Zola CLI.
• External links: Theme and documentation reference Duckquill demo.
• CI/CD: No explicit CI/CD config found; manual builds expected.

Examples

• To add a new German page: create content/pages/newpage.de.md with TOML frontmatter.
• To update theme CSS: edit themes/duckquill/static/css/ or sass/ and rebuild.
• To run locally: zola serve from project root.

Custom Shortcodes

The site provides several custom shortcodes for content enhancement:

Gallery Shortcode

Used for creating image galleries with lightbox support:

{% gallery() %}
[
  {"file": "image1.jpg", "alt": "Description", "title": "Optional Caption"},
  {"file": "image2.jpg", "alt": "Description"}
]
{% end %}

Images must be in the same directory as the content file.

Mermaid Shortcode

For rendering diagrams:

{% mermaid() %}
graph TD
    A[Start] --> B[End]
{% end %}

Skills Shortcode

For displaying categorized skills with optional icons and links:

{% skills() %}
[
  {
    "name": "Category Name",
    "skills": [
      {"name": "Skill Name", "icon": "fa-icon-class", "link": "optional-url"},
      {"name": "Another Skill"}
    ]
  }
]
{% end %}

Timeline Shortcode

For chronological events and experiences:

{% timeline() %}
[
  {
    "from": "2025-01",
    "to": "2025-12",
    "title": "Event Title",
    "location": "Optional Location",
    "icon": "optional-icon-class",
    "body": "Event description",
    "link": "optional-url"
  }
]
{% end %}

References

• Theme docs: themes/duckquill/README.md
• Main config: config.toml
• Scripts: scripts/
• Content: content/
• Static assets: static/, public/
• Custom shortcodes: templates/shortcodes/

---

For questions or unclear conventions, check theme docs or ask for clarification.