diff --git a/README.md b/README.md index 6d8ea81..656fb8c 100644 --- a/README.md +++ b/README.md @@ -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/`` markup or debugging search visibility. | | [`docs/ops-runbook.md`](docs/ops-runbook.md) | Before debugging CI/CD, deployment, or hosting. | diff --git a/docs/post-guideline.md b/docs/post-guideline.md new file mode 100644 index 0000000..906cd85 --- /dev/null +++ b/docs/post-guideline.md @@ -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/.md` | `/posts//` | +| Chinese | `src/content/posts/zh/.md` | `/posts/zh//` | + +- **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/"` 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//` → 200. diff --git a/docs/project-state.md b/docs/project-state.md index 00b45cb..8ac0ed9 100644 --- a/docs/project-state.md +++ b/docs/project-state.md @@ -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.)