Back to Details

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") }}
      or 
      {% cg() %}block text{% end %}
    • Red (negative): 
      {{ cr(body="negative text") }}
      or 
      {% 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:
  1. Title: Rewrite for SEO. Include the primary keyword near the front. Keep it concise but descriptive. Traditional Chinese.
  2. 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.
完成内容后，重新评估：
  1. 标题：为SEO重写标题。将核心关键词放在靠前位置。保持简洁且具有描述性。使用繁体中文。
  2. 描述：重写以包含文章中的所有重要关键词。此文本将出现在搜索结果中 — 使其具有吸引力且信息丰富。理想长度为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
on 
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 = 指南.