--- /dev/null
+# Content Organization Guide
+
+A practical guide for managing content on your personal blog. Use this when creating, editing, or organizing articles and pages.
+
+---
+
+## Table of Contents
+
+1. [Directory Structure](#directory-structure)
+2. [Content Types](#content-types)
+3. [Creating New Content](#creating-new-content)
+4. [Front Matter Reference](#front-matter-reference)
+5. [Publishing Workflow](#publishing-workflow)
+6. [Best Practices](#best-practices)
+7. [Examples](#examples)
+
+---
+
+## Directory Structure
+
+```
+content/
+├── _index.md # Home page (don't modify much)
+├── articles/ # All blog content lives here
+│ ├── _index.md # Articles section landing page
+│ ├── my-first-article/
+│ │ ├── index.md # Article content
+│ │ └── featured-image.jpg # Images bundled with article
+│ ├── another-article.md
+│ └── ...
+└── is/ # Static pages (about, contact, etc.)
+ ├── _index.md # About page (/)
+ ├── here.md # Contact page (/is/here)
+ └── ... # Other static pages
+```
+
+**Key Rules:**
+- All blog posts go in `content/articles/` — not directly in `content/`
+- Static pages (about, contact, uses, now, etc.) go in `content/is/`
+- Use folders for articles with images; use `.md` files for text-only articles
+- Folder names become URL slugs, so use lowercase and hyphens: `my-first-article/`
+
+---
+
+## Content Types
+
+Your blog supports five content types for articles. Each type is visually distinct in the feed with its own badge color.
+
+### **tech** (Purple #a855f7)
+Technical articles: programming tutorials, IT learnings, engineering breakdowns, code walkthroughs, tool reviews.
+
+**Examples:**
+- Understanding Kubernetes networking
+- Building a REST API with Go
+- Setting up a CI/CD pipeline
+- Debugging memory leaks
+
+### **life** (Amber #f59e0b)
+Personal reflections, philosophy, life lessons, observations about slowing down, productivity thoughts, life updates.
+
+**Examples:**
+- On slowing down in a world that won't
+- What I learned from a failed project
+- Balancing work and life
+- Reflections on burnout
+
+### **quote** (Green #00ff88)
+Meaningful quotes you find interesting, with optional context about why they matter to you.
+
+**Examples:**
+- "The obstacle is the way" — Marcus Aurelius
+- "It's about the work, not the reward" — Unknown
+- "Simplicity is the ultimate sophistication" — da Vinci
+
+### **link** (Cyan #38bdf8)
+Interesting links from the web with optional your own commentary. Can be standalone or with analysis.
+
+**Examples:**
+- [Article] The future of Rust in systems programming
+- [Video] Why Git is hard to understand
+- [Thread] Thoughts on API design principles
+
+### **photo** (Pink #ec4899)
+Photos or visual content you create and want to share. Can include captions or stories.
+
+**Examples:**
+- Photos from a recent trip
+- A project you built (with pictures)
+- Visual design work you want to showcase
+
+---
+
+## Creating New Content
+
+### Quick Start: Use Hugo CLI
+
+```bash
+# Create a new article
+hugo new articles/my-article-title/index.md
+
+# Create a static page (about, contact, etc.)
+hugo new is/page-title.md
+```
+
+The CLI uses your archetypes to generate files with proper front matter.
+
+### Manual Creation
+
+If you prefer, just create `.md` files directly in the right folder. Copy the front matter structure from examples below.
+
+---
+
+## Front Matter Reference
+
+Every content file starts with TOML front matter (between `+++` markers). Here's what each field does:
+
+```toml
++++
+title = "Article Title" # Required: The page title (appears in feed and page)
+date = 2026-04-05T10:30:00Z # Required: Publication date (ISO 8601 format)
+draft = false # Optional: Set to true to hide from published site
+type = "tech" # Required for articles: tech, life, quote, link, photo
+featured = false # Optional: Set to true to pin to top of homepage
+image = "featured-image.jpg" # Optional: Image path for card thumbnail (relative to content file)
+description = "One or two..." # Optional: Short summary (2 lines max) for feed cards
++++
+```
+
+### Field Details
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `title` | Yes | Used as page heading and in feeds. Keep under 80 chars for better layout. |
+| `date` | Yes | When the article was published. Format: `2026-04-05T10:30:00Z` (UTC). Hugo sorts by this. |
+| `draft` | No | Set to `true` to hide from published site (useful for work-in-progress). |
+| `type` | Yes (articles) | One of: `tech`, `life`, `quote`, `link`, `photo`. Not needed for static pages. |
+| `featured` | No | Set to `true` to pin one article to the top of the homepage feed. Only the first featured post shows. |
+| `image` | No | Path to a featured image (relative to the content file folder). Shows as thumbnail in card. |
+| `description` | No | Short summary for feed cards. If omitted, Hugo uses the first 120 characters of your content. Keep to 2 lines max (~150 chars). |
+
+---
+
+## Publishing Workflow
+
+### Before Publishing
+
+1. **Write your content** — Use the body section after `+++` for markdown
+2. **Add front matter** — Fill in title, date, type, description, image (if applicable)
+3. **Set draft = false** — Only non-draft content appears on the live site
+4. **Preview locally** — Run `hugo server` to see how it looks
+
+### Publishing
+
+```bash
+# Start local preview
+hugo server
+
+# Open http://localhost:1313 in your browser
+# Check homepage, articles page, filters, detail pages
+
+# When satisfied:
+git add content/
+git commit -m "content: add [title] article"
+git push origin master
+```
+
+### Important Notes
+
+- **Draft status**: Set `draft = true` while writing. Change to `draft = false` when ready to publish.
+- **Featured**: Only set one article to `featured = true`. It will appear first on the homepage, even if it's not the newest.
+- **Dates in the future**: Articles with future dates are treated as drafts (won't appear until that date passes).
+
+---
+
+## Best Practices
+
+### Article Length & Structure
+
+- **Tech articles**: 800–2000 words. Include code examples, explanations, and takeaways.
+- **Life reflections**: 300–1000 words. Personal, conversational tone is best.
+- **Quotes**: 50–200 words. Include the quote, attribution, and 1–2 sentences on why it resonates.
+- **Links**: 50–500 words. Headline, link, and 1–3 sentences of context or summary.
+- **Photos**: 100–500 words. Caption, story, or context about the image.
+
+### Writing Tips
+
+1. **Titles should be specific** — "Understanding X" is better than "Learning about X"
+2. **Descriptions should hook** — Write summaries that make people want to click
+3. **Use code blocks for technical content** — Syntax highlighting works automatically
+4. **Include images for visual interest** — Photos break up text and catch attention
+5. **Link to related posts** — Help readers discover more of your content
+
+### File Organization
+
+- **Use descriptive folder/file names** — `understanding-kubernetes-networking/` is better than `post1/`
+- **Group related assets** — If an article has images, keep them in the same folder
+- **Avoid special characters** — Stick to letters, numbers, hyphens, underscores
+- **Use lowercase** — Slugs should be lowercase (Hugo enforces this in URLs)
+
+### Images
+
+- **Optimal sizes**: Featured images 1200x600px or wider (16:9 aspect ratio)
+- **File formats**: JPG for photos, PNG for diagrams, WebP for web-optimized
+- **File size**: Keep images under 500KB (use compression tools)
+- **Naming**: Use lowercase, hyphens, descriptive names: `kubernetes-architecture.jpg`
+
+### Code Blocks
+
+Include a language identifier for syntax highlighting:
+
+````markdown
+```python
+def hello_world():
+ print("Hello, world!")
+```
+````
+
+Supported languages: Python, Go, JavaScript, TypeScript, Bash, SQL, YAML, HTML, CSS, Rust, and many more.
+
+---
+
+## Examples
+
+### Example 1: Tech Article with Images
+
+**File structure:**
+```
+content/articles/understanding-rest-apis/
+├── index.md
+├── rest-principles.png
+└── api-flow.png
+```
+
+**Front matter:**
+```toml
++++
+title = "Understanding REST APIs: A Practical Guide"
+date = 2026-04-05T09:00:00Z
+draft = false
+type = "tech"
+featured = false
+image = "rest-principles.png"
+description = "REST APIs power the web. Learn the six constraints that make them scalable and how to build your own."
++++
+```
+
+**Body:**
+```markdown
+REST (Representational State Transfer) is an architecture style for building web APIs...
+
+## The Six Constraints
+
+1. **Client-Server Architecture** — Separation of concerns...
+2. **Statelessness** — Each request contains all needed information...
+
+## Building Your First REST API
+
+Here's how to build a simple API with Go:
+
+```go
+package main
+
+import (
+ "net/http"
+)
+
+func main() {
+ http.HandleFunc("/api/hello", func(w http.ResponseWriter, r *http.Request) {
+ w.Write([]byte("Hello, REST!"))
+ })
+ http.ListenAndServe(":8000", nil)
+}
+```
+
+...
+```
+
+### Example 2: Life Reflection
+
+**File: `content/articles/slowing-down.md`**
+
+```toml
++++
+title = "On Slowing Down in a World That Won't"
+date = 2026-04-04T14:30:00Z
+draft = false
+type = "life"
+featured = false
+description = "There's a particular kind of exhaustion that comes from moving too fast. Here's what I learned about intentionality."
++++
+```
+
+**Body:**
+```markdown
+Last week I caught myself reading the same sentence five times without understanding it. My mind was already on the next task, the next meeting, the next thing to fix.
+
+That's when it hit me: I'd been running on fumes for months...
+
+## What I'm Trying Now
+
+Three small changes have made a difference:
+
+1. **One deep work block per day** — No meetings, no emails, just focused time.
+2. **Walking between tasks** — A 5-minute walk breaks the mental loop.
+3. **Saying no more often** — Turns out, most requests weren't actually urgent.
+
+The irony is that slowing down made me more productive. Not because I did more, but because what I did actually mattered...
+```
+
+### Example 3: Quote Post
+
+**File: `content/articles/obstacle-is-the-way.md`**
+
+```toml
++++
+title = "\"The Obstacle Is the Way\" — Marcus Aurelius"
+date = 2026-04-03T12:00:00Z
+draft = false
+type = "quote"
+featured = false
+description = "A powerful Stoic principle on turning problems into progress."
++++
+```
+
+**Body:**
+```markdown
+> The impediment to action advances action. What stands in the way becomes the way.
+>
+> — Marcus Aurelius, Meditations
+
+This quote resonates because it reframes failure and obstacles. Instead of seeing problems as roadblocks, Stoic philosophy teaches us to see them as *the path itself*.
+
+Every challenge I've faced that felt insurmountable at the time became the thing that taught me the most. The failed projects taught me more than the successes. The difficult conversations were more valuable than the easy ones.
+
+What obstacle are you facing right now? What if it's exactly what you need to learn next?
+```
+
+### Example 4: Link Post with Commentary
+
+**File: `content/articles/future-of-rust.md`**
+
+```toml
++++
+title = "The Future of Rust in Systems Programming"
+date = 2026-04-02T10:00:00Z
+draft = false
+type = "link"
+featured = false
+image = "rust-logo.png"
+description = "Why Rust is becoming essential for systems programming and what's coming next."
++++
+```
+
+**Body:**
+```markdown
+Read this excellent piece on [The Future of Rust in Systems Programming](https://example.com/rust-future)
+
+The author makes a compelling argument about why Rust's memory safety guarantees are becoming non-negotiable in infrastructure software. I particularly appreciated the section on how Rust adoption is accelerating in Linux kernel development.
+
+The key takeaway: safety isn't a trade-off anymore. Rust proves you can have performance *and* memory safety, which changes everything for systems programming.
+```
+
+### Example 5: Static Page (About)
+
+**File: `content/is/_index.md`** (already created, but here's how to edit it)
+
+```toml
++++
+title = "About"
+date = 2026-01-01T00:00:00Z
++++
+```
+
+**Body:**
+```markdown
+Hi, I'm Danilo. I'm an engineer and writer trying to figure out how to build good things and live well.
+
+## What I Write About
+
+- **Tech**: Systems design, Go, backend architecture, things I learn while building
+- **Life**: Reflections on work, learning, slowing down, and finding meaning
+- **Ideas**: Interesting thoughts and quotes that stick with me
+
+## What I'm Doing Now
+
+Currently building distributed systems and thinking about how to write better. I'm particularly interested in observability, performance, and the intersection of technology and philosophy.
+
+## Get in Touch
+
+Want to chat? [Send me a message](/is/here) — I read and reply to everything.
+```
+
+---
+
+## File Format & Markdown
+
+### Standard Markdown
+
+Your content is written in Markdown. Here are the basics:
+
+```markdown
+# Heading 1
+## Heading 2
+### Heading 3
+
+**Bold text**
+*Italic text*
+
+- Bullet point
+- Another point
+
+1. Numbered item
+2. Another item
+
+[Link text](https://example.com)
+
+
+
+> Blockquote text
+```
+
+### Code Blocks
+
+Fenced code blocks with language specification:
+
+````markdown
+```python
+print("Hello")
+```
+
+```javascript
+console.log("Hello");
+```
+
+```bash
+echo "Hello"
+```
+````
+
+### Images
+
+Place images in the same folder as the article:
+
+```markdown
+
+```
+
+For featured images in front matter, use just the filename:
+```toml
+image = "image-filename.jpg"
+```
+
+---
+
+## Troubleshooting
+
+### Article doesn't appear on site
+
+- **Check `draft = false`** — Draft articles don't publish
+- **Check the date** — Articles with future dates are treated as drafts
+- **Check `type`** — Articles need a valid type (tech, life, quote, link, photo)
+- **Check folder structure** — Articles must be in `content/articles/`
+
+### Image doesn't show
+
+- **Relative paths only** — Use filename only (`image.jpg`) or relative paths (`./images/image.jpg`)
+- **Place in same folder** — If in a folder article, put the image in the same folder as `index.md`
+- **Check the path** — Make sure the filename matches exactly (case-sensitive on Linux)
+
+### Feed shows wrong description
+
+- **Explicit is better** — Always set `description` in front matter instead of relying on auto-summary
+- **Keep it short** — Max 2 lines (~150 characters)
+- **Write for scanners** — People decide whether to click based on the description
+
+### Featured post not showing
+
+- **Only one per site** — If multiple articles have `featured = true`, only one displays
+- **Check date order** — The featured post shows first, then newest articles below
+- **Remove other featured flags** — Make sure only one article has `featured = true`
+
+---
+
+## Quick Reference
+
+### Create New Article
+```bash
+hugo new articles/my-article-title/index.md
+# Edit the file, add front matter, write content
+# Set draft = false when ready to publish
+```
+
+### Create New Static Page
+```bash
+hugo new is/page-name.md
+# Edit and publish like articles
+```
+
+### Preview Locally
+```bash
+hugo server
+# Open http://localhost:1313
+```
+
+### Commit and Deploy
+```bash
+git add content/
+git commit -m "content: add [article title]"
+git push origin master
+```
+
+### Content Types at a Glance
+
+| Type | Badge | Use For |
+|------|-------|---------|
+| `tech` | Purple | Technical articles, tutorials, engineering |
+| `life` | Amber | Personal reflections, life lessons |
+| `quote` | Green | Meaningful quotes with context |
+| `link` | Cyan | Interesting links with commentary |
+| `photo` | Pink | Visual content and stories |
+
+---
+
+## Questions?
+
+Refer back to this guide whenever you:
+- Create new content
+- Edit existing articles
+- Reorganize the site
+- Add images or code examples
+- Publish or unpublish articles
+
+Happy writing! 🚀
