/mykg-github-pages

name: mykg-github-pages
description: Set up and maintain the GitHub Pages site for the mykg repo (SenolIsci/mykg) — a purpose-built pages/ folder (landing page adapted from README.md, blog posts, diagrams), built by a GitHub Actions workflow that runs Jekyll and deploys the result to a gh-pages branch. Use whenever the user wants to publish project documentation or blog articles as a website, create a landing page, turn the project into a public site, enable/configure/troubleshoot GitHub Pages or the gh-pages branch, add a new page/blog post/diagram to the published site, fix a broken/failing Pages build, or asks things like "can we get a docs site for mykg", "I want a landing page based on README", "publish this blog article", "is Pages enabled yet", "the pages workflow failed", or "add this new doc to the site". Also trigger on custom domain / CNAME requests for the project site. Scoped to the mykg repo's own pages/ folder and its gh-pages publishing pipeline — not for unrelated new project sites.

mykg GitHub Pages

Publishes a purpose-built `pages/` folder from the `SenolIsci/mykg` `main` branch as a website, via a GitHub Actions workflow that builds it with Jekyll and pushes the built `_site/` output to a `gh-pages` branch, which is what GitHub Pages actually serves.

main branch                        gh-pages branch
├── src/       ← software          ├── index.html   ← built site
├── pages/     ← Pages source      ├── blog/...
│   ├── _config.yml                └── ...  (generated — never hand-edit)
│   ├── _posts/          (blog articles)
│   ├── index.md         (landing page, adapted from README.md)
│   └── diagrams/
└── .github/workflows/pages.yml

pages.yml: on push to main (pages/** changes) → jekyll build pages/ → _site/
           → peaceiris/actions-gh-pages pushes _site/ to gh-pages
Settings > Pages: source = gh-pages branch

Why a dedicated `pages/` folder

A dedicated `pages/` folder holds *only* content written for the public site, so there's never anything to accidentally publish. This skill's default and only source for initial content is `README.md` (see Step 1) — it never assumes any other folder in the repo is publishable. Any other repo artifact (a diagram, a logo, a screenshot, an existing doc) is fair game to feature on the site, but only when the user explicitly points at it — see "Sourcing artifacts from the repo" below. Don't scan the repo looking for content to publish; ask instead.

Check state before doing anything

gh api repos/SenolIsci/mykg/pages 2>&1
git ls-remote --heads origin gh-pages
cat .github/workflows/pages.yml 2>&1
ls pages/ 2>&1

• No `pages/` folder, no `gh-pages` branch, no workflow file → first-time

setup. Do the full flow: Step 1 through Step 5.

• `pages/` and the workflow already exist → maintenance request (add a page,

add a blog post, fix a failing build). Skip to the relevant section below.

• Workflow exists but the last run failed → go straight to Troubleshooting.
• Pages config exists but `build_type` is `"workflow"` while this repo

deploys via a branch push (i.e. `source.branch` isn't reliably `gh-pages`, or the live URL 404s despite green Actions runs) → the misconfiguration described in Step 5/6 and Troubleshooting; fix with a `PUT` setting `build_type=legacy` before doing anything else.

• `build_type`/`source` look correct, Actions runs are green, `gh-pages` has

real content, but the live URL still 404s and `gh api .../pages --jq .status` is `null` → check whether `.github/workflows/pages.yml`'s deploy step uses `secrets.GITHUB_TOKEN` instead of a PAT secret. See Step 4a and the matching Troubleshooting entry — this is a different bug from the `build_type` one above and looks identical from the outside.

• The "Deploy to gh-pages" Actions step itself fails with `remote:

Permission ... denied` / `403` on `git push origin gh-pages` → the PAT in the secret is fine-grained, not classic, or lacks the `repo` scope. See Step 4a — this repo's setup only worked with a classic PAT.

• The live URL returns `200` and loads real HTML, but the page has no

styling at all (default browser serif font, no colors, no layout — looks like the theme never applied) → check `pages/_config.yml` for `baseurl: "/mykg"`. See Step 3 — missing `baseurl` on a project Pages site makes the CSS `<link>` resolve to the domain root instead of `/mykg/...` and 404 silently; nothing in the Actions build or Pages config flags this.

Step 1 — Scaffold `pages/` and the landing page

Create `pages/index.md` as the site's landing page, adapted from `README.md` — not a straight copy. The README carries CI/PyPI/codecov badges, a long table of contents, and prose written for someone about to `pip install` and read source code; a landing page is written for someone deciding whether the project is relevant to them at all. Concretely:

• Lead with what myKG does and why (the first paragraph or two of the

README's intro is usually the right seed).

• Keep the logo.
• Drop CI/coverage/PyPI-version badges — they're repo-maintenance signals,

not landing-page content. A "View on GitHub" / "PyPI" link pair is enough.

• Link out to: the blog (once it exists — see Step 2), the GitHub repo, and

PyPI. Don't try to reproduce the README's full command reference — link to it on GitHub instead of duplicating it.

• Ask the user to review the draft copy before moving on — this is the page

a stranger sees first, worth a second pair of eyes rather than shipping silently.

The README typically references logo/image assets by path or URL. Confirm with the user which asset(s) to feature and where those files live in the repo, then copy (don't move) them into `pages/assets/` — the source folder keeps its own copies since other things may still reference them there. See "Sourcing artifacts from the repo" below for the general pattern this follows for any asset, not just the logo.

Step 2 — Blog articles

Use