jekyll-chirpy-blog
Use when editing the Jekyll/Chirpy blog or fixing mermaid.
- License 许可
- MIT
- 最近更新
- 2026-08-19
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- jekyll-chirpy-blog
- license
- MIT
- version
- 1.0.0
- metadata
- { "hermes": { "tags": [ "jekyll", "chirpy", "blog", "mermaid", "github-pages" ] } }
- description
- Use when editing the Jekyll/Chirpy blog or fixing mermaid.
02 资源文件 1
- 参考文档references/pages-deployment-diagnosis.md4.2 KB
03 SKILL.md 正文
peterlau123.github.io — Jekyll/Chirpy Blog Maintenance
User's personal blog (Jekyll + Chirpy theme, GitHub Pages). Cloned at
/data/lx/ai-engineer/peterlau123.github.io/ (origin git@github.com:peterlau123/peterlau123.github.io.git,
standard SSH URL — ~/.ssh/config routes github.com → ssh.github.com:443).
Posts live in _posts/YYYY-MM-DD-<slug>.md (some nested under _posts/ai/).
Mermaid rendering — root cause when flowcharts don't render
Chirpy theme only loads the mermaid JS bundle when the post's frontmatter has
mermaid: true (checked in _includes/js-selector.html: {% if page.mermaid %}).
Without it, ```mermaid blocks render as plain text — this is the #1 cause of
"flowchart 显示失败 / 渲染失败" reports.
Required frontmatter for any post containing mermaid:
---
title: "..."
date: YYYY-MM-DD
layout: post
categories: [System Design, Agent] # any
tags: [...]
mermaid: true
toc: true
---
layout: post + toc: true also appear on the working reference post
(_posts/ai/2026-04-15-Agent-Harness-Enineering.md) — copy its frontmatter shape.
Mermaid syntax conventions (worked: Bifrost post, 2026-08-18)
- Use
flowchart LR/flowchart TD, NOT the oldergraph LR— matches the blog's working diagrams. - Quote Chinese labels:
A["GPFS 共享存储"]— unquoted CJK labels can break parse. A["label<br/>second line"]for multi-line node text.- Subgraphs:
subgraph Name["显示名"] ... end; edges into/out of subgraphs are fine. - Dotted edge with label:
W1 -.->|"fallback: 100ms 轮询"| W2.
Validating mermaid without a browser
mmdc (mermaid-cli) requires puppeteer/Chromium which is NOT installed on mx001. Instead
install mermaid + jsdom as node packages and call mermaid.parse() — pure syntax check,
no browser:
cd /tmp && npm init -y >/dev/null 2>&1 && npm install mermaid dompurify jsdom --no-audit --no-fund
node -e "
const { JSDOM } = require('jsdom');
const dom = new JSDOM('<!DOCTYPE html><body></body>');
global.window = dom.window; global.document = dom.window.document; global.navigator = dom.window.navigator;
const fs = require('fs');
const m = require('mermaid').default;
m.initialize({ startOnLoad: false });
(async () => {
for (const f of process.argv.slice(1)) {
try { await m.parse(fs.readFileSync(f, 'utf8')); console.log('PASS ' + f); }
catch (e) { console.log('FAIL ' + f + ': ' + String(e.message||e).split('\n')[0]); }
}
})();
" /tmp/diagram1.mmd /tmp/diagram2.mmd
Notes:
require('mermaid')returns{__esModule, default}— always use.default.mermaid.render()additionally needsCSSStyleSheet(browser-only) — for CI-style validationparse()is enough.DOMPurify.addHook is not a functionmeans jsdom globals weren't installed before requiring mermaid;renderfailing with CSSStyleSheet is expected in plain node — don't chase it.- Feed each diagram from a
```mermaidblock into its own.mmdfile, then run the check.
Post edit workflow
git pull origin main && git checkout -b fix/<topic>(user convention: branch per change; never push to main).- Edit the post; keep frontmatter conventions above.
- Validate any mermaid blocks (above), verify code fences are paired
(
grep -c '```'should be even), check no leftover ASCII-art boxes (┌ │ ▼ └ characters) where a diagram was requested. - Commit
fix: <description>/feat: <description>, push. - PR creation:
POST /api.github.com/repos/peterlau123/peterlau123.github.io/pullswith the fine-grainedGITHUB_TOKENreturns 403 "Resource not accessible" — this repo's token has contents:write but NOT pulls:write (verified 2026-08-18; contrast: ai-infra-wiki PRs CAN be created via API). Fallback: push the branch and hand the user the compare URLhttps://github.com/peterlau123/peterlau123.github.io/compare/main...<branch>to open the PR manually.
GitHub Pages deployment diagnosis — when CI is green but the site 404s
The repo has two competing deployment mechanisms that silently conflict:
- Legacy Pages builder (
build_type: "legacy") — serves raw files frommainbranch. Controlled by Settings → Pages → Source = "Deploy from a branch". - Actions workflow (
.github/workflows/jekyll.yml) — builds with Jekyll and deploys viaactions/deploy-pages@v4. Controlled by Settings → Pages → Source = "GitHub Actions".
A .nojekyll file exists at repo root (added 2025-12-13). Under legacy mode,
this disables Jekyll processing entirely — Pages serves raw .md files as
text/plain. The Actions workflow builds correctly (Jekyll runs, artifact is
uploaded, deploy-pages returns success), but then the legacy builder also
runs and overwrites the Actions artifact with raw branch files.
Symptoms: CI all green, Pages build status built, but:
/posts/<slug>/→ 404/sitemap.xml→ 404,/feed.xml→ 404- Homepage returns 200 but only 34 bytes (raw frontmatter
---\nlayout: home\n---) - Two deployments for the same commit; one ends
successtheninactive(superseded by the other builder)
Fix (requires UI — API returns 403 for PUT /pages with the PAT):
Settings → Pages → Build and deployment → Source → change
"Deploy from a branch" to "GitHub Actions". Then re-trigger the workflow
(see "Re-triggering after Pages source change" below).
Re-triggering after Pages source change
After switching Pages Source to "GitHub Actions", the old legacy deployment artifact is still live — the site will continue 404ing until a new Actions workflow run produces a fresh artifact. You must re-trigger the workflow:
-
workflow_dispatchAPI returns 403 — the fine-grained PAT hascontents:writebut NOTactions:write, so:curl -s -X POST -H "Authorization: token $GITHUB_TOKEN" \ -H "Accept: application/vnd.github+json" \ "https://api.github.com/repos/peterlau123/peterlau123.github.io/actions/workflows/<workflow_id>/dispatches" \ -d '{"ref":"main"}' # → 403 "Resource not accessible by personal access token" -
Workaround: empty commit push (verified working 2026-08-18):
cd /data/lx/ai-engineer/peterlau123.github.io git pull origin main git commit --allow-empty -m "chore: trigger redeploy after Pages source changed to workflow" git push origin mainThis triggers the
on: pushevent for all workflows. The Jekyll build + deploy-pages workflow runs, produces a fresh artifact, and replaces the stale legacy deployment. -
Verify after ~2-4 minutes (Jekyll build takes time):
# CI should all be completed/success curl -s -H "Authorization: token $GITHUB_TOKEN" \ "https://api.github.com/repos/peterlau123/peterlau123.github.io/actions/runs?per_page=3" # Page should return 200 with real content (not 34 bytes) curl -sL -o /dev/null -w "HTTP %{http_code} | %{size_download} bytes\n" \ "https://peterlau123.github.io/posts/<slug>/" # Homepage should be ~20KB+ (full rendered HTML), not 34 bytes (raw frontmatter) curl -sL -o /dev/null -w "HTTP %{http_code} | %{size_download} bytes\n" \ "https://peterlau123.github.io/"Tell-tale signs of success: article page returns 200 with 40KB+, homepage returns 200 with 20KB+. If homepage is still 34 bytes, the workflow hasn't finished or the source change didn't save.
Diagnostic API calls (GITHUB_TOKEN from ~/.hermes/.env)
export GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | cut -d'=' -f2-)
# 1. Pages config — check build_type and source
curl -sL -H "Authorization: token $GITHUB_TOKEN" \
"https://api.github.com/repos/peterlau123/peterlau123.github.io/pages"
# build_type: "legacy" = bad (serves raw), "workflow" = good (Actions)
# 2. Latest Pages build status
curl -sL -H "Authorization: token $GITHUB_TOKEN" \
"https://api.github.com/repos/peterlau123/peterlau123.github.io/pages/builds/latest"
# status: "built" + error.message: null = build succeeded (but may be wrong builder)
# 3. Check .nojekyll exists
curl -sL -o /dev/null -w "%{http_code}" -H "Authorization: token $GITHUB_TOKEN" \
"https://api.github.com/repos/peterlau123/peterlau123.github.io/contents/.nojekyll?ref=main"
# 200 = .nojekyll present (disables Jekyll under legacy mode)
# 4. Workflow run statuses (all should be success)
curl -sL -H "Authorization: token $GITHUB_TOKEN" \
"https://api.github.com/repos/peterlau123/peterlau123.github.io/actions/runs?per_page=5"
# 5. Deployment statuses — look for "inactive" (superseded) vs "success"
curl -sL -H "Authorization: token $GITHUB_TOKEN" \
"https://api.github.com/repos/peterlau123/peterlau123.github.io/deployments?per_page=3"
# Then for each deployment ID:
curl -sL -H "Authorization: token $GITHUB_TOKEN" \
"https://api.github.com/repos/peterlau123/peterlau123.github.io/deployments/<ID>/statuses"
# 6. Live URL check — 404 + tiny body = Jekyll not running
curl -sL -o /dev/null -w "%{http_code} %{size_download}bytes" \
"https://peterlau123.github.io/posts/<slug>/"
curl -sL -o /dev/null -w "%{http_code}" "https://peterlau123.github.io/sitemap.xml"
Decision tree: if build_type=legacy AND .nojekyll exists AND CI is green
AND posts return 404 → the legacy/workflow conflict is the cause. Fix by switching
Source to "GitHub Actions" in repo Settings → Pages (user must do this in UI;
PAT returns 403 on PUT /pages).
See references/pages-deployment-diagnosis.md for the full session transcript
of this diagnosis, including the post-fix re-trigger sequence.
PAT permission matrix (peterlau123.github.io, verified 2026-08-18)
The fine-grained GITHUB_TOKEN in ~/.hermes/.env has limited scopes for this
repo. Known capabilities:
| API action | Result | Scope needed |
|---|---|---|
GET /pages (read config) |
✅ 200 | (read) |
PUT /pages (change build_type) |
❌ 403 | Pages admin |
POST /actions/workflows/.../dispatches |
❌ 403 | actions:write |
POST /pulls (create PR) |
❌ 403 | pulls:write |
GET /contents/... (read files) |
✅ 200 | contents:read |
PUT /contents/... (write files via API) |
✅ 200 | contents:write |
| Git push (via SSH key) | ✅ works | SSH key (separate from PAT) |
Pattern: when an API action returns 403, fall back to git push (SSH key is
independent of PAT scopes). An empty commit push is the universal workaround
for triggering on: push workflows when workflow_dispatch is blocked.
Environment notes
- No local Jekyll/Ruby (
bundlenot found) — cannotjekyll buildlocally; GitHub Actions deploys on merge. Validate mermaid syntactically and rely on CI for the rest. - GitHub Pages deploy requires
build_type: "workflow"(see diagnosis section above). If Pages Source is still "Deploy from a branch" (legacy), the site will serve raw files and all posts will 404 despite green CI. After changing Source to "GitHub Actions" in UI, must re-trigger via empty commit push —workflow_dispatchAPI returns 403 (PAT lacksactions:write). ghCLI is NOT installed; use the GitHub REST API viacurlwithGITHUB_TOKENfrom~/.hermes/.env.
04 同仓库更多 Skills
test-driven-development
TDD: enforce RED-GREEN-REFACTOR, tests before code.
systematic-debugging
4-phase root cause debugging: understand bugs before fixing.
spike
Throwaway experiments to validate an idea before build.
simplify-code
Parallel 4-agent cleanup of recent code changes.
requesting-code-review
Pre-commit review: security scan, quality gates, auto-fix.
python-debugpy
Debug Python: pdb REPL + debugpy remote (DAP).