path: root/AGENTS.md

# 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" >}}
![Mountain View 1](/images/mountain1.jpg)
![Mountain View 2](/images/mountain2.jpg)
![Mountain View 3](/images/mountain3.jpg)
{{< /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.