# 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](https://duckquill.daudix.one).
- **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:
```md
{% 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:
```md
{% mermaid() %}
graph TD
    A[Start] --> B[End]
{% end %}
```

### Skills Shortcode
For displaying categorized skills with optional icons and links:
```md
{% 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:
```md
{% 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.