2025-10-10 12:28:19 +02:00

6.4 KiB

Raw Permalink Blame History

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

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

create_german_stubs.sh: Creates .de.md versions from base .md files
- Automatically prefixes titles with "Übersetzung: "
- Uses macOS-compatible sed -i '' syntax
add_update_frontmatter.sh: Adds updated field to frontmatter after existing date field
organize.sh: Converts ISO-dated files (2023-06-01-post.md) into folder structure (2023-06-01-post/index.md)
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:

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

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

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

[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

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

[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

[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

Always run from project root: Zola expects to be run from the directory containing config.toml
Script execution: Helper scripts expect to be run from scripts/ directory (use relative path ../content)
macOS compatibility: Scripts use sed -i '' syntax (empty string for in-place edit without backup)
Asset colocation: Place images next to markdown files, reference with relative paths
Multilingual workflow: Create German base content first, then English .en.md versions
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

6.4 KiB Raw Permalink Blame History