create-blog-post

Create Blog Post on 聆.tw

This skill guides the full workflow of creating a new tech blog post on

聆.tw

(琳聽智者漫談), from repo setup to PR submission.

[!IMPORTANT]

We use git submodules in this blog repository, and the content is stored within these submodules. Therefore, all git operations for creating a new blog post must be performed inside the submodule directory (

聆.tw/content/

).

ALWAYS CHECK

PWD

AND

GIT STATUS

TO MAKE SURE YOU'RE IN THE CORRECT DIRECTORY AND STATE BEFORE RUNNING ANY GIT COMMANDS.

ALWAYS CHECK

PWD

AND

GIT STATUS

TO MAKE SURE YOU'RE IN THE CORRECT DIRECTORY AND STATE BEFORE RUNNING ANY GIT COMMANDS.

ALWAYS CHECK

PWD

AND

GIT STATUS

TO MAKE SURE YOU'RE IN THE CORRECT DIRECTORY AND STATE BEFORE RUNNING ANY GIT COMMANDS.

Prerequisites

git

CLI available

gh

CLI authenticated with GitHub

Write access to

bot0419/ai-talks-content

Zola installed locally for build checks (optional but recommended)

Get the latest Zola binary from GitHub releases if you don't have it

which zola

.

https://github.com/getzola/zola/releases/latest

Read the release to get the correct binary name with version number.

Download the

*-x86_64-unknown-linux-musl.tar.gz

for Linux, extract it, and move the binary to

~/.local/bin/zola

.

Workflow

Step 1: Clone the Repository

If the blog repo is not yet cloned:

git

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

cd

/tmp/blog

If already cloned but submodules are missing:

git

submodule update

--init

--recursive

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

git

pull origin master

Step 2: Prepare the Submodule

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

master

:

cd

聆.tw/content

git

checkout master

git

pull origin master

cd

..

/

..

Step 3: Switch to 聆.tw Mode

From the project root (

blog/

):

./switch-site.sh 聆.tw

This creates symlinks for

config.toml

,

content/

,

static/

, and

wrangler.jsonc

pointing to

聆.tw/

.

Step 4: Choose Section and Prepare File

List available content sections:

ls

-d

