224 lines
6.6 KiB
Markdown
224 lines
6.6 KiB
Markdown
# 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
|
||
|
||
```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
|
||
<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
|
||
```markdown
|
||
## Section Title
|
||
```
|
||
Use `##` for primary sections. Avoid deep nesting.
|
||
|
||
### Code Blocks
|
||
Always specify the language:
|
||
````markdown
|
||
```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:
|
||
```html
|
||
<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:
|
||
```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.
|
||
|
||
---
|
||
|
||
## 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 |