path: root/CONTENT_GUIDE.md

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

![Image alt text](image-file.jpg)

> 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
![A description of the image](image-filename.jpg)
```

For featured images in front matter, use just the filename:
```toml
image = "image-filename.jpg"
```

---

## Hugo Shortcodes

Beyond standard Markdown, the theme includes special shortcodes for enhanced content. Place your content files (images, etc.) in the same folder as the article.

### Responsive Image Shortcode

The `img` shortcode creates responsive, optimized images with lazy loading, WebP format support, and a fade-in LQIP (Low Quality Image Placeholder) effect.

**Usage:**
```hugo
{{< img src="image.jpg" alt="Image description" >}}
```

**Parameters:**
- `src` (required) — Path to image file (relative to content folder)
- `alt` (required) — Alt text for accessibility
- `divClass` (optional) — CSS class to add to the wrapper div

**Configuration:**
Add to your `hugo.toml` to define responsive image sizes:
```toml
[params]
imageSizes = [640, 900, 1200, 1600]
```

**Example:**
```hugo
{{< img src="kubernetes-architecture.jpg" alt="Kubernetes cluster architecture" >}}
```

---

### Quote Shortcode

The `quote` shortcode creates styled blockquotes with optional source attribution and links.

**Usage:**
```hugo
{{< quote source="Author Name" src="https://example.com" >}}
This is a meaningful quote.
{{< /quote >}}
```

**Parameters:**
- Content between tags — The quote text
- `source` (optional) — Author or source name
- `src` (optional) — URL to link the source to (opens in new tab)

**Examples:**

Simple quote:
```hugo
{{< quote >}}
The obstacle is the way.
{{< /quote >}}
```

Quote with attribution:
```hugo
{{< quote source="Marcus Aurelius" >}}
The impediment to action advances action. What stands in the way becomes the way.
{{< /quote >}}
```

Quote with link:
```hugo
{{< quote source="Paul Graham" src="http://paulgraham.com/wealth.html" >}}
The way to get rich is to work hard, at something people want.
{{< /quote >}}
```

---

### Gravatar Shortcode

The `gravatar` shortcode embeds a Gravatar profile image with optional caption and link.

**Usage:**
```hugo
{{< gravatar mail="your@email.com" size=150 caption="My avatar" >}}
```

**Parameters:**
- `mail` (optional) — Email address for Gravatar lookup (falls back to `author_email` from config)
- `size` (optional) — Image size in pixels (default: 200)
- `class` (optional) — CSS class for the figure element
- `link` (optional) — URL to wrap the image in a link
- `target` (optional) — Link target (_blank, _self, etc.)
- `rel` (optional) — Link rel attribute (e.g., "author")
- `caption` (optional) — Caption text (supports Markdown)
- `alt` (optional) — Alt text (uses caption as fallback)

**Configuration:**
Add to your `hugo.toml` to set your default email:
```toml
[params]
author_email = "your@email.com"
```

**Examples:**

Simple gravatar with default size:
```hugo
{{< gravatar >}}
```

Custom size and caption:
```hugo
{{< gravatar mail="danilo@example.com" size=120 caption="That's me" >}}
```

With link to profile:
```hugo
{{< gravatar mail="danilo@example.com" size=150 link="https://gravatar.com/danilo" target="_blank" rel="author" caption="Click to view my profile" >}}
```

---

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