From: Danilo M. Date: Wed, 15 Apr 2026 13:54:19 +0000 (+0200) Subject: docs: update AGENTS.md with comprehensive content management guide X-Git-Tag: release_22042026-1342~257 X-Git-Url: https://git.danix.xyz/?a=commitdiff_plain;h=a73106a477875faa1340c06ab3ac48b7ce5f2104;p=danix.xyz-2.git docs: update AGENTS.md with comprehensive content management guide --- diff --git a/AGENTS.md b/AGENTS.md index 1ba87e7..e20b7ed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,26 +1,444 @@ -# 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" >}} +![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.