# chns.tech Blog Post Writing Guide ## File Location & Naming - **Directory**: `/home/dockersa/chns.tech/content/posts/YYYY/` - **Filename format**: `MM-DD-{slug}.md` (e.g., `03-11-docker-setup-guide.md`) - **Slug**: lowercase, hyphen-separated, descriptive --- ## Front Matter Template ```yaml --- 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) ```markdown ## 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: ```html Description of image ``` ### 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 ```markdown ## Section Title ``` Use `##` for primary sections. Avoid deep nesting. ### Code Blocks Use plain fenced code blocks — do not specify a language: ````markdown ``` command here ``` ```` ### 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 `

`. ### Images Use HTML `` tags — NOT standard markdown image syntax: ```html Description of image ``` Image path pattern: `https://public.chns.tech/images/chns/YYYY/MM-DD-{slug}/N.png` ### Lists Unordered: ```markdown - Item one - Item two ``` Ordered (for sequential steps): ```markdown 1. Step one 2. Step two ``` ### Links ```markdown [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. --- ## 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 YAML in a code block, then explanation 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 - Use Hugo shortcodes (none are currently used)