209 lines
6.4 KiB
Markdown
209 lines
6.4 KiB
Markdown
# 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`
|