create-blog-post

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Blog Post on 聆.tw

在聆.tw创建博文

This skill guides the full workflow of creating a new tech blog post on 聆.tw (琳聽智者漫談), from repo setup to PR submission.

本技能指导在**聆.tw（琳聽智者漫談）**上创建新技术博文的完整工作流，从仓库设置到PR提交。

Prerequisites

前置要求

```
git
```
CLI available
```
gh
```
CLI authenticated with GitHub
Write access to
```
jim60105/ai-talks-content
```

可使用
```
git
```
CLI
```
gh
```
CLI已通过GitHub认证
拥有
```
jim60105/ai-talks-content
```
的写入权限

Workflow

工作流

Step 1: Clone the Repository

步骤1：克隆仓库

If the blog repo is not yet cloned:

bash

git clone --recurse-submodules https://github.com/jim60105/blog.git
cd blog

If already cloned but submodules are missing:

bash

git submodule update --init --recursive

If already cloned and submodules exist, just ensure they're up to date:

bash

git pull origin master

如果尚未克隆博客仓库：

bash

git clone --recurse-submodules https://github.com/jim60105/blog.git
cd blog

如果已克隆但缺少子模块：

bash

git submodule update --init --recursive

如果已克隆且子模块存在，只需确保其为最新版本：

bash

git pull origin master

Step 2: Prepare the Submodule

步骤2：准备子模块

Enter the content submodule and ensure it's on the latest

master

bash

cd 聆.tw/content
git checkout master
git pull origin master
cd ../..

进入内容子模块并确保其处于最新的

master

分支：

bash

cd 聆.tw/content
git checkout master
git pull origin master
cd ../..

Step 3: Switch to 聆.tw Mode

步骤3：切换至聆.tw模式