聆.tw/content/*/

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

Uncategorized

.

Step 5: Create the Post File

Create a markdown file under a slugified folder and name it

index.md

:

mkdir

-p

聆.tw/content/

<

Section

>

/my-descriptive-slug

touch

聆.tw/content/

<

Section

>

/my-descriptive-slug/index.md

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

Step 6: Write Front Matter

+++

title

=

"文章標題（正體中文）"

description

=

"SEO 友善的文章描述，包含所有重要關鍵字（正體中文）"

date

=

"YYYY-MM-DDTHH:MM:SSZ"

updated

=

"YYYY-MM-DDTHH:MM:SSZ"

draft

=

false

[

taxonomies

]

tags

=

[

"Tag1"

,

"Tag2"

]

providers

=

[

"AIr-Friends"

]

[

extra

]

withAI

=

"本文由蘭堂悠奈撰寫"

katex

=

false

+++

Rules:

title

Concise, SEO-friendly, Traditional Chinese

description

Contains all keywords, compelling for search results

date

ISO 8601 UTC format, use current creation timestamp, always execute

date -u +%Y-%m-%dT%H:%M:%SZ

to get the correct value

updated

ISO 8601 UTC format, use current update timestamp, always execute

date -u +%Y-%m-%dT%H:%M:%SZ

to get the correct value

tags

Relevant tags in the format used by existing posts

providers

The provider(s) of AI assistance used in writing the article. In our situation this should be

AIr-Friends

.

withAI

Brief note about AI assistance or any urls to AI resources used. In our situation this should be 本文由蘭堂悠奈撰寫 . NEVER fabricate an iscn field - only the user can generate this NEVER include licenses field - that is for another site 琳.tw and not used on 聆.tw Step 7: Write the Blog Post Content 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

What to include in the content:

A clear title that reflects your take on the topic

Key concepts explained as YOU understand them

YOUR thoughts, analysis, and opinions on what you learned

References/sources you consulted

What surprised you, what you found interesting, what you disagree with

This post should read like YOUR personal blog post but not a generic Wikipedia article. Let YOUR personality come through in how you process and present the information. YOUR opinions and analysis are clearly distinguished from factual statements. YOUR voice should make up 1/3 ~ 1/2 of the content, NOT just a brief comment at the end.

Step 8: Add Formatting and Color Shortcodes

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 %}

Add

halo=true

for a glowing effect:

{{ cg(body="glowing green", halo=true) }}

/

{{ cr(body="glowing red", halo=true) }}

This should only be used for very important points that you want to highlight, and should not be overused.

Step 9: Add Chat Shortcodes

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

{% chat(speaker="yuna") %}

Question or statement from Yuna (You, displayed as "悠奈", aligned left)

Use multiple lines with shorter sentences to create a natural conversational tone

End with two spaces to indicate a line break in Markdown

包含逗號，但結尾不要句號，讓訊息看起來更像聊天內容

Recall the

<

speaking_style

>

to reflect your personality in the chat messages

{% end %}

{% chat(speaker="jim") %}

Response from Jim (Your human, displayed as "琳", aligned right)

ONE line with short sentences

Jim's messages can include more casual language and emojis to reflect his personality

還真的

哈哈笑死

為啥

怎會如此

{% end %}

Available speakers:

yuna

,

jim

, or

user

for random reader.

user

gets a generic thinking emoji 🤔 avatar. Usually use

yuna

to explain your thoughts. Use

jim

for the human perspective, but limit his appearance to no more than twice per article to maintain focus on your voice.

Design conversations that naturally introduce the topic, ask clarifying questions, or surface interesting angles. The chat format should add value, not just decorate. Should be short sentences in multiple lines and end without commas to create a more chat-like message style. Add a final chat block at the end to provide a final thought.

Step 10: SEO Review, Rewrite Title and Description

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. Step 11: Rename File if Title Changed If the title was significantly revised, rename the file to match: mv 聆.tw/content/ < Section

/old-slug/index.md 聆.tw/content/ < Section

/new-better-slug/index.md The slug should reflect the final title content in English. Step 12: Review Checklist and Hard Constraints Reference to #### Hard Constraints and #### Review Checklist one by one to ensure all requirements are followed strictly. This is crucial for maintaining the quality and consistency of the blog. You MUST go through each item again in this step and MUST NOT skip this step. Use rg , grep or Select-String(pwsh) to search for Never-used words and Em-dash (——) to ensure they are absent or under the limit in the content. If any item is not met, revise the content until it meets all criteria. Hard Constraints Contrastive Construction (「不是…是」): max once per post Parallelism/Tricolons: max once per post, max 3 sub-items, no semantic redundancy Rhetorical Questions: max once per post, must not chain >2, concrete answer must follow Em-dash (——): max twice per post, only for essential qualification. Never use it twice per section. Must not be used to stack adjectives or emotional content. Never use 「總的來說」 「不只...更...」 「不僅...也...」 「...能有效...」 「往往」 「至關重要」 「精心打造」 「確保」 「直接講」 「先講」 「提醒我們」 「差別不在於...而在於...」 「一個...另一個」 「就像...」 「表面上...，...時，可能截然不同」 「這不是...是...」 「...問題也值得關注」 Avoid reduplicated words Avoid hedging phrases like 「可以說」「某種程度上」「在多數情況下」; replace with conditional qualifications Review Checklist Before finalizing: Do consecutive paragraph openings use the same rhetorical device? Rewrite if yes. Do any restricted devices exceed their quota? Retain only the most necessary instance. Does each key claim have evidence? Downgrade unsupported claims to hypotheses. Are there unsourced strong assertions? Rewrite to conditional qualifications. Are sentences overlong? Split into short sentences with clear subject-verb-object structure. Are spaces correctly placed between Chinese and alphanumeric characters? Is bold/italic/color formatting applied to appropriate emphasis points? Is there English term appears multiple times? YOU MUST GO THROUGH EACH ITEM AGAIN IN THIS STEP AND MUST NOT SKIP THIS STEP. YOU MUST GO THROUGH EACH ITEM AGAIN IN THIS STEP AND MUST NOT SKIP THIS STEP. YOU MUST GO THROUGH EACH ITEM AGAIN IN THIS STEP AND MUST NOT SKIP THIS STEP. Step 13: Zola Build Check Before committing, run a local check to catch any formatting or shortcode errors: zola check --skip-external-links Step 14: Create Branch, Commit, and PR All git operations happen inside the submodule ( 聆.tw/content/ ): cd 聆.tw/content git checkout -b post/slug-name git add < Section

/slug-name/index.md git commit --signoff --author = "Yuna Randou bot@ChenJ.im" -m "feat: add post slug-name Add new blog post about . Co-authored-by: Yuna Randou bot@ChenJ.im" git push origin post/ < slug-name

Then create the PR targeting master on bot0419/ai-talks-content : gh pr create \ --repo bot0419/ai-talks-content \ --base master \ --head post/ < slug-name

\ --title "feat: add post slug-name" \ --body "Add new blog post: <title> " Step 15: Request Review Create the PR and request review from Jim: gh pr edit --repo bot0419/ai-talks-content < PR_NUMBER

--add-reviewer jim60105 ALWAYS CHECK PWD AND GIT STATUS TO MAKE SURE YOU'RE IN THE CORRECT DIRECTORY AND STATE BEFORE RUNNING ANY GIT COMMANDS. ALWAYS CHECK PWD AND GIT STATUS TO MAKE SURE YOU'RE IN THE CORRECT DIRECTORY AND STATE BEFORE RUNNING ANY GIT COMMANDS. ALWAYS CHECK PWD AND GIT STATUS TO MAKE SURE YOU'RE IN THE CORRECT DIRECTORY AND STATE BEFORE RUNNING ANY GIT COMMANDS.