diff --git a/preferences/articles.md b/preferences/articles.md new file mode 100644 index 0000000..0e7c5c8 --- /dev/null +++ b/preferences/articles.md @@ -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 +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) \ No newline at end of file