Blog: Content Structure

Level 2 (Topic) — Article organization, front matter, naming conventions.

Concept

Each blog post lives in its own directory under content/posts/. The post exists in two versions: Italian (primary, index.it.md) and English (translation, index.md).

Directory Structure

content/posts/
├── <post-slug>/
│   ├── index.md            # English version
│   ├── index.it.md         # Italian version
│   ├── featured.jpg        # Optional thumbnail (600x600 max)
│   └── featured.png        # Source image (converted to JPG by process-blog-image.sh)

Post Slug Convention

  • Kebab-case, English
  • Derived from article title
  • Example: blackout-test-power-loss-resurrection

Front Matter (TOML)

Required fields:

+++
title = "Article Title"
date = 2026-04-29T00:00:00+00:00
draft = false
tags = ["Kubernetes", "Talos OS"]
description = "One-sentence summary of the article."
+++

The date is set to 4 hours before publication time (to account for the CI/CD delay).

Bilingual Model

FileLanguageCreated by
index.it.mdItalianblog-writer Phase 2
index.mdEnglishblog-writer Phase 4 (translation)

The Italian version is always written first. The English version is a technical translation produced after user approval.

  • Source: featured.png (any size)
  • Processed: bash AGENTS.ctx/blog-writer/assets/process-blog-image.sh featured.png
  • Output: featured.jpg (600x600 max, 85% quality)
  • Original PNG is deleted after conversion

Taxonomy

Tags are the primary taxonomy. Categories, authors, and series are also configured but tags are the most used. Tags are lowercase and technical.

See Also