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