| name | github-hugo-blog-ops |
| description | Operate a GitHub-hosted Hugo blog repository end-to-end. Use when tasks include creating/editing drafts in content/posts, publishing/unpublishing posts, running quality gates (doctor/seo/media checks), previewing or scheduling content, deploying safely with rollback tags, opening PR-based publish flows, or maintaining theme/workflow infrastructure. |
GitHub Hugo Blog Ops
Use this skill to execute repeatable blog workflows safely through scripts/blogctl.sh.
Quick Start
- Run commands from repo root.
- Use
skills/github-hugo-blog-ops/scripts/blogctl.sh.
- Export
BLOG_ROOT if running the script from outside this repo.
export BLOG_ROOT=/path/to/your/blog-repo
skills/github-hugo-blog-ops/scripts/blogctl.sh list
Workflow Decision
- Draft or edit content: Use
new, then edit markdown in content/posts/*.md.
- Publish content directly on
main: Use publish, check, then safe-deploy --push.
- Publish via PR: Use
pr-flow (recommended when review is required).
- Maintain infrastructure: Use
bootstrap, maintain, update-theme, and doctor.
- QA/SEO/media cleanup: Use
doctor, seo, and media.
Create Drafts
Use new to generate a correctly formatted TOML front matter block.
skills/github-hugo-blog-ops/scripts/blogctl.sh new \
--title "Install FFmpeg on macOS (2026 Update)" \
--summary "Practical ffmpeg install and verification commands for macOS." \
--keywords "ffmpeg,macos,video" \
--pin
Then write or revise the body in the created markdown file under content/posts/.
Publish Posts
Use publish to flip draft to false and set lastmod.
skills/github-hugo-blog-ops/scripts/blogctl.sh publish install-ffmpeg-on-macos
skills/github-hugo-blog-ops/scripts/blogctl.sh check
skills/github-hugo-blog-ops/scripts/blogctl.sh safe-deploy --message "Publish ffmpeg guide updates" --push
Use unpublish to move a live post back to draft mode.
New Operational Commands
bootstrap: Initialize submodules and environment sanity checks.doctor: Validate front matter, links, markdown quality, and build health.preview: Run local Hugo preview with drafts/future content support.schedule list: Show future posts via Hugo listing.schedule publish-due: Auto-publish due drafts based on date.media audit: Find empty image alt text and non-kebab local image names.media normalize: Rename local media filenames to kebab-case and update references.media compress: Compress large local images (threshold-based).seo: Audit title/summary lengths, canonical fields, OG cover, sitemap/robots.safe-deploy: Check + commit + tag + optional push, with rollback support.pr-flow: Create branch, commit, push, and optionally open GitHub PR.
PR Flow Example
skills/github-hugo-blog-ops/scripts/blogctl.sh doctor
skills/github-hugo-blog-ops/scripts/blogctl.sh pr-flow \
--branch "post/ffmpeg-2026-update" \
--message "post: ffmpeg 2026 update" \
--title "Update ffmpeg install guide" \
--body "Refresh steps and verification commands."
Use --dry-run first for safe-deploy and pr-flow to preview actions safely.
Maintenance Tasks
Use maintain for repository health signals:
- git working tree summary
- submodule status for
themes/github-style
- presence of
.github/workflows/hugo.yml
- local Hugo installation status
Use update-theme to fast-forward the theme submodule and prepare a commit.
skills/github-hugo-blog-ops/scripts/blogctl.sh bootstrap --update-theme
skills/github-hugo-blog-ops/scripts/blogctl.sh doctor
skills/github-hugo-blog-ops/scripts/blogctl.sh update-theme
skills/github-hugo-blog-ops/scripts/blogctl.sh check
skills/github-hugo-blog-ops/scripts/blogctl.sh safe-deploy --message "Update theme submodule" --push
Guardrails
- Avoid manual front matter toggles when
blogctl.sh can do it deterministically.
- Run
doctor and check before safe-deploy --push.
- Keep publishing on
main because GitHub Pages deployment is triggered by pushes to main.
- Prefer
pr-flow over direct pushes when review/approval is needed.
- Keep commits scoped to blog changes; avoid unrelated edits in publish commits.
- Use
safe-deploy rollback --dry-run before real rollback.
Reference File
Load references/repository-operations.md for path conventions, deployment mechanics, and maintenance checklist.
