Initial commit
This commit is contained in:
parent
80700ab28b
commit
e89aa4f978
17 changed files with 387 additions and 89 deletions
209
.github/copilot-instructions.md
vendored
Normal file
209
.github/copilot-instructions.md
vendored
Normal file
|
|
@ -0,0 +1,209 @@
|
|||
# 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`
|
||||
Loading…
Add table
Add a link
Reference in a new issue