From the project root (

blog/

bash

./switch-site.sh 聆.tw

This creates symlinks for

config.toml

content/

static/

, and

wrangler.jsonc

pointing to

聆.tw/

从项目根目录（

blog/

）执行：

bash

./switch-site.sh 聆.tw

此操作会为

config.toml

、

content/

、

static/

和

wrangler.jsonc

创建指向

聆.tw/

的符号链接。

Step 4: Choose Section and Prepare File

步骤4：选择栏目并准备文件

List available content sections:

bash

ls -d 聆.tw/content/*/

Choose the section most related to the topic. If none fits well, use

Uncategorized

列出可用的内容栏目：

bash

ls -d 聆.tw/content/*/

选择与主题最相关的栏目。如果没有合适的栏目，请使用

Uncategorized

。

Step 5: Create the Post File

步骤5：创建博文文件

Create a markdown file with a slugified filename (lowercase, hyphens, English, descriptive):

bash

touch 聆.tw/content/<Section>/my-descriptive-slug.md

Naming convention: use lowercase English words separated by hyphens. The slug should describe the post content concisely.

创建一个文件名经过slug化的Markdown文件（小写、连字符分隔、英文、描述性）：

bash

touch 聆.tw/content/<Section>/my-descriptive-slug.md

命名规范：使用小写英文单词，以连字符分隔。Slug应简洁描述博文内容。

Step 6: Write Front Matter

步骤6：编写前置元数据（Front Matter）

Read

AGENTS.md

at the project root for the latest front matter specification. The required format:

toml

+++
title = "文章標題（正體中文）"
description = "SEO 友善的文章描述，包含所有重要關鍵字（正體中文）"
date = "YYYY-MM-DDTHH:MM:SSZ"
updated = "YYYY-MM-DDTHH:MM:SSZ"
draft = false

[taxonomies]
tags = ["Tag1", "Tag2"]
providers = [ "Felo Search" ]

[extra]
withAI = "<https://the.ai.resource/used>"
+++

Rules:

```
title
```
: Concise, SEO-friendly, Traditional Chinese
```
description
```
: Contains all keywords, compelling for search results
```
date
```
: ISO 8601 UTC format, use current timestamp
```
updated
```
: ISO 8601 UTC format, use current timestamp
```
tags
```
: Relevant tags in the format used by existing posts
```
providers
```
: The provider(s) of AI assistance used in writing the article, if any
```
withAI
```
: Brief note about AI assistance or any urls to AI resources used. This is optional but recommended for transparency.
NEVER fabricate an
```
iscn
```
field — only the user can generate this

阅读项目根目录下的

AGENTS.md

获取最新的前置元数据规范。必填格式如下：

toml

+++
title = "文章標題（正體中文）"
description = "SEO 友善的文章描述，包含所有重要關鍵字（正體中文）"
date = "YYYY-MM-DDTHH:MM:SSZ"
updated = "YYYY-MM-DDTHH:MM:SSZ"
draft = false

[taxonomies]
tags = ["Tag1", "Tag2"]
providers = [ "Felo Search" ]

[extra]
withAI = "<https://the.ai.resource/used>"
+++

规则：

```
title
```
：简洁、SEO友好的繁体中文标题
```
description
```
：包含所有关键词，对搜索结果有吸引力
```
date
```
：ISO 8601 UTC格式，使用当前时间戳
```
updated
```
：ISO 8601 UTC格式，使用当前时间戳
```
tags
```
：采用现有博文使用的格式添加相关标签
```
providers
```
：撰写文章时使用的AI辅助提供商（如有）
```
withAI
```
：关于AI辅助的简要说明或使用的AI资源链接。此为可选字段，但建议添加以保证透明度。
切勿伪造
```
iscn
```
字段 — 仅用户可生成此字段

Step 7: Write the Blog Post Content

步骤7：撰写博文内容

Read

.github/instructions/quill-sage.instructions.md

at the project root for full editorial guidelines. For quick reference, see references/writing-guidelines.md.

Key rules:

Write in Traditional Chinese (zh-TW) with full-width punctuation
Add a space between Chinese characters and alphanumeric characters
Use inverted pyramid structure: core conclusion first, evidence second
Avoid bullet lists unless explicitly requested; prefer natural paragraphs
Use
```
##
```
and
```
###
```
subheadings to organize
Address reader as 「讀者」「大家」「各位」 or 「你」, never 「您」
Refer to the author as 「我」, never 「我們」
Opening paragraph states core conclusion and scope
Closing paragraph must not use slogan-style endings

阅读项目根目录下的

.github/instructions/quill-sage.instructions.md

获取完整编辑指南。快速参考可查看 references/writing-guidelines.md。

核心规则：

使用**繁体中文（zh-TW）**并搭配全角标点
中文字符与字母数字字符之间添加空格
使用倒金字塔结构：先给出核心结论，再提供证据
除非明确要求，否则避免使用项目符号列表；优先使用自然段落
使用
```
##
```
和
```
###
```
子标题进行内容组织
称呼读者为「讀者」「大家」「各位」或「你」，切勿使用「您」
指代作者为「我」，切勿使用「我們」
开篇段落需说明核心结论和内容范围
结尾段落不得使用口号式结尾

Step 8: Add Formatting and Color Shortcodes

步骤8：添加格式和颜色短代码

Review the article and enhance with:

Bold (
```
**text**
```
) for emphasis keywords
Italic (
```
*text*
```
) where appropriate

Color shortcodes for pros/cons:

Green (positive):

{{ cg(body="positive text") }}

{% cg() %}block text{% end %}

Red (negative):

{{ cr(body="negative text") }}

{% cr() %}block text{% end %}

审阅文章并通过以下方式增强内容：

粗体（
```
**text**
```
）用于强调关键词
斜体（
```
*text*
```
）用于合适的场景

用于优缺点的颜色短代码：

绿色（正面）：

{{ cg(body="positive text") }}

或

{% cg() %}block text{% end %}

红色（负面）：

{{ cr(body="negative text") }}

或

{% cr() %}block text{% end %}

Step 9: Add Chat Shortcodes

步骤9：添加对话短代码

Use chat shortcodes to create conversational content that makes the article vivid:

markdown

{% chat(speaker="yuna") %}
Question or statement from Yuna
{% end %}

{% chat(speaker="jim") %}
Response from Jim (author, displayed as 琳, aligned right)
{% end %}

Available speakers:

chatgpt

claude

gemini

copilot

felo

jim

(author, right-aligned),

yoruka

, or any custom name. Default/

user

gets a generic user avatar.

Design conversations that naturally introduce the topic, ask clarifying questions, or surface interesting angles. The chat format should add value, not just decorate.

使用对话短代码创建生动的对话式内容：

markdown

{% chat(speaker="yuna") %}
Question or statement from Yuna
{% end %}

{% chat(speaker="jim") %}
Response from Jim (author, displayed as 琳, aligned right)
{% end %}

可用发言人：

chatgpt

、

claude

、

gemini

、

copilot

、

felo

、

jim

（作者，右对齐）、

yoruka

，或任何自定义名称。默认/

user

将使用通用用户头像。

设计的对话应自然引入主题、提出澄清问题或呈现有趣的视角。对话格式应增加内容价值，而非仅作为装饰。

Step 10: SEO Review — Rewrite Title and Description

步骤10：SEO审阅 — 重写标题和描述

After completing the content, re-evaluate:

Title: Rewrite for SEO. Include the primary keyword near the front. Keep it concise but descriptive. Traditional Chinese.
Description: Rewrite to include all important keywords from the article. This text appears in search results — make it compelling and informative. ~150-160 characters ideal.

完成内容后，重新评估：

标题：为SEO重写标题。将核心关键词放在靠前位置。保持简洁且具有描述性。使用繁体中文。
描述：重写以包含文章中的所有重要关键词。此文本将出现在搜索结果中 — 使其具有吸引力且信息丰富。理想长度为150-160字符。

Step 11: Rename File if Title Changed

步骤11：若标题变更则重命名文件

If the title was significantly revised, rename the file to match:

bash

mv 聆.tw/content/<Section>/old-slug.md 聆.tw/content/<Section>/new-better-slug.md

The slug should reflect the final title content in English.

若标题进行了大幅修改，重命名文件以匹配：

bash

mv 聆.tw/content/<Section>/old-slug.md 聆.tw/content/<Section>/new-better-slug.md

Slug应使用英文反映最终标题的内容。

Step 12: Create Branch, Commit, and PR

步骤12：创建分支、提交并创建PR

All git operations happen inside the submodule (

聆.tw/content/

bash

cd 聆.tw/content
git checkout -b post/<slug-name>
git add <Section>/new-post-file.md
git commit --signoff --author="GitHub Copilot <bot@ChenJ.im>" -m "feat: add post <descriptive-title>

Add new blog post about <topic summary>.

Co-authored-by: GitHub Copilot <bot@ChenJ.im>"
git push origin post/<slug-name>

Then create the PR targeting

master

jim60105/ai-talks-content

bash

gh pr create \
  --repo jim60105/ai-talks-content \
  --base master \
  --head post/<slug-name> \
  --title "feat: add post <descriptive-title>" \
  --body "Add new blog post: <title>

<brief description of content>

---
Written with AI assistance."

所有git操作均在子模块内部（

聆.tw/content/

）执行：

bash

cd 聆.tw/content
git checkout -b post/<slug-name>
git add <Section>/new-post-file.md
git commit --signoff --author="GitHub Copilot <bot@ChenJ.im>" -m "feat: add post <descriptive-title>

Add new blog post about <topic summary>.

Co-authored-by: GitHub Copilot <bot@ChenJ.im>"
git push origin post/<slug-name>

然后创建针对

jim60105/ai-talks-content

仓库

master

分支的PR：

bash

gh pr create \
  --repo jim60105/ai-talks-content \
  --base master \
  --head post/<slug-name> \
  --title "feat: add post <descriptive-title>" \
  --body "Add new blog post: <title>

<brief description of content>

---
Written with AI assistance."

Step 13: Request Review

步骤13：请求审阅

bash

gh pr edit --repo jim60105/ai-talks-content <PR_NUMBER> --add-reviewer jim60105

bash

gh pr edit --repo jim60105/ai-talks-content <PR_NUMBER> --add-reviewer jim60105

Terminology Mappings

术语映射

When writing content, apply these Traditional Chinese mappings: create = 建立, object = 物件, queue = 佇列, stack = 堆疊, information = 資訊, code = 程式碼, running = 執行, library = 函式庫, building = 建構, package = 套件, video = 影片, class = 類別, function = 函式, memory = 記憶體, document = 文件, example = 範例, tutorial = 指南.

撰写内容时，请使用以下繁体中文映射：create = 建立, object = 物件, queue = 佇列, stack = 堆疊, information = 資訊, code = 程式碼, running = 執行, library = 函式庫, building = 建構, package = 套件, video = 影片, class = 類別, function = 函式, memory = 記憶體, document = 文件, example = 範例, tutorial = 指南.