-# Content Management Instructions - opencode
-
-You are the content curator for https://danix.xyz. You operate strictly within the `content/` directory.
-
-## 🌍 Multilingual Content Handling
-The site supports Italian (default) and English. You must manage content as follows:
-- **File Naming**: Within each Page Bundle, use language suffixes:
- - `index.md` or `index.it.md` for Italian content.
- - `index.en.md` for the English translation.
-- **Consistency**: Ensure that if an article exists in Italian, an English version is created (or marked as a translation) to maintain site integrity.
-- **Front-matter**: Translate all metadata (titles, descriptions, tags) for each language file.
-
-## 🖋 Editorial Standards
-- **Structure**: Exclusively use **Page Bundles** (`content/section/title/index.md`).
-- **Assets**: Images and attachments reside within the specific bundle folder; they are shared between language versions.
-- **Front-matter**: YAML format. Mandatory fields: `title`, `date`, `draft: false`, `tags`, `categories`, `description`.
-
-## 🛠 Shortcode Usage
-Raw HTML is forbidden. Use the shortcodes provided by the theme:
-- **Contact**: Use `{{< contact_form >}}`.
-- **Media**: Use specific shortcodes for images, galleries, and videos.
-- **Reference**: Consult `SHORTCODES.md` for parameters.
-
-## 🤝 Workflow
-1. **Verification**: If a shortcode or i18n string is missing, notify the user and ask for instructions.
-2. **Taxonomy**: Keep tags and categories consistent and translated across languages.
\ No newline at end of file
+# Content Management Instructions - danix.xyz
+
+You are the content curator for https://danix.xyz. You operate strictly within the `content/` directory and manage bilingual (IT/EN) content using Hugo Page Bundles.
+
+## 🌍 Multilingual Content Structure
+
+The site is **bilingual with Italian as the default language** and English as the secondary language. All content must be organized to support seamless language switching.
+
+### Languages
+
+- **Italian (IT)**: Default language for the site
+- **English (EN)**: Secondary language with full translations
+
+### Directory Structure
+
+```
+content/
+├── _index.md # Landing page (IT only)
+├── it/
+│ ├── _index.md # Articles list (IT)
+│ └── articles/
+│ └── article-slug/
+│ ├── index.md # Article content (IT)
+│ └── images/
+│ ├── featured.jpg
+│ └── gallery-01.jpg
+└── en/
+ ├── _index.md # Articles list (EN)
+ └── articles/
+ └── article-slug/
+ ├── index.en.md # Article content (EN)
+ └── images/ # Shared with IT version
+ ├── featured.jpg
+ └── gallery-01.jpg
+```
+
+### File Naming Conventions
+
+- **Italian content**: Use `index.md` or `index.it.md`
+- **English content**: Use `index.en.md`
+- **Assets**: All images and attachments are shared between language versions (no duplication)
+- **Consistency**: If an article exists in Italian, create an English translation in the corresponding English bundle
+
+### Content Structure Example
+
+A typical article Page Bundle looks like this:
+
+```
+content/it/articles/why-i-love-go/
+├── index.md # Article with front-matter
+├── images/
+│ ├── gopher.jpg
+│ ├── code-snippet.png
+│ └── architecture.jpg
+└── gallery/
+ ├── 01.jpg
+ ├── 02.jpg
+ └── 03.jpg
+```
+
+The English version shares the same assets:
+
+```
+content/en/articles/why-i-love-go/
+├── index.en.md # English translation
+└── images/ # Symbolic link or relative reference to IT images
+```
+
+## 📋 Article Front-Matter
+
+All articles use Page Bundles with YAML front-matter. The front-matter defines metadata for the article and controls how it's displayed throughout the site.
+
+### Required Fields
+
+- **title**: Article headline (translated for each language)
+- **date**: Publication date (ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`)
+- **draft**: Set to `false` when published, `true` while in development
+- **type**: Article type (see Article Types section): `life`, `photo`, `link`, `quote`, or `tech`
+- **tags**: List of content tags (translated, comma-separated)
+- **categories**: List of categories (translated, comma-separated)
+- **description**: Brief summary for listings and SEO (translated)
+
+### Optional Fields
+
+- **pinned**: Set to `true` to pin article to top of listings
+- **updated**: Date of last significant update (ISO 8601 format)
+- **featured_image**: Path to featured image for photo articles
+- **featured_image_caption**: Caption for the featured image
+- **external_url**: URL for link-type articles
+- **link_title**: Title of external link
+- **quote_text**: The quote content for quote-type articles
+- **quote_author**: Author of the quote
+
+## 📝 Article Types
+
+### 1. Life
+
+Generic blog posts, personal essays, and thoughts on various topics.
+
+**Description**: Use this type for personal reflections, essays, tutorials, announcements, and general blog content.
+
+**Front-matter example**:
+```yaml
+---
+title: "Why I Started This Blog"
+date: 2026-04-15T10:30:00Z
+draft: false
+type: life
+tags: "blogging, thoughts, programming"
+categories: "personal"
+description: "Exploring the reasons behind starting my personal blog and what I hope to share."
+---
+```
+
+**Content**: Standard markdown, any length, supports all shortcodes (images, galleries, contact form).
+
+**File structure**:
+```
+content/it/articles/why-i-started-blogging/
+├── index.md
+└── images/
+ └── desk-setup.jpg
+```
+
+**Example URL**: `/it/articles/why-i-started-blogging/`
+
+### 2. Photo
+
+Photo essays, galleries, and visual-focused content.
+
+**Description**: Use this type for travel photography, galleries, visual stories, and photo essays with accompanying text.
+
+**Front-matter example**:
+```yaml
+---
+title: "Mountain Hiking Adventure"
+date: 2026-04-10T14:20:00Z
+draft: false
+type: photo
+featured_image: "/images/mountain-peak.jpg"
+featured_image_caption: "Summit view at dawn"
+tags: "photography, travel, nature"
+categories: "photos"
+description: "A visual journey through the Alpine mountains with stunning photography."
+---
+```
+
+**Content**: Markdown with image and gallery shortcodes for visual storytelling.
+
+**File structure**:
+```
+content/it/articles/mountain-hiking-adventure/
+├── index.md
+└── images/
+ ├── mountain-peak.jpg
+ ├── hiking-trail.jpg
+ ├── alpine-lake.jpg
+ └── sunset-view.jpg
+```
+
+**Requirements**: Must include `featured_image` and preferably `featured_image_caption`.
+
+**Example URL**: `/it/articles/mountain-hiking-adventure/`
+
+### 3. Link
+
+Bookmarks, external content recommendations, and brief commentary on articles from other sources.
+
+**Description**: Use this type to share and comment on interesting external resources without writing a full article.
+
+**Front-matter example**:
+```yaml
+---
+title: "Interesting Read: The Unix Philosophy"
+date: 2026-04-08T09:15:00Z
+draft: false
+type: link
+external_url: "https://en.wikipedia.org/wiki/Unix_philosophy"
+link_title: "The Unix Philosophy"
+tags: "unix, philosophy, programming"
+categories: "links"
+description: "An insightful overview of Unix principles and their lasting impact on software design."
+---
+```
+
+**Content**: Brief commentary or summary of the external resource (optional).
+
+**File structure**:
+```
+content/it/articles/unix-philosophy-link/
+└── index.md
+```
+
+**Requirements**: Must include `external_url` and `link_title`.
+
+**Example URL**: `/it/articles/unix-philosophy-link/`
+
+### 4. Quote
+
+Pull quotes, inspirational content, and quotations with optional commentary.
+
+**Description**: Use this type to highlight meaningful quotes, create inspirational content, or document memorable ideas.
+
+**Front-matter example**:
+```yaml
+---
+title: "On Simplicity"
+date: 2026-04-05T11:00:00Z
+draft: false
+type: quote
+quote_text: "The greatest enemy of understanding is complexity."
+quote_author: "Unknown"
+tags: "philosophy, wisdom, simplicity"
+categories: "quotes"
+description: "A meditation on simplicity and its role in clear thinking."
+---
+```
+
+**Content**: Optional - add commentary, reflection, or context about the quote.
+
+**File structure**:
+```
+content/it/articles/simplicity-quote/
+└── index.md
+```
+
+**Requirements**: Must include `quote_text` and `quote_author`.
+
+**Example URL**: `/it/articles/simplicity-quote/`
+
+### 5. Tech
+
+Technical articles, tutorials, guides, and programming content with code examples.
+
+**Description**: Use this type for technical writing, tutorials, how-to guides, and in-depth programming articles.
+
+**Front-matter example**:
+```yaml
+---
+title: "Building a Go CLI Tool"
+date: 2026-04-01T15:45:00Z
+draft: false
+type: tech
+tags: "golang, cli, programming"
+categories: "tutorials"
+description: "A step-by-step guide to building a command-line tool in Go with example code."
+---
+```
+
+**Content**: Markdown with code blocks, syntax highlighting handled automatically via Chroma.
+
+**Code block example**:
+````markdown
+```go
+package main
+
+import (
+ "fmt"
+ "flag"
+)
+
+func main() {
+ name := flag.String("name", "World", "name to greet")
+ flag.Parse()
+ fmt.Printf("Hello, %s!\n", *name)
+}
+```
+````
+
+**File structure**:
+```
+content/it/articles/building-go-cli-tool/
+├── index.md
+└── images/
+ └── cli-output.png
+```
+
+**Example URL**: `/it/articles/building-go-cli-tool/`
+
+## 🎨 Editorial Standards
+
+Follow these standards to maintain consistency and quality across the site.
+
+### Structure
+
+- **Always use Page Bundles**: Organize all content using Hugo's Page Bundle pattern (`content/section/slug/index.md`)
+- **Never use raw HTML**: All formatting must use markdown and shortcodes only
+- **Asset organization**: Store images and attachments within the bundle's directory for easy management
+
+### Front-Matter Checklist
+
+Before publishing any article, verify:
+
+- [ ] **title**: Clear, descriptive headline
+- [ ] **date**: Correct publication date (ISO 8601)
+- [ ] **draft**: Set to `false` for published articles
+- [ ] **type**: One of the five article types
+- [ ] **tags**: Consistent with site taxonomy
+- [ ] **categories**: Consistent with site taxonomy
+- [ ] **description**: Compelling summary for listings
+- [ ] **Type-specific fields**: Include required fields for your article type
+
+## 🔌 Shortcode Usage
+
+Use these four shortcodes to enhance your content. For detailed documentation, see [SHORTCODES.md](./SHORTCODES.md).
+
+### Images
+
+Responsive images with optional captions and lazy-loading:
+
+```
+{{< image src="/images/mountain.jpg" alt="Mountain landscape" caption="Hiking in the Alps" >}}
+```
+
+### Galleries
+
+Create responsive image grids:
+
+```
+{{< gallery cols="3" >}}
+
+
+
+{{< /gallery >}}
+```
+
+### Gravatar
+
+Display author profiles with Gravatar:
+
+```
+{{< gravatar email="danix@danix.xyz" alt="Profile" class="w-32 h-32 rounded-full" >}}
+```
+
+### Contact Form
+
+Embed an interactive contact form:
+
+```
+{{< contact_form >}}
+```
+
+## 📚 Taxonomy Consistency
+
+Maintain consistent tags and categories across both language versions to enable proper content filtering and organization.
+
+### Tag Mappings
+
+Keep translations consistent across languages. Example mappings:
+
+| Italian | English |
+|---------|---------|
+| programmazione | programming |
+| tutorial | tutorial |
+| sicurezza | security |
+| golang | golang |
+| linux | linux |
+
+### Category Mappings
+
+Ensure categories are translated consistently:
+
+| Italian | English |
+|---------|---------|
+| articoli | articles |
+| foto | photos |
+| link | links |
+| citazioni | quotes |
+| tutorial | tutorials |
+
+### Best Practices
+
+- Create a consistent taxonomy document for your team
+- Use lowercase tags and categories
+- Avoid redundant tags (don't use both "programming" and "programming-tutorial")
+- Translate tags and categories when creating English versions
+
+## 🚀 Content Workflow
+
+Follow this workflow when creating and publishing new articles.
+
+### Creating a New Article
+
+1. **Create the directory structure**:
+ ```bash
+ mkdir -p content/it/articles/my-article-slug
+ ```
+
+2. **Create the Italian index.md** with front-matter:
+ ```yaml
+ ---
+ title: "Article Title"
+ date: 2026-04-15T10:00:00Z
+ draft: true
+ type: life
+ tags: "tag1, tag2"
+ categories: "category"
+ description: "Brief description"
+ ---
+
+ Article content here in markdown.
+ ```
+
+3. **Add assets** (images, etc.) to the bundle:
+ ```bash
+ mkdir content/it/articles/my-article-slug/images
+ # Copy images to the images folder
+ ```
+
+4. **Create the English translation** (index.en.md) in the English bundle:
+ ```bash
+ mkdir -p content/en/articles/my-article-slug
+ # Create index.en.md with translated front-matter and content
+ # Reference the same images directory
+ ```
+
+5. **Test locally** with Hugo:
+ ```bash
+ hugo server
+ ```
+
+6. **Review the preview** at http://localhost:1313 in both languages
+
+7. **Finalize when ready**: Set `draft: false` in the front-matter
+
+8. **Push to production**: Commit and deploy the changes
+
+### File Organization Tips
+
+- Use descriptive, URL-friendly slugs: `my-awesome-article` not `Article 1`
+- Store images in `images/` subfolder within the bundle
+- Use descriptive image names: `sunset-mountain.jpg` not `img1.jpg`
+- Keep bundle structure flat: avoid deep nesting of directories
+
+### Language Version Management
+
+- When creating English versions, ensure front-matter translations are accurate
+- Use the same directory structure in both `content/it/` and `content/en/`
+- Images are shared; use the same paths in both language versions
+- If one language version needs updating, both should be reviewed for consistency
+
+---
+
+**Questions or issues?** Refer to [SHORTCODES.md](./SHORTCODES.md) for shortcode documentation or [CLAUDE.md](./CLAUDE.md) for theme development guidelines.
