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