Mi&Bee Blog

518 字 2 分钟阅读

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

content/posts/
├── telemetry/       # ~26 posts — Observability, Prometheus, VictoriaMetrics
├── iot/             # ~22 posts — ESP, Raspberry Pi, hardware
├── architecture/    # ~16 posts — System architecture design
├── aihelper/        # ~14 posts — AI tools, LLMs, dev assistants
├── mibee-oss/       # ~10 posts — NVR, open-source projects
├── system/          # ~4 posts  — System configuration
├── _index.md        # Section index (zh)
├── _index.en.md     # Section index (en)
└── code-test.md     # Test post (gitignored)

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

Where to Look

TaskLocationNotes
Add new postcontent/posts/<category>/<slug>.mdPick matching category dir
Add new categoryCreate new subdir under posts/Lowercase name
Add post imagescontent/posts/<category>/images/Reference as /posts/<category>/images/file.png
Archive old postMove to content/archives/Bilingual pairs .md + .en.md
Validate Mermaidpython scripts/check-mermaid.py content/posts/Run before commit

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

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

---
title: "文章标题"
date: 2024-01-15
weight: 1
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 1, 2, 3, … to allow inserting in the middle later.

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

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 (---)