AGENTS.md — Blog Posts (content/posts/)

Overview

Blog post content organized by topic category. ~94 posts total. All new posts MUST be bilingual (zh + en).

Structure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

content/posts/
├── telemetry/       # ~26 posts — 可观测性, Prometheus, VictoriaMetrics
├── iot/             # ~16 posts — 物联网, ESP, 树莓派
├── architecture/    # ~16 posts — 系统架构设计
├── aihelper/        # ~7 posts — AI 工具, 大模型, 辅助开发
├── mibee-oss/       # ~20 posts — MiBee 开源项目
├── network/         # 网络技术
├── physical-world/  # 信号处理与图像
├── programming/     # 编程语言
├── frontend/        # 前端技术
├── _index.md        # Section index (zh)
└── _index.en.md     # Section index (en)

Each category may have an images/ subdirectory for post assets.

Where to Look

Front Matter (YAML only)

All posts use YAML (---). Never use TOML (+++) despite the archetype.

Required: title, date

Common optional: categories, tags, comments, description, keywords, lastmod, toc, math, mermaid, draft, series, weight, chapter

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

---
title: "文章标题"
date: 2024-01-15
weight: 10        # series ordering, step-10 (10, 20, 30...)
chapter: P2P 核心协议   # optional — groups posts into collapsible chapters on the series page
categories:
  - 分类
tags:
  - 标签1
  - 标签2
series:
  - 系列名称
comments: true
description: "文章描述"
---

MANDATORY: Bilingual Posts

Every new blog post MUST be created as a pair:

• content/posts/<category>/<slug>.md — Chinese version
• content/posts/<category>/<slug>.en.md — English version

Both files must have identical front matter fields (with translated values). Each category needs _index.md (zh) + _index.en.md (en) for section page titles.

MANDATORY: Series Weight

Posts in a series MUST use weight to control ordering (not date). The series detail template sorts by .Pages.ByWeight. Lower weight = earlier in series.

Use step-10 weights: 10, 20, 30, ... (not 1, 2, 3). Step-10 leaves gaps (e.g. insert a new post at weight 15 between 10 and 20) without renumbering the whole series. Collision (two posts with the same weight) makes the series stepper and prev/next nav nondeterministic — python scripts/check-series.py content/posts/ catches this before commit.

Optional: Series Chapters (chapter field)

For large series (≈ 8+ posts), group posts into chapters on the series detail page by adding an optional chapter field. Same-chapter posts collapse into one accordion panel.

• Chapter order = weight order of each chapter’s earliest post. No second ordering key — weight does double duty. To place a chapter earlier, give its posts a smaller weight than the next chapter’s posts.
• Bilingual: Chinese posts use a Chinese chapter name, English posts use the translated name (mirrors the bilingual series naming rule).
• Degradation: a series with zero chapter-tagged posts renders as the original flat timeline. Untagged posts in a partially-tagged series fall into a trailing “未分组” / “Other” panel.
• No migration: just start tagging. Existing series keep working.

See the network series (网络开发实战 / Network Development Practice) for a working 5-chapter example.

Content Rules

• Language: Chinese with inline English for technical terms
• Headings: Start at ## (h2) — h1 is the title
• No manual numbering: TOC auto-numbers, avoid “一、二、” or “1. 2. 3.”
• Images: Store in category’s images/ dir, reference with absolute path
• Code blocks: Triple backticks with language identifier
• Mermaid: Fenced ```mermaid blocks, set mermaid: true in front matter if needed

Graphics: single source of truth (diagram shortcode)

Complex/reused graphics — especially animated SVG and rich diagrams that appear in BOTH the .md and .en.md — MUST be extracted into a partial and referenced via the diagram shortcode, not inlined in both posts.

Inlining a 68-line SVG in both the zh and en post means every fix must be applied twice with no shared source. The diagram shortcode solves this:

1. Create themes/hugo-themes-zhi/layouts/_partials/diagrams/<series>/<slug>.html holding the graphic. If text labels differ by language, branch on .lang inside the partial (see diagrams/obs-tech-03/chunk-lifecycle.html for the pattern). Structure/animation that is language-neutral lives once.

2. In BOTH .md and .en.md, reference it with one line: &#123;&#123;< diagram src="<series>/<slug>" >&#125;&#125;}

   (Shown with HTML entities above so Hugo does not execute this example; write the literal &#123;&#123;< diagram src="..." >&#125;&#125; in real posts.)

The shortcode passes the current page language to the partial automatically. A fix applied to the partial renders correctly in both languages.

When to use the shortcode vs. inline:

• Inline ```mermaid fence: one-off diagrams unique to a single post.
• diagram shortcode: any graphic duplicated across the zh/en pair, or any non-Mermaid graphic (animated SVG, hand-built diagram) — always.
• Static image: screenshots/exports — images/ dir + markdown image syntax.

Graphics technology selection (quick reference)

Anti-Patterns

• NEVER put posts in content/posts/ root — always use category subdirectory
• NEVER create a single-language post — every post needs both .md and .en.md
• NEVER use manual heading numbering
• NEVER put config:/themeVariables: inside Mermaid code blocks
• NEVER use classDef/style in sequenceDiagram — causes Parse error
• NEVER use @{ shape } outside flowchart/graph
• NEVER use TOML front matter (+++) — always YAML (---)
• NEVER inline the same graphic in both .md and .en.md — extract to a diagram partial (single source of truth)
• NEVER reuse a weight value within a series — causes nondeterministic order

Anti-Patterns: 去 AI 味（AI-tone）

写/改博文时遵守主 AGENTS.md 的「去套路 / 反 AI 味」规范（位于 Content Conventions → Writing Style 之后）。要点：

• NEVER 用 AI 模板框架：> **新手类比**： / **动画说明**： / **新手速查 — X** callout 框、“读完后你将理解：” + bullet 学习目标清单、"## 系列总结与展望" / “感谢阅读，欢迎持续关注” 展望套路、虚构的"作者简介"模块、同段连写两遍的重复段落。
• NEVER 用套路开头：“本文将深入剖析/详细介绍…包括 A、B、Z，帮助你…"、“想象一下/想象一个场景…"、“答案很简单：X"。直入主题，用准确动词（覆盖/梳理/对比），不用华丽词（深入剖析/融会贯通/全方位）。
• NEVER 用空洞赞美词密集堆砌：强大的/完美的/优雅的/公认…领导者/不二之选/无疑是/终极选择/极致性能/革命性（突破）/新纪元/范式跃迁/前所未有的。换成具体事实或删除。（边界词 事实标准/首选 在技术陈述里准确，可保留。）
• NEVER 用升华/鸡汤结尾：“不再是幻想”/“让…成为现实”/“没有万能银弹”/“这是一门艺术”/“保持学习的热情”/“记住，好的运维不仅仅是…"。
• NEVER 用对仗排比堆砌：4 字排比结尾、“从 X 进化到 Y / 不仅仅是…而是… / 不仅…更…"、“无论…无论…“双重排比。
• NEVER 把个人语气改成正式体：真实口语（“但说实话"“折腾"“血泪教训"“免得误期待”）是目标语感，保留。2023 年前手写老文的口语风格（“总结来说”）是个人风格，不是 AI 味，不要改成正式体。
• ALWAYS 中英同步：中文 .md 改了，英文 .en.md 对应改。

写完对照主 AGENTS.md 的"自检清单"过一遍。