# Studio UMZU - Copilot Instructions

## Project Overview

This is a **Zola static site** for Studio UMZU, a Berlin-based workshop team offering maker education. The site uses the [Duckquill theme](https://duckquill.daudix.one) and is deployed with multilingual support (German primary, English secondary).

## Architecture & Key Concepts

### Static Site Structure
- **Zola**: Static site generator written in Rust (similar to Hugo/Jekyll)
- **Duckquill Theme**: Located in `themes/duckquill/`, provides templates, styles, and base functionality
- **Content**: Markdown files in `content/` with TOML frontmatter (`+++`)
- **Output**: Generated to `public/` directory (not version controlled)

### Multilingual Setup
- **Default language**: German (`de`) - files without suffix (e.g., `_index.md`)
- **English**: Files with `.en.md` suffix (e.g., `_index.en.md`)
- Language-specific content uses Zola's built-in i18n with translations in `i18n/de.toml`

### Content Organization
- **Section pages**: `_index.md` or `_index.en.md` files
- **Single pages**: Can be either standalone `.md` files or `folder/index.md` structure
- **Colocated assets**: Images and resources placed alongside content markdown files

## Critical Developer Workflows

### Building & Previewing
```bash
# Development server with live reload
zola serve

# Production build
zola build

# Build with specific base URL
zola build --base-url https://studio-umzu.de/
```

The site is configured in `config.toml` with:
- `compile_sass = true` - SCSS compilation enabled
- `minify_html = true` - Production optimization
- `hard_link_static = false` - Proper static file copying

### Content Management Scripts

The `scripts/` directory contains helper utilities:

1. **`create_german_stubs.sh`**: Creates `.de.md` versions from base `.md` files
   - Automatically prefixes titles with "Übersetzung: "
   - Uses macOS-compatible `sed -i ''` syntax

2. **`add_update_frontmatter.sh`**: Adds `updated` field to frontmatter after existing `date` field

3. **`organize.sh`**: Converts ISO-dated files (`2023-06-01-post.md`) into folder structure (`2023-06-01-post/index.md`)

4. **`youtube_rewrite.sh`**: Migrates old Jekyll-style video embeds to Zola shortcodes

## Custom Shortcodes & Components

The site extends Duckquill with custom shortcodes in `templates/shortcodes/`:

### 1. **Skills** (`skills.html`)
Renders categorized skill lists with icons. Usage in markdown:
```markdown
{% skills() %}
[
  {
    "name": "Category Name",
    "skills": [
      { "name": "Skill", "icon": "fas fa-icon", "link": "https://..." }
    ]
  }
]
{% end %}
```

### 2. **Timeline** (`timeline.html`)
Displays chronological events with dates and locations:
```markdown
{% timeline() %}
[
  {
    "title": "Event",
    "from": "2023-01",
    "to": "2023-12",
    "location": "Berlin",
    "icon": "fas fa-map-marker",
    "body": "Description",
    "link": "https://..."
  }
]
{% end %}
```

### 3. **Gallery** (`gallery.html`)
Creates image galleries from JSON data:
```markdown
{% gallery() %}
[
  { "file": "image.jpg", "alt": "Description", "title": "Caption" }
]
{% end %}
```

### 4. **Mermaid** (`mermaid.html`)
Embeds Mermaid.js diagrams - requires mermaid.js loaded via `config.toml` or page frontmatter

All custom shortcodes use `load_data(literal = body, format="json")` to parse JSON from markdown body.

## Styling System

### SCSS Architecture
- **Main**: `sass/style.scss` imports all partials
- **Variables**: `sass/_variables.scss` defines theme tokens
- **Custom CSS**: Added via `config.toml` extra.styles array:
  ```toml
  [extra]
  styles = [
      "/css/timeline.css",
      "/css/mermaid.css",
      "/css/skills.css",
      "/css/gallery.css",
  ]
  ```

### Theme Customization
- Custom SCSS mods can be added in `sass/mods/` (see examples like `_modern-headings.scss`)
- The theme supports dark/light modes with `accent_color` and `accent_color_dark` in config

## Frontmatter Conventions

### Required Fields
```toml
+++
title = "Page Title"
description = "Meta description"
+++
```

### Common Optional Fields
- `date = 2023-08-31` - Publication date (ISO format)
- `updated = "2024-06-21"` - Last update date
- `[taxonomies]` - Tags: `tags = ["Tag1", "Tag2"]`
- `[extra]` section for theme-specific options

### Extra Section Examples
```toml
[extra]
toc = true                    # Enable table of contents
toc_inline = true             # Show TOC inline
banner = "image.webp"         # Hero image (colocated)
go_to_top = true             # Show "back to top" button
styles = ["custom.css"]       # Page-specific CSS
scripts = ["custom.js"]       # Page-specific JS

[extra.comments]              # Mastodon comments integration
host = "mastodon.online"
user = "reprintedAron"
```

## Configuration Patterns

### Key Config Locations
- **Site config**: `config.toml` (root)
- **Theme config**: `themes/duckquill/config.toml` (reference only)
- **Old config backup**: `old_config.toml`

### Important Config Sections
```toml
[extra.nav]
links = [
    { url = "https://...", name = "Name", external = true }
]

[extra.footer]
socials = [
    { url = "mailto:...", name = "Email", icon = "..." }
]
show_copyright = true
show_source = true
```

## Development Best Practices

1. **Always run from project root**: Zola expects to be run from the directory containing `config.toml`

2. **Script execution**: Helper scripts expect to be run from `scripts/` directory (use relative path `../content`)

3. **macOS compatibility**: Scripts use `sed -i ''` syntax (empty string for in-place edit without backup)

4. **Asset colocation**: Place images next to markdown files, reference with relative paths

5. **Multilingual workflow**: Create German base content first, then English `.en.md` versions

6. **Custom shortcodes**: JSON data must be valid - use arrays of objects with consistent schemas

## Common Pitfalls

- **Don't edit `public/`**: It's generated output, changes will be overwritten
- **Don't modify theme files directly**: Override via `templates/` or `sass/` in project root
- **Shortcode JSON**: Must be properly formatted arrays; missing commas or quotes will break builds
- **Frontmatter format**: Zola uses `+++` TOML delimiters, not `---` YAML
- **Date formats**: Use ISO 8601 (`YYYY-MM-DD`) for dates in frontmatter

## External Integrations

- **GoatCounter Analytics**: Configured via `[extra.goatcounter]` section
- **Mastodon Comments**: Fetches replies from Mastodon posts via API
- **Source Repository**: Links to Forgejo instance at `forgejo.petau.net`