SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillswjs-publishing-hugo

wjs-publishing-hugo

Deployment & operations

View repository

Updated 10-15 23:32

About this skill

wjs-publishing-hugo

A conversational backend for a Hugo blog.I am the backend—no CMS, no /admin page, no PAT, no Cloudflare. You say what to publish, and I edit according to the repository conventions, content/, place images, commit, push, and go live automatically through the repository's existing deployment flow.

Applies to: Hugo sites like maggiacito.com (content/posts/*.md + categories/tags taxonomy + GitHub Pages Actions deployment). Other Hugo repositories can also use it; first align with the conventions per the "Preflight checks" below.

Preflight checks (do this first every time you start work)

  1. Confirm you are at the Hugo repository root: there is hugo.toml(or config.toml) and content/. If not, ask the user for the path.
  2. Read hugo.toml: get timeZone、[taxonomies](confirm categories/tags）。
  3. Look at the front matter of an existing post (pick any one incontent/posts/ ), and confirm the fields match the "Authoritative format" below; if they do not match, go by therepository's current state, and do not apply this document's defaults.

Authoritative post format (maggiacito current state)

File:content/posts/<slug>.md. The front matter is strictly as follows, with the date using YYYY-MM-DD HH:MM:SS（Asia/Shanghai）：

---
title: "标题"
date: 2026-06-04 21:30:00
lastmod: 2026-06-04 21:30:00
categories: ["知天命"]
tags: []
url: /知天命/标题/
---

正文 markdown……
  • url explicitly write /<主类目>/<标题或slug>/(following the link style migrated from WordPress; categories and titles may contain Chinese).
  • categories / tags is a string array, may be empty []。
  • Do not hand-write front matter—use scripts/new-post.py to generate it, so the format will not drift.

Workflow

1. Add a post

Get the title + body (the user can provide a draft/link/scattered ideas; polish as needed), choose the category, then:

echo "<正文 markdown>" | python3 <SKILL_DIR>/scripts/new-post.py \
  --repo <仓库根> --title "标题" --category "知天命" --slug 可选英文slug

The script generates content/posts/<slug>.md and prints the path. When --slug is not passed, derive the filename from the title (Chinese is fine too; readers do not see the filename). When --url is not passed, default to /<首个类目>/<标题或slug>/. If another link is needed, use --url to override.

2. Edit a post

Directly edit the corresponding content/posts/*.md: change the body freely; if the content is changed, update lastmod to the current time, and leavedate unchanged.

3. Manage categories

  • First list the existing categories for the user to choose from (to avoid creating duplicates):bash <SKILL_DIR>/scripts/categories.sh <仓库根>
  • New category: just add it on the spot to the post's categories[] , and Hugo taxonomy will automatically create the /categories/<名>/ page, with no other configuration needed.
  • Rename/merge categories: scan all content/posts/*.md 's categories[] and replace in bulk (this is something a CMS cannot do but I can). After the change, remind the user that the old /categories/<旧名>/ links will become invalid.

4. Upload images

Put new images in static/uploads/<年>/(served as /uploads/...); leave the old static/wp-content/uploads/ unchanged.

python3 <SKILL_DIR>/scripts/add-image.py <本地图片> --repo <仓库根> --alt "说明"

Print a one-line markdown image link and insert it into the body. Images wider than 2000px will be automatically resized using macOS sips .

5. Publish live

Local preview (optional):hugo server -D → view http://localhost:1313 . After confirming, publish:

bash <SKILL_DIR>/scripts/publish.sh "post: <标题>" <仓库根>

A regular user's git push will trigger deploy.yml（on: push) to build and go live—Only the feedback bot's GITHUB_TOKEN pushesget blocked by GitHub's anti-recursion protection; your own pushes are unaffected. After pushing, you can gh run watch check the deployment.

Scope (YAGNI)

Only do: create/edit posts, manage categories, upload images, publish.Don't docomments, user management, draft workflows, scheduled publishing.

Common mistakes

  • ❌ Hand-writing front matter causes date format/field drift → ✅ Always go through new-post.py。
  • ❌ Stuffing images into static/wp-content/uploads/(that's a legacy directory from migration) → ✅ Put new images into static/uploads/。
  • ❌ Edited a post but forgot to update lastmod → ✅ Sync after editing lastmod。
  • ❌ Created a category with the same name/similar meaning as an existing one → ✅ First categories.sh take a look before deciding.
  • ❌ Think pushing won't auto-deploy (misled by that GITHUB_TOKEN limitation in the feedback loop) → ✅ Your own push will trigger deploy.yml。
  • ❌ Set a colliding url(duplicates an existing post) → ✅ Use categories.sh/grep to check for duplicates, and if necessary --url specify a unique path.