awebsite/.github/copilot-instructions.md

# Copilot Instructions for AI Agents

## Project Overview
This is **aron.petau.net**, a multilingual personal portfolio and blog built with:
- **Framework**: [Zola](https://www.getzola.org/) static site generator (v0.19+)
- **Theme**: Customized [Duckquill](https://duckquill.daudix.one) theme
- **Languages**: English (default) and German (`.de.md` suffixed files)
- **Deployment**: Manual build process, `public/` directory is version controlled
- **URL**: https://aron.petau.net/
- **Source**: Hosted on self-hosted Forgejo at https://forgejo.petau.net/aron/awebsite

## Architecture & File Structure

### Content Layer (`content/`)
- `_index.md` / `_index.de.md` - Homepage content
- `pages/` - Static pages (About, CV, Contact, Privacy, etc.)
- `project/` - Blog posts and projects, organized by date folders
  - Format: `YYYY-MM-DD-slug/index.md` and `index.de.md`
  - Each project is self-contained with its own images

### Template Layer
- `themes/duckquill/templates/` - Base theme templates (DO NOT MODIFY)
- `templates/` - Custom template overrides (use this for customization)
- `templates/shortcodes/` - Custom shortcodes (gallery, mermaid, skills, timeline)

### Style Layer
- `sass/` - Custom SCSS source files (compiled by Zola)
- `themes/duckquill/sass/` - Theme SCSS (DO NOT MODIFY)
- `static/css/` - Pre-built CSS for shortcodes (gallery, mermaid, skills, timeline)

### Static Assets
- `static/` - Raw files copied as-is to output (images, documents, fonts, CSS, JS)
  - `static/documents/` - PDFs and downloadable files
  - `static/images/` - Site-wide images
  - `static/css/` - Custom CSS for shortcodes
- `public/` - **Generated output** (version controlled, pushed to server)

### Configuration
- `config.toml` - Main Zola configuration
  - Base URL: `https://aron.petau.net/`
  - Theme: `duckquill`
  - Features: RSS/Atom feeds, search index, taxonomy (tags)
  - Custom styles loaded: timeline, mermaid, skills, gallery
- `i18n/de.toml` - German translations for UI elements

## Critical Workflows

### Development
```bash
# Serve with live reload on localhost:1111
zola serve

# Build site (output to public/)
zola build

# Run comprehensive tests (build, link checking, etc.)
./scripts/test_site.sh
```

### Content Management
```bash
# Create German stubs for all existing English content
./scripts/create_german_stubs.sh

# Update frontmatter across content files
./scripts/add_update_frontmatter.sh

# Organize content (details in script)
./scripts/organize.sh
```

### Content Creation

**New Project/Blog Post:**
1. Create folder: `content/project/YYYY-MM-DD-slug/`
2. Create `index.md` (English) and `index.de.md` (German)
3. Add required frontmatter:
   ```toml
   +++
   title = "Project Title"
   authors = ["Aron Petau"]
   date = 2025-10-06
   description = "Brief description"

   [taxonomies]
   tags = ["tag1", "tag2"]

   +++
   ```
4. Place images in the same directory as the markdown file
5. Build and test locally before committing

**New Page:**
1. Create in `content/pages/`: `pagename.md` and `pagename.de.md`
2. Add frontmatter (same structure as above)
3. Ensure both language versions have matching content structure

**Adding Documents (PDFs, etc.):**
- Place in `static/documents/`
- Reference as `/documents/filename.pdf` in content
- **DO NOT** use external CDN dependencies (Adobe, etc.)

## Project-Specific Conventions

### Multilingual Content
- **Every page must have both `.md` (English) and `.de.md` (German)**
- Filenames must match exactly (except for language suffix)
- German translations should match English structure and tone
- Use `./scripts/create_german_stubs.sh` to generate initial German files

### Frontmatter Requirements
All markdown files require TOML frontmatter with:
- `title` - Page/post title
- `authors` - Array, typically `["Aron Petau"]`
- `date` - ISO format (YYYY-MM-DD)
- `description` - Brief summary (for SEO and cards)
- `[taxonomies]` - tags array
- `[extra]` - Optional settings (show_copyright, show_shares, etc.)

### Directory Structure Conventions
- `content/pages/` - Static site pages
- `content/project/` - Blog posts and projects (date-prefixed folders)
- `static/documents/` - PDFs and downloadable files
- `static/images/` - Site-wide images
- `static/css/` - Shortcode-specific CSS
- Project images go in same folder as `index.md`

### Theme Customization Rules
- **NEVER modify** `themes/duckquill/` directly
- Use `templates/` for template overrides
- Use `sass/` for style customizations
- Use `static/` for additional assets
- Theme updates can overwrite changes in `themes/` directory

### Asset References
- Static files: `/path/from/static/` (e.g., `/documents/file.pdf`)
- Images in same folder: `./image.jpg`
- Processed images: Zola handles automatically
- External links: Use full URLs with https://

## Custom Shortcodes

The site provides four custom shortcodes in `templates/shortcodes/`:

### 1. Gallery Shortcode
Creates responsive image galleries with lightbox support.
**Location**: `templates/shortcodes/gallery.html`
**CSS**: `static/css/gallery.css`

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

**Requirements:**
- Images must be in the same directory as the content file
- Use `./imagename.jpg` for relative paths
- All images must have `alt` text for accessibility
- `title` is optional and appears in lightbox

### 2. Mermaid Shortcode
Renders diagrams using Mermaid.js syntax.
**Location**: `templates/shortcodes/mermaid.html`
**CSS**: `static/css/mermaid.css`

```md
{% mermaid() %}
graph TD
    A[Start] --> B[Process]
    B --> C{Decision}
    C -->|Yes| D[End]
    C -->|No| A
{% end %}
```

**Supported diagrams:** flowchart, sequence, class, state, ER, Gantt, pie, etc.

### 3. Skills Shortcode
Displays categorized skills with optional icons and links.
**Location**: `templates/shortcodes/skills.html`
**CSS**: `static/css/skills.css`

```md
{% skills() %}
[
  {
    "name": "Programming",
    "skills": [
      {"name": "Python", "icon": "fab fa-python", "link": "https://python.org"},
      {"name": "JavaScript", "icon": "fab fa-js"}
    ]
  },
  {
    "name": "Design",
    "skills": [
      {"name": "Figma"},
      {"name": "Adobe XD", "link": "https://adobe.com/xd"}
    ]
  }
]
{% end %}
```

**Properties:**
- `name` (required) - Skill name
- `icon` (optional) - FontAwesome class
- `link` (optional) - External URL

### 4. Timeline Shortcode
Displays chronological events and experiences.
**Location**: `templates/shortcodes/timeline.html`
**CSS**: `static/css/timeline.css`

```md
{% timeline() %}
[
  {
    "from": "2025-01",
    "to": "2025-12",
    "title": "Event Title",
    "location": "Berlin, Germany",
    "icon": "fas fa-briefcase",
    "body": "Description of the event or experience",
    "link": "https://example.com"
  },
  {
    "from": "2024-06",
    "to": "present",
    "title": "Current Position",
    "location": "Remote",
    "body": "Ongoing work description"
  }
]
{% end %}
```

**Properties:**
- `from` (required) - Start date (YYYY-MM format)
- `to` (required) - End date or "present"
- `title` (required) - Event title
- `location` (optional) - Physical location
- `icon` (optional) - FontAwesome class
- `body` (optional) - Detailed description
- `link` (optional) - External URL

## Build & Deployment Process

## Build & Deployment Process

### Local Development
1. **Serve locally** (live reload on port 1111):
   ```bash
   zola serve
   ```

2. **Build site** (outputs to `public/`):
   ```bash
   zola build
   ```

3. **Run tests** (comprehensive validation):
   ```bash
   ./scripts/test_site.sh
   ```
   Tests include:
   - Build validation
   - Link checking (internal and external)
   - Markdown linting
   - Accessibility checks

### Deployment Workflow
1. Make content/code changes
2. Test locally with `zola serve`
3. Run `zola build` to generate `public/`
4. **Important**: `public/` is version controlled
5. Commit both source files AND generated `public/` directory
6. Push to Forgejo (self-hosted Git)
7. Server pulls and serves from `public/`

### Quality Checks
Before committing:
- [ ] Build succeeds without errors
- [ ] Both EN and DE versions exist and match structure
- [ ] Links are valid (run `./scripts/test_site.sh`)
- [ ] Images have alt text
- [ ] Frontmatter is complete and valid
- [ ] No external CDN dependencies added

## Common Tasks & Examples

### Add a new blog post/project
```bash
# 1. Create directory
mkdir -p content/project/2025-10-06-my-project

# 2. Create content files
touch content/project/2025-10-06-my-project/index.md
touch content/project/2025-10-06-my-project/index.de.md

# 3. Add images to same directory
cp ~/images/hero.jpg content/project/2025-10-06-my-project/

# 4. Edit markdown files with proper frontmatter
# 5. Test locally
zola serve

# 6. Build and commit
zola build
git add .
git commit -m "Add: My Project blog post"
git push
```

### Add a new static page
```bash
# Create both language versions
touch content/pages/newpage.md
touch content/pages/newpage.de.md

# Or use the German stub generator
./scripts/create_german_stubs.sh
```

### Update theme styles
```bash
# Add custom SCSS (never edit themes/duckquill/)
nano sass/_custom.scss

# Add to sass/style.scss imports
# Rebuild
zola build
```

### Add a PDF document
```bash
# Place in static directory
cp ~/Downloads/document.pdf static/documents/

# Reference in markdown
# Link: [Download PDF](/documents/document.pdf)
```

### Create a gallery in a post
```markdown
{% gallery() %}
[
  {"file": "./hero.jpg", "alt": "Main image", "title": "Project hero image"},
  {"file": "./detail1.jpg", "alt": "Detail view"},
  {"file": "./detail2.jpg", "alt": "Another detail"}
]
{% end %}
```

## Troubleshooting

### Build fails
1. Check TOML frontmatter syntax (no smart quotes)
2. Ensure all referenced files exist
3. Check for unclosed shortcodes
4. Run `zola check` for detailed errors

### Links broken
1. Use absolute paths for static files (`/documents/file.pdf`)
2. Use relative paths for same-folder images (`./image.jpg`)
3. Run `./scripts/test_site.sh` to find broken links

### German version missing
```bash
./scripts/create_german_stubs.sh
```

### Images not showing
1. Check image is in same folder as markdown file
2. Use `./` prefix for relative images in gallery
3. Ensure proper JSON formatting in gallery shortcode

### Styles not applying
1. Check `config.toml` extra.styles array includes your CSS
2. Ensure CSS is in `static/css/` not `sass/`
3. Rebuild with `zola build`
4. Clear browser cache

## Key Files Reference

| File/Directory | Purpose | Edit? |
|---------------|---------|-------|
| `config.toml` | Main configuration | ✅ Yes |
| `content/` | All markdown content | ✅ Yes |
| `templates/` | Custom template overrides | ✅ Yes |
| `sass/` | Custom SCSS | ✅ Yes |
| `static/` | Static assets | ✅ Yes |
| `themes/duckquill/` | Base theme | ❌ No - override instead |
| `public/` | Generated output | 🤖 Auto-generated, but version controlled |
| `i18n/de.toml` | German UI translations | ✅ Yes |
| `scripts/*.sh` | Automation scripts | ✅ Yes |

## Integration Points

- **Zola CLI**: All builds use Zola v0.19+
- **Theme**: Duckquill ([docs](https://duckquill.daudix.one))
- **Version Control**: Self-hosted Forgejo at https://forgejo.petau.net/aron/awebsite
- **Hosting**: Static files served from `public/` directory
- **Search**: Fuse.js with index built by Zola
- **Math**: KaTeX for equations
- **Diagrams**: Mermaid.js via custom shortcode
- **Icons**: FontAwesome (loaded by theme)

## Notes for AI Agents

1. **Always create bilingual content** - Every `.md` needs a `.de.md`
2. **Never modify theme files directly** - Use overrides in `templates/` or `sass/`
3. **Version control `public/`** - Unlike typical Zola sites, this project commits build output
4. **No external dependencies** - Don't add CDN scripts (Adobe, etc.) - use local files
5. **Test before committing** - Run `./scripts/test_site.sh`
6. **Respect existing structure** - Projects in date-prefixed folders, pages in `pages/`
7. **Use shortcodes** - Gallery, timeline, skills, mermaid for rich content
8. **Accessibility matters** - Always include alt text, proper heading hierarchy
9. **Check frontmatter** - Required fields: title, authors, date, description

---

For detailed theme documentation, see `themes/duckquill/README.md`
- Static assets: `static/`, `public/`
- Custom shortcodes: `templates/shortcodes/`

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