ronnieops

Content Authoring Guide — RonnieOps

Quick Start

# Create a new draft post (uses archetypes/posts.md)
hugo new content posts/my-post-slug.md

# Preview with drafts
hugo server -D

# Build for production
bash build.sh

Front Matter Conventions

Stack theme uses YAML (---) front matter. The archetype (archetypes/posts.md) provides the full template:

Field	Required	Default	Notes
title	✅	auto	From filename if omitted
date	✅	now	ISO 8601 format
draft	✅	true	Set false to publish
description	—	""	Used in meta/Open Graph
image	—	placeholder	Path under static/ (e.g., /img/posts/slug-cover.png)
tags	—	[]	Free-form strings
categories	—	[]	Free-form strings
series	—	[]	Groups posts; theme renders series nav
keywords	—	[]	SEO meta keywords
math	—	false	Enable KaTeX math rendering
comments	—	false	Show/hide comments widget
license	—	false	Show license line

Reading Time

Controlled globally in hugo.toml:

[params.article]
readingTime = true

Table of Contents

Enabled globally in hugo.toml:

[params.article]
toc = true

Publishing Workflow

1. Write draft locally with draft: true
2. Preview: hugo server -D
3. When ready, set draft: false
4. Commit and push — CI lints, builds, and deploys automatically
5. Drafts are excluded from search indexing (Hugo doesn’t render them)

Series

Group related posts with the series front matter field:

series: ["building-ronnieops"]

Series navigation (prev/next links, part X/Y progress) renders automatically between the article body and related-content section on posts that belong to a series. Posts within a series are sorted by date ascending.

Guidelines

• Use series for multi-part tutorials (e.g., “Kubernetes RBAC Deep Dive Part 1/3”)
• Series names should be lowercase, hyphenated (building-ronnieops, not “Building RonnieOps”)
• A post can belong to multiple series
• Set the series field in the archetype template when starting a new series

Cover Images

Cover images live in static/img/posts/. Reference them in front matter:

image: "/img/posts/my-post-slug-cover.png"

Until a custom cover is ready, use the placeholder:

image: "/img/posts/placeholder-cover.svg"

Guidelines

• Recommended: 1200×630 px (Open Graph aspect ratio)
• Minimum: 600×315 px
• Keep under 200 KB where possible

Lint Rules

markdownlint-cli2 runs in CI. Configuration in .markdownlint-cli2.yaml. Disabled rules (blog-friendly):

• MD013 (line length)
• MD025 (multiple H1s)
• MD033 (inline HTML)
• MD034 (bare URLs)
• MD036 (emphasis instead of heading)
• MD041 (first line must be H1)
• MD026 (trailing punctuation in heading)