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 static site generator (v0.19+)
• Theme: Customized Duckquill 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

# 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

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

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

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

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

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

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

   zola serve
   

2. Build site (outputs to public/):

   zola build
   

3. Run tests (comprehensive validation):

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

# 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

# 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

# Add custom SCSS (never edit themes/duckquill/)
nano sass/_custom.scss

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

Add a PDF document

# 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

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

./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)
• 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.