added articles to preferences
This commit is contained in:
205
preferences/articles.md
Normal file
205
preferences/articles.md
Normal file
@@ -0,0 +1,205 @@
|
|||||||
|
# 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
|
||||||
|
<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
|
||||||
|
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 `<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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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)
|
||||||
Reference in New Issue
Block a user