AI/preferences/articles.md

chns.tech Blog Post Writing Guide

File Location & Naming

• New posts (staging): CHNS.tech/staged-posts/ — write all new posts here first
• Published location: /home/dockersa/chns.tech/content/posts/YYYY/ — only after review
• Filename format: MM-DD-{slug}.md (e.g., 03-11-docker-setup-guide.md)
• Slug: lowercase, hyphen-separated, descriptive

---

Front Matter Template

---
title: "Post Title Here"
date: 2026-03-11T14:00:00-00:00
featured_image: "https://public.chns.tech/images/logo/[image].png"
draft: true
lastmod: 2026-03-11T14:00:00-00:00
tags: []
categories: [Category Name]
summary: "A brief 1–3 sentence description of what this post covers."
---

Field notes:

• date: ISO 8601 with timezone offset (e.g., -00:00)
• featured_image: CDN URL on public.chns.tech — use relevant image or logo; optional
• draft: always leave as true; manually change to false to publish
• lastmod: set to the same value as date
• tags: typically left as empty array []
• categories: single-item array, see categories list below

---

Categories

Category	Use For
Docker Apps	Docker-based self-hosted app guides
Docker	General Docker concepts, not app-specific
Ubuntu Server	Ubuntu-specific server tutorials
Proxmox	Proxmox VE guides
Windows Server	Windows Server tutorials
Unifi	Unifi networking gear guides
TrueNAS	TrueNAS storage guides
VMware	VMware/ESXi topics
Networking	General networking concepts
Linux	General Linux topics
Windows	General Windows tips
Computer Novice	Non-technical/general audience posts
Web Development	Web dev and site building topics
Reviews	Product/service reviews

---

Post Structure

1. Introduction (2–3 paragraphs)

• Open with personal context or motivation for the topic
• Explain what the post will cover
• Note any caveats, disclaimers, or "why this matters" framing
• First-person voice — share the personal experience that led to writing this

2. Prerequisites Section (if tutorial)

## Prerequisites

- [Related Post Title](https://chns.tech/posts/...) — brief note on what it covers
- [Related Post Title](https://chns.tech/posts/...) — brief note on what it covers
- Item describing required software, knowledge, or setup
- Item

Search all existing posts in /home/dockersa/chns.tech/content/posts/ and link every related published post (i.e., draft: false), not just one. Each linked post should include a brief note on what it covers.

3. Main Content (H2 sections)

• Use ## for section headers, not ### for primary sections
• Sequential steps for tutorials — explain before showing code
• Follow each code block with a brief explanation of what it does
• Include screenshots for GUI-based workflows — insert placeholder image code anywhere a screenshot would make sense:

<img src="https://public.chns.tech/images/chns/YYYY/MM-DD-{slug}/N.png" alt="Description of image" style="max-width: 100%; height: auto;">

4. Conclusion (1–2 paragraphs)

• Personal reflection on the tool or topic
• Thoughts on its usefulness or when to use it
• Soft call to action: mention related posts or socials

5. References (optional)

• Bare list of links to official docs, GitHub, Docker Hub
• Format: [Link Text](URL)

---

Tone & Voice

• Conversational and friendly — write like explaining to a knowledgeable friend
• First-person throughout — "I", "my homelab", "I found that..."
• Practical and honest — share what worked, what didn't, personal opinions
• Audience: home lab enthusiasts, IT professionals, sysadmins
• Length: ~800–1,000 words; can exceed 1,000 if the content warrants it

---

Formatting Conventions

Headers

## Section Title

Use ## for primary sections. Avoid deep nesting.

Code Blocks

Always specify the language:

```bash
command here
```

```yaml
key: value
```

Inline Code

Use backticks for commands, file paths, config keys, and field names: docker-compose up -d

Bold

Use **text** to emphasize key terms, option names, or important notes.

Section Separators

Use --- between sections for visual separation — do not use <br></br>.

Images

Use HTML <img> tags — NOT standard markdown image syntax:

<img src="https://public.chns.tech/images/chns/YYYY/MM-DD-slug/1.png" alt="Description of image" style="max-width: 100%; height: auto;">

Image path pattern: https://public.chns.tech/images/chns/YYYY/MM-DD-{slug}/N.png

Lists

Unordered:

- Item one
- Item two

Ordered (for sequential steps):

1. Step one
2. Step two

Links

[Link Text](https://url.com)

Internal links to other chns.tech posts are common in prerequisites and conclusions.

Horizontal Rules

Use --- to separate major logical sections when needed.

---

Shortcodes

remote-code — Embed code from Gitea

Use instead of pasting a static code block when the file lives in Gitea.

{{</* remote-code url="https://git.chns.tech/CHNS/Docker-Compose/raw/branch/main/AppName/docker-compose.yaml" lang="yaml" */>}}

• URL must use the raw/branch/main/... path on git.chns.tech
• Use lang="yaml" for Docker Compose files
• Always follow with an explanation of what the file does and what values to change

---

Docker App Post Template

Most common post type. Structure:

1. Introduction — what the app does, why the author uses/likes it
2. Prerequisites — linked list of required background posts
3. Deployment — Docker Compose via remote-code shortcode (linking to Gitea), then explanation of what to change
4. Configuration — step-by-step GUI or config walkthrough with screenshots
5. Feature sections — one ## section per major feature (e.g., "## Create Recipe", "## Import Recipes")
6. Conclusion — personal thoughts, link to official docs/GitHub
7. References — official site, GitHub, Docker Hub

Docker Compose block example:

services:
  appname:
    image: imagename:latest
    container_name: appname
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/data
    environment:
      - TZ=America/Los_Angeles

---

Content DO's and DON'Ts

DO:

• Share personal motivation and experience
• Link to other chns.tech posts for prerequisites
• Explain why before showing how
• Include real config examples that work
• Add screenshots for every major UI step

DON'T:

• Use overly formal or corporate language
• Skip explaining what a code block does
• Write in passive voice
• Leave readers without context on why something matters