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 English as the default language** and Italian as the secondary language. All content must be organized to support seamless language switching.

### Languages

- **English (EN)**: Default language for the site
- **Italian (IT)**: Secondary language with full translations

### Directory Structure

```
content/
├── it/
│   ├── _index.md                      # Articles list (IT)
│   └── articles/
│       └── article-slug/
│           └── index.md            # Article content (IT)
└── en/
    ├── _index.md                      # Articles list (EN)
    └── articles/
        └── article-slug/
            └── index.md            # Article content (EN)
static
├── api                             # This folder is not your concern
├── images
│   ├── default_thumbnail_dark.png
│   ├── default_thumbnail_light.png
│   ├── fav.png
│   └── lampD.png
└── uppies
    ├── 2009
    │   ├── 06
    │   │   └── featured_image.jpg
    │   └── 07
    │       └── featured_image.jpg
    ├── 2010
    │   ├── 03
    │   ├── 11
    │   │   └── featured_image.jpg
    │   └── 12
    ├── 2011
    │   ├── 01
    │   ├── 02
    │   ├── 07
    │   │   ├── gallery_image01.jpg
    │   │   ├── gallery_image02.jpg
    │   │   ├── gallery_image03.jpg
    │   │   ├── gallery_image04.jpg
    │   │   └── featured_image.jpg
    [...]
```

### File Naming Conventions

- **Italian content**: Use `index.md`
- **English content**: Use `index.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 and vice-versa. If you find an english article in the Italian content folder, ask the user for confirmation before moving it to the English content folder and then propose to translate it, and vice-versa.

### Content Structure Example

A typical article Page Bundle looks like this:

```
content/it/articles/why-i-love-go/
└── index.md                    # Article with front-matter
```

The English version shares the same assets:

```
content/en/articles/why-i-love-go/
└── index.md                 # English translation
```

## 📋 Article Front-Matter

All articles use Page Bundles with TOML 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`)
- **author** = "Danilo M."
- **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)
- **image** = Path to featured image for photo articles
- **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**:
```toml
+++
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
```

**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**:
```toml
+++
title = "Mountain Hiking Adventure"
date = "2026-04-10T14:20:00Z"
draft = false
type = "photo"
image = "/images/mountain-peak.jpg"
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
```

**Requirements**: Must include `image`.

**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**:
```toml
+++
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**:
```toml
+++
title = "On Simplicity"
date = "2026-04-05T11:00:00Z"
draft = false
type = "quote"
tags = ["philosophy, wisdom, simplicity"]
categories = ["quotes"]
description = "A meditation on simplicity and its role in clear thinking."
+++
```

**Content**: use the shortcode `quote` to render the content of the quote.

**File structure**:
```
content/it/articles/simplicity-quote/
└── index.md
```

**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**:
```toml
+++
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
```

**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 `static/uppies` directory, organized by year and month for ease of inclusion.

### 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

The theme provides powerful shortcodes to enhance your content with images, galleries, forms, and text styling. **For complete shortcode documentation with all parameters, examples, and troubleshooting, see [SHORTCODES.md](./SHORTCODES.md)** — this section is a quick reference.

### Structural Shortcodes

#### 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" >}}
```

#### Video

Embed responsive videos (local files or YouTube):

```
{{< video src="demo.webm" >}}
{{< video id="dQw4w9WgXcQ" title="YouTube Video" >}}
```

#### Contact Form

Embed an interactive contact form:

```
{{< contact >}}
```

#### Quote

Display blockquote with optional attribution:

```
{{< quote source="Author Name" >}}
Your quote text here
{{< /quote >}}
```

#### Actions

Styled action buttons (downloads, CTAs):

```
{{< actions url="https://example.com/file.zip" desc="Download ZIP" >}}
```

### Inline Text Shortcodes

Simple inline wrappers for styling text within paragraphs. No parameters needed.

#### Strikethrough

Mark text as struck-through or removed:

```
This text is {{< strike >}}wrong{{< /strike >}} and has been corrected.
```

#### Emphasis

Apply semantic emphasis (renders as italic):

```
This is {{< em >}}very important{{< /em >}} information.
```

#### Drop Cap

Style the first letter(s) of a paragraph with a drop cap effect:

```
{{< dropcap >}}Once upon a time{{< /dropcap >}}, in a land far away...
```

### When to Use SHORTCODES.md

Refer to [SHORTCODES.md](./SHORTCODES.md) for:
- Full parameter documentation for each shortcode
- Advanced examples and customization options
- CSS class references for styling
- Accessibility and browser compatibility notes
- Troubleshooting and error resolution

## 📚 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:
   ```toml
   +++
   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 static/uppies/<YEAR>/<MONTH>/
   # Copy images to the MONTH folder
   ```

4. **Create the English translation** (index.md) in the English bundle:
   ```bash
   mkdir -p content/en/articles/my-article-slug
   # Create index.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 `static/uppies/` folder arranged by year and month subfolders
- 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. Always ask clarifying questions to the user before making changes.