add_article.py 使用指南

最後更新：2026-05-20（新增 SKILL 指針：完整發布流程含 SEO 請使用 發布文章 SKILL） 文件狀態：有效 ⚠️ 建議：新文章發布請優先使用 .claude/skills/發布文章.md（含聚落分類 + 延伸閱讀 + Twitter Cards 驗證 + 雙向內鏈）；本文件保留為 add_article.py 參數參考手冊 腳本位置：C:\Users\USER\Desktop\職涯停看聽_網站\add_article.py 版本：v1.1（2026-04-28 排程發布支援）

---

1. 這是什麼

add_article.py 是 careerssl.com 官網的文章發布腳本，由 Claude 執行（Tim 只需提供文章內容與基本參數）。

執行後發生的事：

1. 從 blog/_article_template.html 套入模板
2. 生成 blog/SLUG.html（文章頁面）
3. 更新 blog/articles.json（文章列表，新文章 prepend 到最前）
4. 雙向更新：舊的最新篇的 article-nav-prev 連結更新為指向新文章

---

2. 前置條件

---

3. 必填參數

---

4. 選填參數

---

5. 兩種發布模式

模式 A：立即發布（預設）

cd C:\Users\USER\Desktop\職涯停看聽_網站
python add_article.py \
  --title "標題" \
  --date "2026-04-28" \
  --slug "2026-04-28-article-slug" \
  --tags "標籤1,標籤2" \
  --content-file "blog/_temp_content.html"

執行後：

• ✅ blog/SLUG.html 已建立
• ✅ blog/articles.json 更新（新文章在最前）
• ✅ 舊的最新篇 PREV 連結更新
• 🔗 預期 URL：https://www.careerssl.com/blog/SLUG.html

模式 B：排程發布（--schedule）

python add_article.py \
  --title "標題" \
  --date "2026-04-28" \
  --slug "2026-04-28-article-slug" \
  --tags "標籤1,標籤2" \
  --content-file "blog/_temp_content.html" \
  --schedule "2026-05-01"

執行後：

• ✅ blog/SLUG.html 已建立（URL 存在但列表不顯示）
• ⏰ blog/articles.json 不更新（文章不在列表）
• ✅ blog/scheduled/SLUG.json 排程描述檔已存入
• 🤖 GitHub Actions 每日 09:00（台灣時間）掃描並自動正式發布

--date 是文章顯示的撰寫日期；--schedule 是實際公開上架日期，兩者可不同。

---

6. Claude 標準執行 SOP（每次發文）

Tim 只需提供：文字 + 日期 + 標籤（和是否排程）

Step 1：準備內容檔

• 將文章 HTML 內容儲存至 blog/_temp_content.html

Step 2：決定 slug

• 格式：YYYY-MM-DD-英文關鍵字（3–5 個英文字，清楚描述主題）
• 例：2026-04-28-resume-rewrite-career-change

Step 2.5：Excerpt 策略判斷（⚠️ IMP-082 升規，2026-04-29）

文章開頭決定 excerpt 策略：

場景鋪陳式 Excerpt 撰寫模板（60–80 字）：

[核心 reframe 一句話]。[內容形式（故事/對照/三步驟）]，[讀者利益（學會什麼/得到什麼）]。

範例：「快不行了」不是心理感受，是大腦在呼救。從大衛與蘇菲的對照看懂過勞本質，學會戰略性保護核心資本。

Step 3：執行腳本

cd C:\Users\USER\Desktop\職涯停看聽_網站
python add_article.py --title "..." --date "YYYY-MM-DD" --slug "..." --tags "..." --content-file "blog/_temp_content.html"

Step 4：確認輸出

• 看到 ✅ blog/SLUG.html 已建立 + ✅ articles.json 更新（共 N 篇） 表示成功

Step 5：刪除暫存檔

del blog\_temp_content.html

Step 6：補齊 UI（執行 batch_update）

python batch_update_all_articles.py

此腳本補齊所有文章的 Email 訂閱框等 UI 元素，每次發布後必須執行

Step 7：部署

npx vercel --prod

先 npm run build 通過再 git push，最後 npx vercel --prod（依標準部署三步驟）

---

7. 批量發布注意事項

同時發布多篇文章時（如補上舊文），順序很重要。

• 由舊到新呼叫腳本：確保 NEXT/PREV 雙向連結正確建立
• 所有文章 HTML 生成後，統一執行一次 batch_update_all_articles.py 與 npx vercel --prod
• 不需每篇都部署，最後一次統一部署即可

---

8. 常見錯誤排查

---

9. 模板欄位對照

腳本自動填入以下 {{PLACEHOLDER}} 欄位：

---

10. 腳本位置與相關檔案