aron/awebsite
aron/awebsite
1
0
Fork 0
Code Issues Pull requests Wiki Activity Actions

more translation

Browse source
This commit is contained in:
Aron Petau 2025-10-06 18:01:45 +02:00
parent 2ce9ca50b5
commit a41be821c1
997 changed files with 33247 additions and 32490 deletions
Download patch file Download diff file Expand all files Collapse all files

433
.github/copilot-instructions.md vendored
View file

@ -1,82 +1,223 @@
# Copilot Instructions for AI Agents
## Project Overview
- This is a Zola static site, using the "Duckquill" theme (see `themes/duckquill`).
- Content is organized in Markdown files under `content/` (with language variants like `.de.md` for German).
- Static assets (images, CSS, JS) are in `public/` and `static/`.
- Theme customizations and templates are in `themes/duckquill/` and `templates/`.
- Configuration is managed via `config.toml` and language files in `i18n/`.
This is **aron.petau.net**, a multilingual personal portfolio and blog built with:
- **Framework**: [Zola](https://www.getzola.org/) static site generator (v0.19+)
- **Theme**: Customized [Duckquill](https://duckquill.daudix.one) 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
## Key Workflows
- **Build the site:** Use Zola (`zola build`) to generate static files. Output goes to `public/`.
- **Serve locally:** Use `zola serve` for local development with live reload.
- **Content updates:** Add/edit Markdown files in `content/` (use `.de.md` for German, `.md` for English).
- **Theme changes:** Edit files in `themes/duckquill/` or `templates/` for layout and style.
- **Static assets:** Place images, CSS, JS in `static/` (copied as-is to output).
- **SASS/SCSS:** Source styles in `sass/`, compiled by Zola if referenced in theme.
- **Scripts:** Shell scripts in `scripts/` automate content and frontmatter management (e.g., `add_update_frontmatter.sh`).
## 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
```bash
# 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
```bash
# 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:
```toml
+++
title = "Project Title"
authors = ["Aron Petau"]
date = 2025-10-06
description = "Brief description"
[taxonomies]
tags = ["tag1", "tag2"]
[extra]
show_copyright = true
show_shares = true
+++
```
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:** Each page has `.md` (English) and `.de.md` (German) variants. Use matching filenames for translations.
- **Frontmatter:** All Markdown files require Zola-compatible TOML frontmatter.
- **Directory structure:**
- `content/pages/` for main site pages
- `content/project/` for project posts (each project in its own subfolder)
- **Theme:** Only modify `themes/duckquill/` for theme changes; avoid editing Zola core files.
- **Static files:** Use `static/` for assets that should be copied verbatim to the output.
## Integration Points
- **Zola:** All builds and local serving use Zola CLI.
- **External links:** Theme and documentation reference [Duckquill demo](https://duckquill.daudix.one).
- **CI/CD:** No explicit CI/CD config found; manual builds expected.
### 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
## Examples
- To add a new German page: create `content/pages/newpage.de.md` with TOML frontmatter.
- To update theme CSS: edit `themes/duckquill/static/css/` or `sass/` and rebuild.
- To run locally: `zola serve` from project root.
### 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 several custom shortcodes for content enhancement:
### Gallery Shortcode
Used for creating image galleries with lightbox support:
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`
```md
{% gallery() %}
[
{"file": "image1.jpg", "alt": "Description", "title": "Optional Caption"},
{"file": "image2.jpg", "alt": "Description"}
{"file": "image2.jpg", "alt": "Description", "title": "Another caption"}
]
{% end %}
```
Images must be in the same directory as the content file.
### Mermaid Shortcode
For rendering diagrams:
**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`
```md
{% mermaid() %}
graph TD
A[Start] --> B[End]
A[Start] --> B[Process]
B --> C{Decision}
C -->|Yes| D[End]
C -->|No| A
{% end %}
```
### Skills Shortcode
For displaying categorized skills with optional icons and links:
**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`
```md
{% skills() %}
[
{
"name": "Category Name",
"name": "Programming",
"skills": [
{"name": "Skill Name", "icon": "fa-icon-class", "link": "optional-url"},
{"name": "Another Skill"}
{"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 %}
```
### Timeline Shortcode
For chronological events and experiences:
**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`
```md
{% timeline() %}
[
@ -84,20 +225,208 @@ For chronological events and experiences:
"from": "2025-01",
"to": "2025-12",
"title": "Event Title",
"location": "Optional Location",
"icon": "optional-icon-class",
"body": "Event description",
"link": "optional-url"
"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 %}
```
## References
- Theme docs: `themes/duckquill/README.md`
- Main config: `config.toml`
- Scripts: `scripts/`
- Content: `content/`
**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):
```bash
zola serve
```
2. **Build site** (outputs to `public/`):
```bash
zola build
```
3. **Run tests** (comprehensive validation):
```bash
./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
```bash
# 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
```bash
# 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
```bash
# Add custom SCSS (never edit themes/duckquill/)
nano sass/_custom.scss
# Add to sass/style.scss imports
# Rebuild
zola build
```
### Add a PDF document
```bash
# 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
```markdown
{% 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
```bash
./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](https://duckquill.daudix.one))
- **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/`