- Refresh project-state.md with all completed work this session - Add docs/post-guideline.md (title case, locale structure, frontmatter, publish flow) - Reference it in README + hoelee-blog skill
This commit is contained in:
@@ -38,6 +38,7 @@ src/
|
||||
lang.ts # derives en/zh from folder path
|
||||
docs/
|
||||
content-guide.md # what to write, what to avoid (READ before writing a post)
|
||||
post-guideline.md # HOW to write it: title case, locale, frontmatter, publish flow
|
||||
design-guide.md # what the design must have, what to avoid (READ before touching UI)
|
||||
seo-reference.md # E-E-A-T / name identity, SEO + GEO checklist, syndication
|
||||
ops-runbook.md # pipeline, publish steps, build pitfalls, health checks
|
||||
@@ -49,6 +50,7 @@ docs/
|
||||
| Doc | When to read |
|
||||
|---|---|
|
||||
| [`docs/content-guide.md`](docs/content-guide.md) | Before writing/planning any blog post — categories, post types, the "hard job → post" template, and the anti-patterns. |
|
||||
| [`docs/post-guideline.md`](docs/post-guideline.md) | Before writing/editing a post — title case, locale folder structure, frontmatter, publish flow. |
|
||||
| [`docs/design-guide.md`](docs/design-guide.md) | Before changing theme, layout, typography, color, or SEO markup. |
|
||||
| [`docs/seo-reference.md`](docs/seo-reference.md) | Before adding posts/`<head>` markup or debugging search visibility. |
|
||||
| [`docs/ops-runbook.md`](docs/ops-runbook.md) | Before debugging CI/CD, deployment, or hosting. |
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
# Post-Writing Guideline
|
||||
|
||||
A single reference for writing a post on blog.hoelee.com. Read this **before** creating or editing any post. It consolidates the style, locale, and frontmatter rules — the "how to write it correctly the first time" checklist.
|
||||
|
||||
> Broader *what-to-write* strategy (categories, post types, cadence, anti-patterns) lives in `content-guide.md`. This file is the *how* — mechanics and style.
|
||||
|
||||
---
|
||||
|
||||
## 1. File location & language (enforced by code)
|
||||
|
||||
| Language | Path | URL |
|
||||
|---|---|---|
|
||||
| English | `src/content/posts/<slug>.md` | `/posts/<slug>/` |
|
||||
| Chinese | `src/content/posts/zh/<slug>.md` | `/posts/zh/<slug>/` |
|
||||
|
||||
- **Do NOT set a `lang:` field** in frontmatter — language is derived from the folder.
|
||||
- English is primary. Chinese is selective (2–3 flagship case studies). No Malay.
|
||||
- To make a Chinese translation of a post, give it the **same filename** in the `zh/` folder — the language switcher auto-links them. If filenames differ, add a `translation: "zh/<other-slug>"` field to link them manually.
|
||||
|
||||
---
|
||||
|
||||
## 2. Title style — Title Case
|
||||
|
||||
All English post titles use **Title Case** (capitalize the first letter of every significant word):
|
||||
|
||||
- ✅ `How I Host This Blog: Astro, Gitea Actions, and Self-Hosted CI/CD`
|
||||
- ✅ `Hello, World — About This Blog`
|
||||
- ❌ `How I host this blog: ...`
|
||||
|
||||
Exceptions stay lowercase (articles, prepositions, conjunctions — but our house style capitalizes them after punctuation like `—` or `:` for a clean look): "About", "This", "And", "and" are all acceptable; be **consistent**.
|
||||
|
||||
Chinese titles need no capitalization change.
|
||||
|
||||
---
|
||||
|
||||
## 3. Frontmatter shape
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "How I Built the DigiKedai Telegram AI Bot" # Title Case
|
||||
description: "A ~155-char meta description with the target keyword."
|
||||
pubDate: 2026-09-06
|
||||
updatedDate: 2026-09-10 # optional, when revised
|
||||
category: case-studies # one of the 7 below
|
||||
tags: ["telegram", "n8n", "docker", "cloudflare"]
|
||||
translation: "zh/how-i-built-digikedai-bot" # optional, only if slug differs from zh counterpart
|
||||
ogImage: "/og/digikedai-bot.png" # optional, 1200×630 custom image
|
||||
draft: false # true = hidden from build
|
||||
---
|
||||
```
|
||||
|
||||
### Categories (the only 7 allowed)
|
||||
`engineering` · `devops` · `ai` · `web3` · `tutorials` · `case-studies` · `notes`
|
||||
|
||||
---
|
||||
|
||||
## 4. The "hard job → post" template
|
||||
|
||||
When you finish a difficult piece of work, use this shape — it's simultaneously a tutorial, a case study, and a proof-of-expertise:
|
||||
|
||||
```
|
||||
① The problem → phrased as the searchable question a learner would type
|
||||
② What I tried & why it failed → the debugging story (no one else can copy this)
|
||||
③ The fix → runnable code/config, explained
|
||||
④ What I'd do differently → shows judgment
|
||||
⑤ The result → one quantified outcome
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Language & identity rules
|
||||
|
||||
- **Business framing:** website design & development is the primary business; email hosting is a **side offering** — never describe it as "an email-hosting business".
|
||||
- **Name:** "Lee Teong Hoe" / "Mr Hoelee" — identical across blog, LinkedIn, GitHub, git.hoelee.com.
|
||||
- **No overclaiming**, especially Web3 (learning projects, not production DeFi).
|
||||
|
||||
---
|
||||
|
||||
## 6. Code blocks
|
||||
|
||||
- Wrap code in fenced blocks with the language tag (```yaml, ```bash, ```ts).
|
||||
- Keep code/commands in their **original language** (don't translate code or commands inside a Chinese post).
|
||||
- The copy button is added automatically by the layout — no action needed.
|
||||
|
||||
---
|
||||
|
||||
## 7. Publish flow
|
||||
|
||||
1. Write the `.md` file in the correct folder (see §1).
|
||||
2. `npm run build` locally to confirm it compiles (optional but recommended).
|
||||
3. Commit + push to both remotes:
|
||||
```bash
|
||||
git push origin main && git push github main
|
||||
```
|
||||
4. Gitea Actions CI builds and deploys automatically; verify with `curl -I https://blog.hoelee.com/posts/<slug>/` → 200.
|
||||
+13
-7
@@ -15,19 +15,23 @@ Living list of what's done and what's next for blog.hoelee.com. Work through the
|
||||
- ✅ Full SEO: canonical, Open Graph (+dims), twitter:card, favicon (all sizes), RSS + sitemap
|
||||
- ✅ Category pages (`/categories/`, `/categories/[category]/`)
|
||||
- ✅ Locale scheme: English flat in `posts/`, Chinese in `posts/zh/` (lang derived from folder, no `lang:` frontmatter)
|
||||
- ✅ Language switcher in nav (EN ↔ 中文) + `/zh/` landing page
|
||||
- ✅ Language switcher in nav — links to the **same post** in the other language (auto-matches by `zh/` prefix; falls back to section landing when no translation)
|
||||
- ✅ Locale-aware nav labels (EN: Posts/Categories/About/RSS; ZH: 文章/分类/关于/RSS)
|
||||
- ✅ Dark mode default (light is opt-in via toggle)
|
||||
- ✅ Case study post "how-i-host-this-blog" updated with docker-compose sample + real installation gotchas (from commit history)
|
||||
- ✅ Knowledge guides in `docs/` (content, design, seo, ops) + README index + `hoelee-blog` skill
|
||||
- ⬜ **Make the Gitea repo public** — verified no secrets in source or history (PAT is a `${{ secrets.PAT }}` reference, not hardcoded). Recommended: yes, public — it's a portfolio artifact. Action: flip visibility in Gitea repo settings.
|
||||
- ✅ Case study post "How I Host This Blog" — docker-compose sample + real install gotchas (from commit history)
|
||||
- ✅ Chinese translation of the case study (`posts/zh/how-i-host-this-blog.md`)
|
||||
- ✅ hello-world intro post — "What I write about" skills map + corrected business framing
|
||||
- ✅ Business framing corrected everywhere: website design & development = primary; email hosting = secondary (not the focus)
|
||||
- ✅ Knowledge guides in `docs/` (content, design, seo, ops, post-guideline) + README index + `hoelee-blog` skill
|
||||
- ✅ Both repos public (Gitea + GitHub) with title/description/homepage/topics + `v1.0.0` release
|
||||
|
||||
---
|
||||
|
||||
## Tier 1 — Content (80% of value; do this first)
|
||||
|
||||
- ⬜ **Write the 2 flagship case studies** — highest ROI, these are the portfolio:
|
||||
- ⬜ "How I built the DigiKedai Telegram AI bot" (DSM Docker + Cloudflare tunnel webhook + LiteLLM)
|
||||
- ⬜ "Self-hosting a mem0 memory stack" (API + LiteLLM + pgvector)
|
||||
- ⬜ "How I Built the DigiKedai Telegram AI Bot" (DSM Docker + Cloudflare tunnel webhook + LiteLLM)
|
||||
- ⬜ "Self-Hosting a Mem0 Memory Stack" (API + LiteLLM + pgvector)
|
||||
- ⬜ **2–3 gotcha posts** from real debugging history (short, Google-friendly):
|
||||
- ⬜ "The Traefik forward-auth gotcha that cost me a day"
|
||||
- ⬜ "Site-to-site OpenVPN behind CGNAT"
|
||||
@@ -41,12 +45,12 @@ Living list of what's done and what's next for blog.hoelee.com. Work through the
|
||||
- ⬜ **Tag pages** — tags currently render as labels only; add `/tags/[tag]/` archive pages for fine-grained discovery + internal linking
|
||||
- ⬜ **Categories page shows all 7 categories** (not just those with posts) — signal intended coverage; show "0 posts / coming soon" for empty ones
|
||||
- ⬜ **Search** — AstroPaper-style fuzzy search (low priority until >20 posts)
|
||||
- ⬜ **Dedicated `/zh/posts/` and `/zh/categories/` archive pages** — currently zh nav links point to `/zh/` landing; split into real archives when Chinese content grows
|
||||
|
||||
---
|
||||
|
||||
## Tier 3 — Polish / later
|
||||
|
||||
- ⬜ **Verify Chinese content split** — confirm `zh/` posts don't appear in EN feed (the `isEn` helper already filters; re-check when first zh post lands)
|
||||
- ⬜ **Google Search Console submission** — submit `sitemap-index.xml` for faster indexing
|
||||
- ⬜ **Newsletter / email capture** — only after real traffic exists
|
||||
|
||||
@@ -58,3 +62,5 @@ Living list of what's done and what's next for blog.hoelee.com. Work through the
|
||||
- English-first; Chinese selective (2–3 flagship case studies); no Malay
|
||||
- No overclaiming, especially Web3
|
||||
- Name identity: "Lee Teong Hoe" / "Mr Hoelee" + same photo + same `sameAs` handles everywhere
|
||||
- Business framing: website design & development is primary; email hosting is secondary
|
||||
- See `docs/post-guideline.md` for post-writing rules (title case, locale structure, frontmatter, etc.)
|
||||
|
||||
Reference in New Issue
Block a user