create-gh-pages-site
Scaffold a working GitHub Pages website from a vetted template and wire it to deploy automatically. Use when the user wants to create, scaffold, or publish a site on GitHub Pages: a reviewable VitePress specification, a static page, an Astro or Eleventy site, a React (Vite) SPA,
Install
npx skills add https://github.com/jongio/skills/tree/main/skills/create-gh-pages-site
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install jongio-skills@llmmart
git clone https://github.com/jongio/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole jongio/skills collection as a plugin from our marketplace. Git is the plain clone.
README
create-gh-pages-site
Scaffold a working GitHub Pages website from a vetted template and wire it to deploy automatically — packaged as a GitHub Copilot skill.
Pick a template (static, Astro, React + Vite, Eleventy, Jekyll, or skills catalog); the skill injects the correct base path for your repo, adds the current official GitHub Actions Pages workflow, drops it into your repo (the current repo by default, or a new one), and tells you how to turn Pages on.
It doesn't stop at the template's demo content, either: it digests your repo (README, manifests, entry points, docs) and authors a site that's actually about your project — a CLI reference, an API/usage page, a feature tour, or a catalog of parts — and drops in labeled image placeholders you swap for real art.
Quickstart
1. Install the skill:
npx skills add jongio/skills --skill create-gh-pages-site
2. Reload skills — run /skills reload, or start a new session.
3. Ask Copilot to build a site:
/create-gh-pages-site put this repo on GitHub Pages as an Astro blog
By default the agent scaffolds for the repo you're in — it reads the current
repo from git, picks the astro template, sets site/base for it, lays down the
deploy workflow, and shows you how to enable Pages. Name a different repo
(octocat/blog) only when you want one.
Why this exists
GitHub Pages' hard parts aren't the HTML — they're the deploy plumbing and the
base-path trap: a project site lives at https://USER.github.io/REPO/, so a
site built for / ships with broken assets and links. Every framework fixes this
differently (Astro base, Vite base + 404.html, Eleventy pathPrefix, Jekyll
baseurl). This skill gets all of it right, every time.
Templates
| Template | Use it for | Base path | Build |
|---|---|---|---|
static-html |
landing pages, a few hand-made pages | relative URLs (immune) | none |
astro |
content sites, blogs, docs, marketing | base in astro.config.mjs |
astro build |
react-vite |
interactive SPAs / dashboards | base + 404.html fallback |
vite build |
eleventy |
data/Markdown-driven sites | pathPrefix via env + url filter |
eleventy |
jekyll |
GitHub-native / existing Jekyll | baseurl in _config.yml |
Jekyll |
skills-catalog |
browsable catalogs for Copilot skills repositories | template base helper | registry-defined |
The built-in registry pin includes skills-catalog. Custom registries require a
full --registry-ref, and local checkouts use --templates-dir.
All templates deploy via the GitHub Actions Pages source. Every external action
must be pinned to a full commit SHA, checkout must disable persisted credentials,
and install steps must disable lifecycle scripts. No gh-pages branch is used.
Workflow scanning accepts a conservative block-style YAML subset and rejects
quoted keys, tags, anchors, aliases, merge keys, and unsupported flow mappings.
Browse them in the live gallery with previews,
hosted from the jongio/gh-pages-templates registry.
Tailored to your repo, not a demo
A stamped template is a skeleton, not the deliverable. After stamping, the skill reads your repo and rewrites the content to match it:
scripts/digest-repo.mjsanalyzes the repo and classifies it —cli,library,app,action,collection,docs, orsite— and pulls out the name, pitch, install commands, README usage examples, badges, docs, existing images, and sub-projects. That drives which kind of site gets built: a command reference for a CLI, an API/usage page for a library, a feature tour for an app, a catalog for a monorepo.scripts/make-placeholder.mjsdrops labeled placeholder images (logo, social card, hero, screenshots) into the site plus anIMAGES.mdchecklist telling you what to supply and at what size. Real images the repo already has are reused instead.
node scripts/digest-repo.mjs --dir . --json # see what the author sees
node scripts/make-placeholder.mjs --out site/public/images --preset cli --repo octocat/mytool
Use it
Once installed, describe the site you want:
/create-gh-pages-site a docs site with Eleventy in a new repo called octocat/docs
/create-gh-pages-site put this folder of HTML on Pages
You don't have to name the skill — the agent routes to it whenever you ask to create or publish a GitHub Pages site.
Build it yourself (no agent)
The generator stamps the same site the skill uses. Templates are fetched from the
jongio/gh-pages-templates registry
at an immutable commit, so it needs git + network unless you pass --templates-dir.
The built-in registry uses a reviewed pinned commit. A custom registry requires
--registry-ref with its full 40-character commit SHA:
Free-form metadata is limited to context-safe text because the same sentinel can appear in HTML, JSON, YAML, and JavaScript. Markup, control characters, and context-breaking quotes are rejected instead of being copied into generated code.
# Scaffold for the CURRENT repo (base path read from its origin remote):
node scripts/new-site.mjs astro
# An Astro site for a specific project repo (base = /blog/):
node scripts/new-site.mjs astro --repo octocat/blog --site-name "Octocat's Blog"
# A React SPA:
node scripts/new-site.mjs react-vite --repo octocat/dashboard
# A user site (served from "/") or a quick local scaffold:
node scripts/new-site.mjs static-html --base / --dir ./site
# Offline, from a local registry checkout:
node scripts/new-site.mjs astro --templates-dir ../gh-pages-templates/templates
# A custom registry is always commit-pinned:
node scripts/new-site.mjs skills-catalog --repo octocat/skills \
--author "Octo Cat" --marketplace-id octocat-skills --default-branch trunk \
--registry octocat/templates --registry-ref 0123456789abcdef0123456789abcdef01234567
# List templates:
node scripts/new-site.mjs --list
Safe staging for composition
create-skills-repo and other generators should stage the site instead of writing
into their target:
node scripts/new-site.mjs skills-catalog \
--repo octocat/skills \
--templates-dir ../gh-pages-templates/templates \
--staging-dir ./.site-staging \
--json
The staging contract is fail-closed:
--staging-dirmust name a path that does not exist.- It cannot be combined with
--diror--force. - The generator copies and substitutes the template only in that directory.
- It validates paths, symlinks, sentinels, and workflows before returning success.
- It never reads or writes the consumer's final target. The consumer owns conflict detection and the final merge.
--jsonreturnsmode,directory,template, registry identity, and replacements so callers do not need to parse console prose.
Normal generation uses the same staging and validation pipeline internally, then
applies the validated tree to --dir. Existing --force behavior remains
available only for this explicit apply mode.
Earlier generator versions skipped symbolic links during rewriting. Current versions reject every symbolic link before staging because templates can come from an external registry.
The pinned built-in snapshot already uses immutable action commits. Compatibility normalization remains restricted to that exact reviewed snapshot, rewrites only known legacy forms, and always runs the same validator afterward. Custom registries receive no migration and fail closed.
Then push to main and set Settings → Pages → Source → GitHub Actions. The
workflow publishes on every push; the live URL appears in the Actions run. Point
the repo's "Website" link at it with gh repo edit OWNER/REPO --homepage <site-url>
(the same as checking "Use your GitHub Pages website").
Install options
# Into the current project (.agents/skills/create-gh-pages-site/):
npx skills add jongio/skills --skill create-gh-pages-site
# Pin to a branch or tag:
npx skills add jongio/skills#main --skill create-gh-pages-site
Copilot plugin marketplace:
copilot plugin marketplace add jongio/skills
copilot plugin install create-gh-pages-site@jongio-skills
Local install (no network):
pwsh -File scripts/install-local.ps1
After any install, reload skills with /skills reload or a new session.
A contributable registry
Templates live only in the
jongio/gh-pages-templates registry
with each template in a folder containing a template.json manifest. The generator
fetches the built-in registry at a pinned commit. Override it with both
--registry owner/repo and --registry-ref <full-sha>, or scaffold offline with
--templates-dir <path>. The browsable gallery + live previews are hosted from the
registry too. Adding or fixing a template is a PR to that repo — see its
CONTRIBUTING.md. This skill owns the generator + the agent workflow, not the
templates.
Run the tests
npm test
# node test/generator.test.mjs && node test/digest.test.mjs
No dependencies are needed. The tests run on bare node (18+) and never use the
network. They exercise base-path math, skills-catalog discovery, immutable local
registry checkout, staging, traversal and symlink rejection, sentinel validation,
workflow policy, repo digestion, and placeholder generation.
Layout
SKILL.md The skill (authoring contract + workflow)
scripts/
new-site.mjs Generator: fetch, stage, validate, and apply a template
new-site-cli.mjs Command-line parsing and machine-readable output
template-registry.mjs Immutable registry checkout and verification
template-security.mjs Path, symlink, sentinel, and workflow validation
digest-repo.mjs Analyze a repo → JSON signals + type classification
make-placeholder.mjs Generate placeholder images + an IMAGES.md checklist
install-local.ps1 Install this skill into $COPILOT_HOME/skills
test/ Generator and digest tests (bare node, offline fixture)
License
MIT — see LICENSE.
Skill manifest
Create GitHub Pages Site
Scaffold a vetted Pages template with the correct base path and deployment workflow. Replace demo content with repo-derived content.
When to use which template
Pick by what the user is building. If unsure, ask one question (content vs. app)
and default to static-html for the simplest ask.
| Template | Reach for it when… | Tier | Build |
|---|---|---|---|
static-html |
A landing page, a few hand-made pages, "just put this HTML up". No toolchain. | static | none |
astro |
A content site, blog, docs, or marketing page that should be fast and mostly static. | SSG | astro build |
react-vite |
An interactive single-page app / dashboard with client-side routing. | SPA | vite build |
eleventy |
A data/Markdown-driven site (blog, docs) where content is files + structured data. | data SSG | eleventy |
jekyll |
The user wants the GitHub-native path, or is migrating an existing Jekyll site. | native | Jekyll |
skills-catalog |
A browsable catalog for a repository of Copilot skills, especially when composing create-skills-repo. |
catalog | registry-defined |
spectator |
A technical specification, RFC, architecture proposal, design proposal, engineering decision, or policy proposal built for structured review. | SSG | vitepress build docs |
The built-in registry pin must include the selected template. A custom registry
requires an explicit --registry-ref, and a local checkout uses
--templates-dir.
These seven cover the static / SSG / SPA / data / native / catalog / specification quadrants. For richer themes, point the user at upstream galleries (astro.build/themes, jamstackthemes.dev, github.com/topics/github-pages-template) and adapt — don't try to hand-build a theme from scratch.
The base-path trap (the thing to get right)
A GitHub project site is served from a subpath:
https://<user>.github.io/<repo>/. A site built assuming root (/) ships with
broken CSS, images, and links the moment it's a project site — assets 404 and the
page looks blank. A user/org site (<user>.github.io repo) is served from
/, so it must NOT carry a subpath prefix.
Each framework fixes this differently. The generator handles all of it from the repo name; you rarely set it by hand:
| Template | Mechanism | Project value | User-site value |
|---|---|---|---|
static-html |
relative URLs (./assets/...) |
— (immune) | — (immune) |
astro |
base in astro.config.mjs |
/repo/ |
/ |
react-vite |
base in vite.config.js + basename + 404.html |
/repo/ |
/ |
eleventy |
pathPrefix via PATH_PREFIX env + url filter |
/repo/ |
/ |
jekyll |
baseurl in _config.yml + relative_url |
/repo (no slash) |
"" (empty) |
spectator |
base in spectator.config.ts and VitePress config |
/repo/ |
/ |
The generator detects the <user>.github.io user-site pattern and uses /
automatically. If the user hasn't named the repo yet, scaffold with the repo
they intend; if they truly don't know, use --base / and tell them to re-run (or
edit the base) once the repo exists.
Deployment model — one consistent flow
Every template deploys via the GitHub Actions Pages source, not from a branch. Every external action reference must use a full commit SHA.
static-html,react-vite,eleventyuse that chain directly.astrouses the officialwithastro/action@v6(it builds + produces the Pages artifact) thenactions/deploy-pages@v5.jekylluses GitHub's officialactions/jekyll-build-pages@v1thendeploy-pages.
Every workflow limits top-level permissions to contents: read, grants Pages and
identity-token access only to the jobs that need them, uses one Pages concurrency
group, and deploys through the github-pages environment. There is no
gh-pages branch to manage.
Action versions deprecate aggressively. Update the template registry to a reviewed action commit, then bump this skill's immutable default registry commit.
Interview first — never scaffold on a guess
This skill produces a real repo with a live deploy pipeline, so getting the inputs
right matters more than speed. Do not stamp anything until you know (a) which
template and (b) the target repo (or an explicit base path). If the prompt is bare
("make me a GitHub Pages site") or names no framework/repo, interview the user — ask
only for what's missing, one focused question at a time, using the ask_user tool:
What kind of site? Map the answer to a template:
- "a landing page / just some HTML / the simplest thing" →
static-html - "a blog / docs / content / marketing site, fast" →
astro(oreleventyif they say Markdown- or data-driven, orjekyllif they want the GitHub-native path or are migrating an existing Jekyll site) - "an app / dashboard / interactive / single-page app" →
react-vite - "a catalog of Copilot skills / create a skills repo" →
skills-catalog - "a specification / RFC / architecture or design proposal / engineering
decision / policy proposal / site like the Eval Authoring Guide" →
spectator
If they're unsure, ask the single discriminating question — content site or interactive app? — and default to
static-htmlfor the simplest ask.- "a landing page / just some HTML / the simplest thing" →
Which repo? Assume the current repo by default. The site is for the repo in context unless the user says otherwise — don't ask "current or new." Detect the current repo from git (
git remote get-url origin, parsed toowner/name); the generator does the same automatically when you omit--repo. The repo drives the base path, so you must resolve it before stamping:- Current repo detected → use it. State the assumption in one line
("Scaffolding into this repo, octocat/blog → base
/blog/") and proceed; no question needed. - No git context, detached, or no
origin→ then ask for theowner/name, and whether it's an existing repo or a new one to create. - Only treat it as a new/different repo when the user explicitly asks for one.
For a user site, confirm the repo is named
<user>.github.io(base/); otherwise it's a project site (base/repo/).
- Current repo detected → use it. State the assumption in one line
("Scaffolding into this repo, octocat/blog → base
Title? Optional — default to the repo name; never block on it.
You usually don't need to ask "what should the site say?" — the content comes from
the repo (you digest it after stamping; see "Digest the repo, then author it").
When the target repo is the current/an existing one, run digest-repo.mjs early to
confirm the type and let it inform the template choice (e.g. a cli repo is a great
fit for astro or static-html with a command reference). If the repo is empty or
brand-new, fall back to asking what the site should cover.
Skip any question the prompt already answered: "an Astro blog for octocat/blog"
needs no interview (template astro, repo octocat/blog). For a bare "put this on
Pages" inside a repo, assume the current repo and ask only for the template. Ask
only for the gaps. When you inferred rather than were told, confirm in one line
before scaffolding — e.g. "Astro site → octocat/blog (current repo), base /blog/ —
go?"
Output location invariant
The user's current working directory is the destination workspace. A repo slug
such as octocat/blog determines the Pages base path and URLs; it does not mean the
site belongs in /tmp/blog, a sibling directory, or the skill's own directory.
- If the workspace already contains repo files, scaffold in place with
--dir . --force, even when it is not a git checkout and the prompt supplies the repo slug explicitly. - Never
cdinto the skill directory to run the generator. Invokescripts/new-site.mjsby its absolute path while keeping the workspace as the process working directory. - Use another output directory only when the user explicitly asks for a subfolder or a new/different repo.
- When another generator is composing the result, use
--staging-dirinstead of--dir. The staging directory is isolated and the consumer owns the final merge. - Before reporting completion, confirm the generated config, content, and
.github/workflowsfiles exist under the original working directory.
The workflow you follow
- Interview / gather context. Resolve the questions above via
ask_user. You MUST end up with a chosen template and a target repo (or explicit--base) before stamping. Default the target to the current repo (detect it fromgit remote get-url origin); only ask when there's no git context or the user wants a different/new repo. - Pick the template from the table above.
- Stamp it with the generator (next section). This injects the base path, site URL, and title, and lays down the deploy workflow.
- Place it in the repo:
- Current repo (default): stamp into the repo root (or a subfolder if it's a
subdirectory site, adjusting the workflow's upload path). From the original
working directory, invoke the generator by absolute path and pass
--dir .--forceto write in place. Reconcile an existingdeploy.ymlrather than blindly overwriting it. - New repo (only when asked): create it (e.g.
gh repo create <name> --public), stamp into it, and push. Match the repo name you used for the base path.
- Current repo (default): stamp into the repo root (or a subfolder if it's a
subdirectory site, adjusting the workflow's upload path). From the original
working directory, invoke the generator by absolute path and pass
- Digest the repo and author the site (see "Digest the repo, then author it"
below). This is the step that makes the site real: run the digest, replace
every default page/section with repo-derived content of the right kind, add
image placeholders + an
IMAGES.md, and prompt the user for the real images (they can paste screenshots straight into the chat). Never skip to enabling Pages on the demo content. - Enable Pages. Tell the user (or do it with their approval):
Settings → Pages → Source → GitHub Actions. By CLI:
gh api -X POST repos/<owner>/<repo>/pages -f build_type=workflow(or PUT to update). After the first push tomain, the workflow runs and the live URL appears in the Actions run summary and under Settings → Pages. - Set the repo website link to the Pages URL (the "Website" field in the repo
header — same as ticking Settings → "Use your GitHub Pages website"). This is
just the repo's
homepage; point it at the site URL the generator prints:gh repo edit <owner>/<repo> --homepage <site-url>(orgh api -X PATCH repos/<owner>/<repo> -f homepage=<site-url>). Offer to set the exact URL, or let the user supply a custom domain instead. There's no separate "use Pages" boolean — settinghomepageto the Pages URL is the checkbox. - Verify it actually works (see "Validate" below) — don't claim success on a green workflow alone, and don't claim success while template default copy or "Hello, world" demo content is still on the page.
Stamp a site — the generator
node scripts/new-site.mjs <template> --repo <owner/name> [options]
| Option | Purpose |
|---|---|
--repo <owner/name> |
Target repo. Derives the base path + URLs (and detects user sites). Defaults to the current repo's origin remote when omitted. |
--base </path/> |
Override the base path (e.g. / for a user site or local preview). |
--dir <path> |
Output directory (default: ./<repo-name>). |
--site-name "Title" |
Human title (default: derived from the repo name). |
--description "Text" |
Catalog description (default: derived from the title and repo). |
--author "Name" |
Catalog author (default: repo owner). |
--package-name <id> |
Package identifier (default: repo name). |
--marketplace-id <id> |
Marketplace identifier (default: owner and repo). |
--default-branch <id> |
Repository default branch used by catalog links and deployment triggers (default: main). |
--registry <owner/repo> |
Template registry repo to fetch from (default: jongio/gh-pages-templates; needs git + network). |
--registry-ref <sha> |
Full 40-character commit SHA. Required with a custom registry. Branches and tags are rejected. |
--templates-dir <path> |
Use a local templates/ folder instead of fetching (offline). |
--staging-dir <path> |
Write a validated tree to a new path without applying it to a target. |
--force |
Write into a non-empty directory. |
--json |
Emit a machine-readable result for composition. |
--list |
List available templates. |
Templates are not bundled in the skill. The generator fetches the built-in
jongio/gh-pages-templates registry at a reviewed, immutable commit. A custom
registry requires --registry-ref <full-sha>. Pass --templates-dir <path> to
scaffold from a local copy offline.
Examples:
# Run from the target workspace; SKILL_DIR is this skill's absolute directory.
# Scaffold in place for the current repo (base inferred from its origin remote):
node "$SKILL_DIR/scripts/new-site.mjs" astro --dir . --force
# The workspace is an existing project without git metadata; the slug only supplies
# deployment identity and the base path. Output still goes into the workspace:
node "$SKILL_DIR/scripts/new-site.mjs" astro --repo octocat/blog --dir . --force
# Create a subfolder only when the user explicitly requested one:
node "$SKILL_DIR/scripts/new-site.mjs" react-vite --repo octocat/dashboard --dir ./site
# A user site (served from "/") or a quick local scaffold:
node "$SKILL_DIR/scripts/new-site.mjs" static-html --base / --dir . --force
# Safely compose a skills catalog without touching the consumer's target:
node "$SKILL_DIR/scripts/new-site.mjs" skills-catalog \
--repo octocat/skills \
--templates-dir ../gh-pages-templates/templates \
--staging-dir ./.site-staging \
--json
The generator replaces the shared base and repository sentinels plus the catalog
sentinels __SITE_DESCRIPTION__, __REPO_OWNER__, __REPO_NAME__,
__AUTHOR_NAME__, and __MARKETPLACE_ID__. Injection is deterministic and the
result has no placeholders left. After stamping you may hand-edit content freely.
Metadata values must be plain context-safe text. Markup, control characters, and
characters that can break JSON, YAML, JavaScript, or HTML attributes are rejected.
Safe staging contract
Use --staging-dir whenever create-skills-repo or another tool will merge the
site into a larger output. The path must not exist and the option cannot be
combined with --dir or --force. The generator performs replacement and all
validation inside staging, returns only after success, and never touches the final
target. The consumer must check every destination conflict before copying staged
files.
Before either staging success or normal apply, the generator:
- verifies an external registry checkout matches the requested full commit SHA;
- proves the resolved template path remains inside the registry templates root;
- rejects every symlink in the template tree;
- rejects unresolved
__SENTINEL__placeholders; - scans
.github/workflows/*.ymland.yamlfor excess permissions, unsafe triggers, non-SHA action references, persisted checkout credentials, lifecycle-capable installs without script suppression, and direct GitHub context interpolation in shell commands.
Normal --dir generation uses a private staging directory and applies only after
all checks pass. This preserves existing template and --force behavior while
ensuring an invalid template cannot partially modify the target.
The exact pinned built-in snapshot has a compatibility normalization for its five legacy templates. It upgrades their known action tags to reviewed commit SHAs, disables persisted checkout credentials and lifecycle scripts, and then validates the result. Never apply this normalization to a custom registry.
Digest the repo, then author it (never ship the template defaults)
1. Run the digest
node scripts/digest-repo.mjs --dir <path-to-repo> --json
It returns deterministic signals you build from: name, description (the pitch),
repoSlug, license, a type classification (cli | library | app |
action | collection | docs | site) with the reasons behind it, suggested
install commands, README usageExamples (code fences), badges, docFiles,
existing images (with role hints like logo/hero/screenshot), languages,
and subProjects (for monorepos/collections). Read the repo's README and key docs
yourself too — the digest points you at them; it doesn't replace judgment.
2. Build the right kind of site for the type
| Type | Tell-tale signals | Author the site around… |
|---|---|---|
cli |
bin, console_scripts, [[bin]], --help in README |
Install + Quickstart, then a command/flag reference (a section or page per command), copy-paste examples, config/exit codes. Hero = terminal demo. |
library |
main/exports, [lib], import examples |
Install, an import + usage snippet, an API reference (exported functions/types from the README/docs), examples, badges. Hero = a concept diagram. |
app |
web-framework dep, index.html, src/ |
A feature tour with screenshots, a "Get started"/live-demo CTA. Hero = an app screenshot. |
action |
action.yml |
A uses: snippet, an inputs/outputs table, an example workflow. |
collection |
plugin.json/marketplace.json + skills/, workspaces, packages/ |
A catalog: one card/detail per subProject (its pitch + install), plus a top-level install for the whole thing. Hero = a banner; per-item thumbnails. |
docs |
many Markdown docs, little code | A docs nav + content, pulling the existing Markdown in. |
site / unknown |
none of the above | A clean landing built from the repo's pitch and links. If the shape is unclear, ask the user what sections they want. |
3. Authoring rules
- Replace every default. No template demo copy survives — not the sample hero, not "Hello, Astro/world", not the example blog posts, not lorem. After building, grep the output for the template's stock phrases; none should remain.
- Use real values from the digest: the repo's name and
descriptionas the title/tagline, theinstallcommands verbatim, the READMEusageExamplesas real code blocks,badges,license, and links to the repo and eachsubProject. Don't invent features, commands, or APIs you can't see in the repo — if something's unclear, leave a visibleTODOfor the user rather than fabricate. - Fit the template's content model. Use content collections (Astro/Eleventy:
one entry per command/skill/post), pages (React/static), etc. Add or rename
routes to match the content (e.g. a
commands/orcatalog/section) instead of forcing everything into the demo "blog". Keep the GitHub source link and the base-path-aware internal links the template already wires — never hand-write absolute/...links (use the template's base helper, or it breaks on a project site). - Keep Spectator free-form. Do not force a standard specification outline. Derive pages, headings, and navigation from the supplied context. Preserve the Spectator reading and feedback system, but remove every Project Northstar sample page, label, requirement, source, and image reference.
- Label uncertainty in Spectator. Distinguish verified current behavior, user-approved decisions, proposals, assumptions, risks, and open questions. Do not invent owners, dates, requirements, interfaces, or security claims.
4. Add image placeholders the user can supply
Real sites need art the agent can't produce. Drop in obvious placeholders plus a checklist so the user knows exactly what to provide:
node scripts/make-placeholder.mjs --out <site>/<images-dir> --preset <type> --repo owner/name
--preset is the repo type (cli/library/app/collection/site). It writes
labeled SVG placeholders (logo, social card, favicon, hero, and type-specific
shots) and an IMAGES.md manifest listing each file's purpose and recommended
dimensions. Then:
- Reference them from the pages you author — hero, top-bar logo, the OG/social meta tag, and per-item thumbnails for a catalog.
- Reuse real images first. If the digest found an existing logo or screenshot
(e.g. a
docs/*.png), use it instead of a placeholder. - Put images where the template serves static files:
astro,react-vite→public/images/(served at${BASE_URL}images/…)spectator→docs/public/images/(VitePress applies its configured base)static-html→assets/images/(relative./assets/images/…)eleventy→src/assets/images/(through theurlfilter)jekyll→assets/images/(viarelative_url)
- Leave
IMAGES.mdin the images dir as the hand-off, and tell the user it's there. A placeholder still deploys fine; it just visibly says "replace me".
Ask for real images
After authoring, ask only for images the site references. Give each role, filename,
and recommended dimensions; accept pasted images, file paths, or URLs. Keep
unprovided placeholders, update IMAGES.md, and do not block deployment.
digest-repo.mjs discovers source material; make-placeholder.mjs creates the
placeholder set and handoff manifest.
Per-template notes
- static-html — Zero build. All links are relative, so it's base-path-proof.
Ships
index.html,about.html,404.html,assets/, and a.nojekyll. - astro —
site= origin,base=/repo/. Internal links useimport.meta.env.BASE_URL.public/is copied verbatim. Node 24 in CI by default. - react-vite —
baseinvite.config.js; React Routerbasenamederived fromBASE_URL;copy-404.mjs(apostbuildhook) copiesindex.html→404.htmlso deep-link refreshes work on Pages. Reference public assets as/assetso Vite rewrites them with the base. - eleventy —
pathPrefixcomes from thePATH_PREFIXenv the workflow sets; every link/asset uses theurlfilter. Posts live insrc/posts/, listed viacollections.posts. Locally it serves at/. - jekyll —
baseurl(no trailing slash) in_config.yml; links userelative_url. Built in CI byjekyll-build-pages(honors theGemfile). Local dev needs Ruby + Bundler; CI does not. - spectator: VitePress reads
basefromspectator.config.ts. Content is free-form Markdown underdocs/; navigation is explicit in the shared config. Preserve local search, page outlines, light/dark appearance, plain-language callouts, page feedback, selected-text feedback, and GitHub edit links. Runnpm test,npm run build, andnpm run test:e2e.
Current repo vs. new repo
- Current repo (the default): assume the site is for the repo in context. The
generator infers the base path from its
originremote when you omit--repo. Put the site at the root for a whole-repo site, or in a subfolder and point the workflow'supload-pages-artifactpath:at it. If adeploy.ymlalready exists, reconcile — don't blindly overwrite. - New repo (only when asked): create with
gh repo create, stamp, push tomain. For a user site, the repo MUST be named<user>.github.ioand the base is/— the generator handles the base when you pass that repo name.
Custom domains (documented, not automated)
For a custom domain: add a CNAME file (for static/Jekyll, at the served root;
for Astro, public/CNAME), set DNS at the registrar, and in Astro set site to
the domain and drop base. Don't automate DNS — explain the steps.
Template registry & contributing
Templates live in one place: the
jongio/gh-pages-templates
registry. The skill does not bundle its own copy — the generator fetches
templates from the registry at runtime (override with --registry <owner/repo>, or
scaffold offline from a local checkout with --templates-dir <path>):
node scripts/new-site.mjs astro --repo octocat/blog # pinned default registry
node scripts/new-site.mjs skills-catalog --repo octocat/skills \
--registry octocat/templates --registry-ref 0123456789abcdef0123456789abcdef01234567
node scripts/new-site.mjs astro --templates-dir ../gh-pages-templates/templates
Each template is a folder with a template.json manifest, a deploy workflow,
base-path handling via the sentinels, and a README.md. The registry also renders
the browsable gallery (live previews of every template) at
https://jongio.github.io/gh-pages-templates/ — the single home for browsing and
previewing. Point users there to browse, and to the registry's CONTRIBUTING.md to
submit a new template. Template changes (add/fix a template, bump an action version)
land in the registry, not here.
Validate — don't claim done on a green check
- Content check first. Confirm the site is about the repo, not the template:
the title/tagline, install commands, and examples are the repo's real values, and
no template demo copy survives (grep the built output for the template's stock
phrases — "Hello", "islands", "lorem", the sample post titles — and for leftover
__…__sentinels). The page kind matches the repo type (CLI ref / API ref / feature tour / catalog). Image placeholders exist andIMAGES.mdis present. - Build it. For
astro/react-vite/eleventy/spectator, runnpm ci --ignore-scripts --no-audit --no-fundthennpm run buildand confirm both exit 0 and emit the output dir (dist/_site). Forjekyll,bundle exec jekyll buildif Ruby is present. - Check the base path. Open the built output and confirm asset/link URLs carry
the project prefix (
/repo/...) — not bare/.... This is the failure mode that "looks deployed but renders blank." - After deploy, load the live
page_urlfrom the Actions run; click an internal link and (for the SPA) refresh a sub-route to confirm the404.htmlfallback works. - Only then report it as working.
Run the skill's own tests with npm test (the generator + the repo-digest and
placeholder checks, offline via a fixture). Template/workflow validation lives in
the jongio/gh-pages-templates registry.
Footguns
- Never ship a project site built for
/— assets 404. Set the base path (the generator does this; verify it). - Never put a subpath base on a user site (
<user>.github.io) — it must be/(Jekyll:baseurl: ""). - Never use
actions/upload-artifactfor Pages — it'supload-pages-artifact. - Never reach for
peaceiris/actions-gh-pagesor agh-pagesbranch — use the first-party Actions flow these templates ship. - Never forget to set Source → GitHub Actions in Settings → Pages; the workflow can't publish until Pages is enabled for Actions.
- Don't leave the repo "Website" link blank — set
homepageto the Pages URL (gh repo edit --homepage) so visitors find the site; it's the same as the "Use your GitHub Pages website" checkbox. - Never claim success because the workflow is green — load the URL and check an asset and an internal link actually resolve.
- Never ship the template's demo content. A stamped template that still says "Hello, Astro", lists sample blog posts, or contains Project Northstar is a failure. Digest the repo and author real content of the right kind.
- Never fabricate features, commands, or APIs to fill the page. Author only what
the repo actually shows; leave a visible
TODOwhen unsure. - Don't leave bare image references with nothing behind them — add the placeholders +
IMAGES.md, or reuse the repo's existing images. - Don't ship placeholders silently — tell the user which real images the site needs and that they can paste a screenshot into the chat to fill each one.
- Don't hand-roll a base-path setup when the generator + sentinels already do it correctly per framework.
- Never pass a branch or tag as
--registry-ref. Only a full commit SHA is immutable enough to validate. - Never compose directly into another generator's target. Stage first, check conflicts, then merge.
Files (skills)
-
evals
-
create-gh-pages-site
-
fixtures
-
astro-cli
-
package.json 153 B
Loading… -
README.md 154 B
Loading…
-
-
skills-catalog
-
deploy.yml 392 B
Loading… -
index.html 435 B · in bundle
-
template.json 152 B
Loading…
-
-
skills-repo
-
alpha-skill.md 82 B
Loading… -
do-not-overwrite.txt 15 B
Loading… -
README.md 53 B
Loading…
-
-
spectator
-
.github
-
workflows
-
deploy.yml 1.1 KB
Loading…
-
-
-
docs
-
.vitepress
-
theme
-
FeedbackPrompt.vue 111 B · in bundle
-
index.ts 391 B
Loading… -
SelectionActions.vue 352 B · in bundle
-
-
config.mts 219 B · in bundle
-
-
index.md 137 B
Loading… -
proposal.md 155 B
Loading… -
system-shape.md 148 B
Loading…
-
-
package.json 136 B
Loading… -
spectator.config.ts 146 B
Loading… -
template.json 135 B
Loading…
-
-
spectator-repo
-
proposal-notes.md 413 B
Loading… -
README.md 330 B
Loading…
-
-
static-library
-
package.json 150 B
Loading… -
README.md 208 B
Loading…
-
-
-
eval.yaml 19.6 KB
Loading…
-
-
README.md 2 KB
Loading…
-
-
scripts
-
digest-repo.mjs 17.6 KB · in bundle
-
install-local.ps1 1.2 KB · in bundle
-
make-placeholder.mjs 7.8 KB · in bundle
-
new-site-cli.mjs 6.4 KB · in bundle
-
new-site.mjs 17.8 KB · in bundle
-
template-registry.mjs 4.4 KB · in bundle
-
template-security.mjs 20.3 KB · in bundle
-
-
test
-
digest.test.mjs 8.7 KB · in bundle
-
generator.test.mjs 32.2 KB · in bundle
-
-
.gitignore 345 B · in bundle
-
.npmrc 18 B · in bundle
-
.vally.yaml 672 B
Loading… -
CONTRIBUTING.md 4 KB
Loading… -
LICENSE 1 KB · in bundle
-
package-lock.json 108.1 KB
Loading… -
package.json 840 B
Loading… -
README.md 10.2 KB
# create-gh-pages-site Scaffold a working **GitHub Pages** website from a vetted template and wire it to deploy automatically — packaged as a GitHub Copilot skill. Pick a template (static, Astro, React + Vite, Eleventy, Jekyll, or skills catalog); the skill injects the correct **base path** for your repo, adds the current official GitHub Actions Pages workflow, drops it into your repo (the **current repo by default**, or a new one), and tells you how to turn Pages on. It doesn't stop at the template's demo content, either: it **digests your repo** (README, manifests, entry points, docs) and authors a site that's actually about your project — a CLI reference, an API/usage page, a feature tour, or a catalog of parts — and drops in labeled image placeholders you swap for real art. ## Quickstart **1. Install the skill**: ```sh npx skills add jongio/skills --skill create-gh-pages-site ``` **2. Reload skills** — run `/skills reload`, or start a new session. **3. Ask Copilot to build a site:** ```text /create-gh-pages-site put this repo on GitHub Pages as an Astro blog ``` By default the agent scaffolds for the **repo you're in** — it reads the current repo from git, picks the `astro` template, sets `site`/`base` for it, lays down the deploy workflow, and shows you how to enable Pages. Name a different repo (`octocat/blog`) only when you want one. ## Why this exists GitHub Pages' hard parts aren't the HTML — they're the deploy plumbing and the **base-path trap**: a project site lives at `https://USER.github.io/REPO/`, so a site built for `/` ships with broken assets and links. Every framework fixes this differently (Astro `base`, Vite `base` + `404.html`, Eleventy `pathPrefix`, Jekyll `baseurl`). This skill gets all of it right, every time. ## Templates | Template | Use it for | Base path | Build | | --- | --- | --- | --- | | `static-html` | landing pages, a few hand-made pages | relative URLs (immune) | none | | `astro` | content sites, blogs, docs, marketing | `base` in `astro.config.mjs` | `astro build` | | `react-vite` | interactive SPAs / dashboards | `base` + `404.html` fallback | `vite build` | | `eleventy` | data/Markdown-driven sites | `pathPrefix` via env + `url` filter | `eleventy` | | `jekyll` | GitHub-native / existing Jekyll | `baseurl` in `_config.yml` | Jekyll | | `skills-catalog` | browsable catalogs for Copilot skills repositories | template base helper | registry-defined | The built-in registry pin includes `skills-catalog`. Custom registries require a full `--registry-ref`, and local checkouts use `--templates-dir`. All templates deploy via the **GitHub Actions** Pages source. Every external action must be pinned to a full commit SHA, checkout must disable persisted credentials, and install steps must disable lifecycle scripts. No `gh-pages` branch is used. Workflow scanning accepts a conservative block-style YAML subset and rejects quoted keys, tags, anchors, aliases, merge keys, and unsupported flow mappings. Browse them in the live [gallery with previews](https://jongio.github.io/gh-pages-templates/), hosted from the [`jongio/gh-pages-templates`](https://github.com/jongio/gh-pages-templates) registry. ## Tailored to your repo, not a demo A stamped template is a skeleton, not the deliverable. After stamping, the skill reads your repo and rewrites the content to match it: - **`scripts/digest-repo.mjs`** analyzes the repo and classifies it — `cli`, `library`, `app`, `action`, `collection`, `docs`, or `site` — and pulls out the name, pitch, install commands, README usage examples, badges, docs, existing images, and sub-projects. That drives *which* kind of site gets built: a command reference for a CLI, an API/usage page for a library, a feature tour for an app, a catalog for a monorepo. - **`scripts/make-placeholder.mjs`** drops labeled placeholder images (logo, social card, hero, screenshots) into the site plus an `IMAGES.md` checklist telling you what to supply and at what size. Real images the repo already has are reused instead. ```sh node scripts/digest-repo.mjs --dir . --json # see what the author sees node scripts/make-placeholder.mjs --out site/public/images --preset cli --repo octocat/mytool ``` ## Use it Once installed, describe the site you want: ```text /create-gh-pages-site a docs site with Eleventy in a new repo called octocat/docs ``` ```text /create-gh-pages-site put this folder of HTML on Pages ``` You don't have to name the skill — the agent routes to it whenever you ask to create or publish a GitHub Pages site. ## Build it yourself (no agent) The generator stamps the same site the skill uses. Templates are fetched from the [`jongio/gh-pages-templates`](https://github.com/jongio/gh-pages-templates) registry at an immutable commit, so it needs git + network unless you pass `--templates-dir`. The built-in registry uses a reviewed pinned commit. A custom registry requires `--registry-ref` with its full 40-character commit SHA: Free-form metadata is limited to context-safe text because the same sentinel can appear in HTML, JSON, YAML, and JavaScript. Markup, control characters, and context-breaking quotes are rejected instead of being copied into generated code. ```sh # Scaffold for the CURRENT repo (base path read from its origin remote): node scripts/new-site.mjs astro # An Astro site for a specific project repo (base = /blog/): node scripts/new-site.mjs astro --repo octocat/blog --site-name "Octocat's Blog" # A React SPA: node scripts/new-site.mjs react-vite --repo octocat/dashboard # A user site (served from "/") or a quick local scaffold: node scripts/new-site.mjs static-html --base / --dir ./site # Offline, from a local registry checkout: node scripts/new-site.mjs astro --templates-dir ../gh-pages-templates/templates # A custom registry is always commit-pinned: node scripts/new-site.mjs skills-catalog --repo octocat/skills \ --author "Octo Cat" --marketplace-id octocat-skills --default-branch trunk \ --registry octocat/templates --registry-ref 0123456789abcdef0123456789abcdef01234567 # List templates: node scripts/new-site.mjs --list ``` ## Safe staging for composition `create-skills-repo` and other generators should stage the site instead of writing into their target: ```sh node scripts/new-site.mjs skills-catalog \ --repo octocat/skills \ --templates-dir ../gh-pages-templates/templates \ --staging-dir ./.site-staging \ --json ``` The staging contract is fail-closed: 1. `--staging-dir` must name a path that does not exist. 2. It cannot be combined with `--dir` or `--force`. 3. The generator copies and substitutes the template only in that directory. 4. It validates paths, symlinks, sentinels, and workflows before returning success. 5. It never reads or writes the consumer's final target. The consumer owns conflict detection and the final merge. 6. `--json` returns `mode`, `directory`, `template`, registry identity, and replacements so callers do not need to parse console prose. Normal generation uses the same staging and validation pipeline internally, then applies the validated tree to `--dir`. Existing `--force` behavior remains available only for this explicit apply mode. Earlier generator versions skipped symbolic links during rewriting. Current versions reject every symbolic link before staging because templates can come from an external registry. The pinned built-in snapshot already uses immutable action commits. Compatibility normalization remains restricted to that exact reviewed snapshot, rewrites only known legacy forms, and always runs the same validator afterward. Custom registries receive no migration and fail closed. Then push to `main` and set **Settings → Pages → Source → GitHub Actions**. The workflow publishes on every push; the live URL appears in the Actions run. Point the repo's "Website" link at it with `gh repo edit OWNER/REPO --homepage <site-url>` (the same as checking *"Use your GitHub Pages website"*). ## Install options ```sh # Into the current project (.agents/skills/create-gh-pages-site/): npx skills add jongio/skills --skill create-gh-pages-site # Pin to a branch or tag: npx skills add jongio/skills#main --skill create-gh-pages-site ``` **Copilot plugin marketplace:** ```sh copilot plugin marketplace add jongio/skills copilot plugin install create-gh-pages-site@jongio-skills ``` **Local install (no network):** ```sh pwsh -File scripts/install-local.ps1 ``` After any install, reload skills with `/skills reload` or a new session. ## A contributable registry Templates live **only** in the [`jongio/gh-pages-templates`](https://github.com/jongio/gh-pages-templates) registry with each template in a folder containing a `template.json` manifest. The generator fetches the built-in registry at a pinned commit. Override it with both `--registry owner/repo` and `--registry-ref <full-sha>`, or scaffold offline with `--templates-dir <path>`. The browsable gallery + live previews are hosted from the registry too. Adding or fixing a template is a PR to that repo — see its `CONTRIBUTING.md`. This skill owns the generator + the agent workflow, not the templates. ## Run the tests ```sh npm test # node test/generator.test.mjs && node test/digest.test.mjs ``` No dependencies are needed. The tests run on bare `node` (18+) and never use the network. They exercise base-path math, skills-catalog discovery, immutable local registry checkout, staging, traversal and symlink rejection, sentinel validation, workflow policy, repo digestion, and placeholder generation. ## Layout ```text SKILL.md The skill (authoring contract + workflow) scripts/ new-site.mjs Generator: fetch, stage, validate, and apply a template new-site-cli.mjs Command-line parsing and machine-readable output template-registry.mjs Immutable registry checkout and verification template-security.mjs Path, symlink, sentinel, and workflow validation digest-repo.mjs Analyze a repo → JSON signals + type classification make-placeholder.mjs Generate placeholder images + an IMAGES.md checklist install-local.ps1 Install this skill into $COPILOT_HOME/skills test/ Generator and digest tests (bare node, offline fixture) ``` ## License MIT — see [LICENSE](./LICENSE). -
SKILL.md 28.8 KB
--- name: create-gh-pages-site description: >- Scaffold a working GitHub Pages website from a vetted template and wire it to deploy automatically. Use when the user wants to create, scaffold, or publish a site on GitHub Pages: a reviewable VitePress specification, a static page, an Astro or Eleventy site, a React (Vite) SPA, or a Jekyll site. Picks the right template, injects the correct base path for the target repo (the #1 thing people get wrong), adds the official GitHub Actions Pages deploy workflow, and sets it up in the user's current repo by default or a new one if asked. Does not stop at demo content: it digests the target repo (README, manifests, entry points, docs) and authors a site about that repo (CLI reference, API/usage page, feature tour, or catalog) with labeled image placeholders the user swaps in. Do NOT use for non-Pages hosting (Vercel/Netlify/Azure), deploying an existing app without a Pages target, or plain web pages unrelated to GitHub Pages. metadata: version: "1.1.0" --- # Create GitHub Pages Site Scaffold a vetted Pages template with the correct base path and deployment workflow. Replace demo content with repo-derived content. ## When to use which template Pick by what the user is building. If unsure, ask one question (content vs. app) and default to `static-html` for the simplest ask. | Template | Reach for it when… | Tier | Build | | --- | --- | --- | --- | | `static-html` | A landing page, a few hand-made pages, "just put this HTML up". No toolchain. | static | none | | `astro` | A content site, blog, docs, or marketing page that should be fast and mostly static. | SSG | `astro build` | | `react-vite` | An interactive single-page app / dashboard with client-side routing. | SPA | `vite build` | | `eleventy` | A data/Markdown-driven site (blog, docs) where content is files + structured data. | data SSG | `eleventy` | | `jekyll` | The user wants the GitHub-native path, or is migrating an existing Jekyll site. | native | Jekyll | | `skills-catalog` | A browsable catalog for a repository of Copilot skills, especially when composing `create-skills-repo`. | catalog | registry-defined | | `spectator` | A technical specification, RFC, architecture proposal, design proposal, engineering decision, or policy proposal built for structured review. | SSG | `vitepress build docs` | The built-in registry pin must include the selected template. A custom registry requires an explicit `--registry-ref`, and a local checkout uses `--templates-dir`. These seven cover the static / SSG / SPA / data / native / catalog / specification quadrants. For richer *themes*, point the user at upstream galleries (astro.build/themes, jamstackthemes.dev, github.com/topics/github-pages-template) and adapt — don't try to hand-build a theme from scratch. ## The base-path trap (the thing to get right) A GitHub **project** site is served from a subpath: `https://<user>.github.io/<repo>/`. A site built assuming root (`/`) ships with broken CSS, images, and links the moment it's a project site — assets 404 and the page looks blank. A **user/org** site (`<user>.github.io` repo) *is* served from `/`, so it must NOT carry a subpath prefix. Each framework fixes this differently. The generator handles all of it from the repo name; you rarely set it by hand: | Template | Mechanism | Project value | User-site value | | --- | --- | --- | --- | | `static-html` | relative URLs (`./assets/...`) | — (immune) | — (immune) | | `astro` | `base` in `astro.config.mjs` | `/repo/` | `/` | | `react-vite` | `base` in `vite.config.js` + `basename` + `404.html` | `/repo/` | `/` | | `eleventy` | `pathPrefix` via `PATH_PREFIX` env + `url` filter | `/repo/` | `/` | | `jekyll` | `baseurl` in `_config.yml` + `relative_url` | `/repo` (no slash) | `""` (empty) | | `spectator` | `base` in `spectator.config.ts` and VitePress config | `/repo/` | `/` | **The generator detects the `<user>.github.io` user-site pattern and uses `/` automatically.** If the user hasn't named the repo yet, scaffold with the repo they intend; if they truly don't know, use `--base /` and tell them to re-run (or edit the base) once the repo exists. ## Deployment model — one consistent flow Every template deploys via the **GitHub Actions** Pages source, not from a branch. Every external action reference must use a full commit SHA. - `static-html`, `react-vite`, `eleventy` use that chain directly. - `astro` uses the official `withastro/action@v6` (it builds + produces the Pages artifact) then `actions/deploy-pages@v5`. - `jekyll` uses GitHub's official `actions/jekyll-build-pages@v1` then `deploy-pages`. Every workflow limits top-level permissions to `contents: read`, grants Pages and identity-token access only to the jobs that need them, uses one Pages concurrency group, and deploys through the `github-pages` environment. There is **no `gh-pages` branch** to manage. > Action versions deprecate aggressively. Update the template registry to a reviewed > action commit, then bump this skill's immutable default registry commit. ## Interview first — never scaffold on a guess This skill produces a real repo with a live deploy pipeline, so getting the inputs right matters more than speed. **Do not stamp anything until you know (a) which template and (b) the target repo (or an explicit base path).** If the prompt is bare ("make me a GitHub Pages site") or names no framework/repo, interview the user — ask only for what's missing, one focused question at a time, using the `ask_user` tool: 1. **What kind of site?** Map the answer to a template: - "a landing page / just some HTML / the simplest thing" → `static-html` - "a blog / docs / content / marketing site, fast" → `astro` (or `eleventy` if they say Markdown- or data-driven, or `jekyll` if they want the GitHub-native path or are migrating an existing Jekyll site) - "an app / dashboard / interactive / single-page app" → `react-vite` - "a catalog of Copilot skills / create a skills repo" → `skills-catalog` - "a specification / RFC / architecture or design proposal / engineering decision / policy proposal / site like the Eval Authoring Guide" → `spectator` If they're unsure, ask the single discriminating question — *content site or interactive app?* — and default to `static-html` for the simplest ask. 2. **Which repo? Assume the current repo by default.** The site is for the repo in context unless the user says otherwise — don't ask "current or new." Detect the current repo from git (`git remote get-url origin`, parsed to `owner/name`); the generator does the same automatically when you omit `--repo`. The repo drives the base path, so you must resolve it before stamping: - **Current repo detected** → use it. State the assumption in one line (*"Scaffolding into this repo, octocat/blog → base `/blog/`"*) and proceed; no question needed. - **No git context, detached, or no `origin`** → then ask for the `owner/name`, and whether it's an existing repo or a **new** one to create. - Only treat it as a **new/different** repo when the user explicitly asks for one. For a user site, confirm the repo is named `<user>.github.io` (base `/`); otherwise it's a project site (base `/repo/`). 3. **Title?** Optional — default to the repo name; never block on it. You usually don't need to ask "what should the site say?" — the **content comes from the repo** (you digest it after stamping; see "Digest the repo, then author it"). When the target repo is the current/an existing one, run `digest-repo.mjs` early to confirm the type and let it inform the template choice (e.g. a `cli` repo is a great fit for `astro` or `static-html` with a command reference). If the repo is empty or brand-new, fall back to asking what the site should cover. Skip any question the prompt already answered: *"an Astro blog for octocat/blog"* needs no interview (template `astro`, repo `octocat/blog`). For a bare *"put this on Pages"* inside a repo, assume the current repo and ask only for the template. Ask only for the gaps. When you **inferred** rather than were told, confirm in one line before scaffolding — e.g. *"Astro site → octocat/blog (current repo), base `/blog/` — go?"* ## Output location invariant **The user's current working directory is the destination workspace.** A repo slug such as `octocat/blog` determines the Pages base path and URLs; it does not mean the site belongs in `/tmp/blog`, a sibling directory, or the skill's own directory. - If the workspace already contains repo files, scaffold in place with `--dir . --force`, even when it is not a git checkout and the prompt supplies the repo slug explicitly. - Never `cd` into the skill directory to run the generator. Invoke `scripts/new-site.mjs` by its absolute path while keeping the workspace as the process working directory. - Use another output directory only when the user explicitly asks for a subfolder or a new/different repo. - When another generator is composing the result, use `--staging-dir` instead of `--dir`. The staging directory is isolated and the consumer owns the final merge. - Before reporting completion, confirm the generated config, content, and `.github/workflows` files exist under the original working directory. ## The workflow you follow 1. **Interview / gather context.** Resolve the questions above via `ask_user`. You MUST end up with a chosen template and a target repo (or explicit `--base`) before stamping. **Default the target to the current repo** (detect it from `git remote get-url origin`); only ask when there's no git context or the user wants a different/new repo. 2. **Pick the template** from the table above. 3. **Stamp it** with the generator (next section). This injects the base path, site URL, and title, and lays down the deploy workflow. 4. **Place it in the repo:** - *Current repo (default)*: stamp into the repo root (or a subfolder if it's a subdirectory site, adjusting the workflow's upload path). From the original working directory, invoke the generator by absolute path and pass `--dir .` `--force` to write in place. Reconcile an existing `deploy.yml` rather than blindly overwriting it. - *New repo (only when asked)*: create it (e.g. `gh repo create <name> --public`), stamp into it, and push. Match the repo name you used for the base path. 5. **Digest the repo and author the site** (see "Digest the repo, then author it" below). This is the step that makes the site *real*: run the digest, replace every default page/section with repo-derived content of the right kind, add image placeholders + an `IMAGES.md`, and **prompt the user for the real images** (they can paste screenshots straight into the chat). Never skip to enabling Pages on the demo content. 6. **Enable Pages.** Tell the user (or do it with their approval): **Settings → Pages → Source → GitHub Actions**. By CLI: `gh api -X POST repos/<owner>/<repo>/pages -f build_type=workflow` (or PUT to update). After the first push to `main`, the workflow runs and the live URL appears in the Actions run summary and under Settings → Pages. 7. **Set the repo website link** to the Pages URL (the "Website" field in the repo header — same as ticking *Settings → "Use your GitHub Pages website"*). This is just the repo's `homepage`; point it at the site URL the generator prints: `gh repo edit <owner>/<repo> --homepage <site-url>` (or `gh api -X PATCH repos/<owner>/<repo> -f homepage=<site-url>`). Offer to set the exact URL, or let the user supply a custom domain instead. There's no separate "use Pages" boolean — setting `homepage` to the Pages URL *is* the checkbox. 8. **Verify it actually works** (see "Validate" below) — don't claim success on a green workflow alone, and don't claim success while template default copy or "Hello, world" demo content is still on the page. ## Stamp a site — the generator ```sh node scripts/new-site.mjs <template> --repo <owner/name> [options] ``` | Option | Purpose | | --- | --- | | `--repo <owner/name>` | Target repo. Derives the base path + URLs (and detects user sites). **Defaults to the current repo's `origin` remote when omitted.** | | `--base </path/>` | Override the base path (e.g. `/` for a user site or local preview). | | `--dir <path>` | Output directory (default: `./<repo-name>`). | | `--site-name "Title"` | Human title (default: derived from the repo name). | | `--description "Text"` | Catalog description (default: derived from the title and repo). | | `--author "Name"` | Catalog author (default: repo owner). | | `--package-name <id>` | Package identifier (default: repo name). | | `--marketplace-id <id>` | Marketplace identifier (default: owner and repo). | | `--default-branch <id>` | Repository default branch used by catalog links and deployment triggers (default: `main`). | | `--registry <owner/repo>` | Template registry repo to fetch from (default: `jongio/gh-pages-templates`; needs git + network). | | `--registry-ref <sha>` | Full 40-character commit SHA. Required with a custom registry. Branches and tags are rejected. | | `--templates-dir <path>` | Use a local `templates/` folder instead of fetching (offline). | | `--staging-dir <path>` | Write a validated tree to a new path without applying it to a target. | | `--force` | Write into a non-empty directory. | | `--json` | Emit a machine-readable result for composition. | | `--list` | List available templates. | Templates are **not bundled in the skill**. The generator fetches the built-in `jongio/gh-pages-templates` registry at a reviewed, immutable commit. A custom registry requires `--registry-ref <full-sha>`. Pass `--templates-dir <path>` to scaffold from a local copy offline. Examples: ```sh # Run from the target workspace; SKILL_DIR is this skill's absolute directory. # Scaffold in place for the current repo (base inferred from its origin remote): node "$SKILL_DIR/scripts/new-site.mjs" astro --dir . --force # The workspace is an existing project without git metadata; the slug only supplies # deployment identity and the base path. Output still goes into the workspace: node "$SKILL_DIR/scripts/new-site.mjs" astro --repo octocat/blog --dir . --force # Create a subfolder only when the user explicitly requested one: node "$SKILL_DIR/scripts/new-site.mjs" react-vite --repo octocat/dashboard --dir ./site # A user site (served from "/") or a quick local scaffold: node "$SKILL_DIR/scripts/new-site.mjs" static-html --base / --dir . --force # Safely compose a skills catalog without touching the consumer's target: node "$SKILL_DIR/scripts/new-site.mjs" skills-catalog \ --repo octocat/skills \ --templates-dir ../gh-pages-templates/templates \ --staging-dir ./.site-staging \ --json ``` The generator replaces the shared base and repository sentinels plus the catalog sentinels `__SITE_DESCRIPTION__`, `__REPO_OWNER__`, `__REPO_NAME__`, `__AUTHOR_NAME__`, and `__MARKETPLACE_ID__`. Injection is deterministic and the result has no placeholders left. After stamping you may hand-edit content freely. Metadata values must be plain context-safe text. Markup, control characters, and characters that can break JSON, YAML, JavaScript, or HTML attributes are rejected. ### Safe staging contract Use `--staging-dir` whenever `create-skills-repo` or another tool will merge the site into a larger output. The path must not exist and the option cannot be combined with `--dir` or `--force`. The generator performs replacement and all validation inside staging, returns only after success, and never touches the final target. The consumer must check every destination conflict before copying staged files. Before either staging success or normal apply, the generator: 1. verifies an external registry checkout matches the requested full commit SHA; 2. proves the resolved template path remains inside the registry templates root; 3. rejects every symlink in the template tree; 4. rejects unresolved `__SENTINEL__` placeholders; 5. scans `.github/workflows/*.yml` and `.yaml` for excess permissions, unsafe triggers, non-SHA action references, persisted checkout credentials, lifecycle-capable installs without script suppression, and direct GitHub context interpolation in shell commands. Normal `--dir` generation uses a private staging directory and applies only after all checks pass. This preserves existing template and `--force` behavior while ensuring an invalid template cannot partially modify the target. The exact pinned built-in snapshot has a compatibility normalization for its five legacy templates. It upgrades their known action tags to reviewed commit SHAs, disables persisted checkout credentials and lifecycle scripts, and then validates the result. Never apply this normalization to a custom registry. ## Digest the repo, then author it (never ship the template defaults) ### 1. Run the digest ```sh node scripts/digest-repo.mjs --dir <path-to-repo> --json ``` It returns deterministic signals you build from: `name`, `description` (the pitch), `repoSlug`, `license`, a `type` classification (`cli` | `library` | `app` | `action` | `collection` | `docs` | `site`) with the reasons behind it, suggested `install` commands, README `usageExamples` (code fences), `badges`, `docFiles`, existing `images` (with role hints like `logo`/`hero`/`screenshot`), `languages`, and `subProjects` (for monorepos/collections). Read the repo's README and key docs yourself too — the digest points you at them; it doesn't replace judgment. ### 2. Build the right *kind* of site for the type | Type | Tell-tale signals | Author the site around… | | --- | --- | --- | | `cli` | `bin`, console_scripts, `[[bin]]`, `--help` in README | Install + Quickstart, then a **command/flag reference** (a section or page per command), copy-paste examples, config/exit codes. Hero = terminal demo. | | `library` | `main`/`exports`, `[lib]`, import examples | Install, an **import + usage** snippet, an **API reference** (exported functions/types from the README/docs), examples, badges. Hero = a concept diagram. | | `app` | web-framework dep, `index.html`, `src/` | A **feature tour** with screenshots, a "Get started"/live-demo CTA. Hero = an app screenshot. | | `action` | `action.yml` | A `uses:` snippet, an **inputs/outputs table**, an example workflow. | | `collection` | `plugin.json`/`marketplace.json` + `skills/`, workspaces, `packages/` | A **catalog**: one card/detail per `subProject` (its pitch + install), plus a top-level install for the whole thing. Hero = a banner; per-item thumbnails. | | `docs` | many Markdown docs, little code | A **docs nav + content**, pulling the existing Markdown in. | | `site` / unknown | none of the above | A clean landing built from the repo's pitch and links. If the shape is unclear, ask the user what sections they want. | ### 3. Authoring rules - **Replace every default.** No template demo copy survives — not the sample hero, not "Hello, Astro/world", not the example blog posts, not lorem. After building, grep the output for the template's stock phrases; none should remain. - **Use real values from the digest:** the repo's name and `description` as the title/tagline, the `install` commands verbatim, the README `usageExamples` as real code blocks, `badges`, `license`, and links to the repo and each `subProject`. **Don't invent** features, commands, or APIs you can't see in the repo — if something's unclear, leave a visible `TODO` for the user rather than fabricate. - **Fit the template's content model.** Use content collections (Astro/Eleventy: one entry per command/skill/post), pages (React/static), etc. Add or rename routes to match the content (e.g. a `commands/` or `catalog/` section) instead of forcing everything into the demo "blog". Keep the GitHub source link and the base-path-aware internal links the template already wires — never hand-write absolute `/...` links (use the template's base helper, or it breaks on a project site). - **Keep Spectator free-form.** Do not force a standard specification outline. Derive pages, headings, and navigation from the supplied context. Preserve the Spectator reading and feedback system, but remove every Project Northstar sample page, label, requirement, source, and image reference. - **Label uncertainty in Spectator.** Distinguish verified current behavior, user-approved decisions, proposals, assumptions, risks, and open questions. Do not invent owners, dates, requirements, interfaces, or security claims. ### 4. Add image placeholders the user can supply Real sites need art the agent can't produce. Drop in **obvious placeholders** plus a checklist so the user knows exactly what to provide: ```sh node scripts/make-placeholder.mjs --out <site>/<images-dir> --preset <type> --repo owner/name ``` `--preset` is the repo type (`cli`/`library`/`app`/`collection`/`site`). It writes labeled SVG placeholders (logo, social card, favicon, hero, and type-specific shots) and an `IMAGES.md` manifest listing each file's purpose and recommended dimensions. Then: - **Reference them** from the pages you author — hero, top-bar logo, the OG/social meta tag, and per-item thumbnails for a catalog. - **Reuse real images first.** If the digest found an existing logo or screenshot (e.g. a `docs/*.png`), use it instead of a placeholder. - **Put images where the template serves static files:** - `astro`, `react-vite` → `public/images/` (served at `${BASE_URL}images/…`) - `spectator` → `docs/public/images/` (VitePress applies its configured base) - `static-html` → `assets/images/` (relative `./assets/images/…`) - `eleventy` → `src/assets/images/` (through the `url` filter) - `jekyll` → `assets/images/` (via `relative_url`) - **Leave `IMAGES.md` in the images dir** as the hand-off, and tell the user it's there. A placeholder still deploys fine; it just visibly says "replace me". ### Ask for real images After authoring, ask only for images the site references. Give each role, filename, and recommended dimensions; accept pasted images, file paths, or URLs. Keep unprovided placeholders, update `IMAGES.md`, and do not block deployment. `digest-repo.mjs` discovers source material; `make-placeholder.mjs` creates the placeholder set and handoff manifest. ## Per-template notes - **static-html** — Zero build. All links are relative, so it's base-path-proof. Ships `index.html`, `about.html`, `404.html`, `assets/`, and a `.nojekyll`. - **astro** — `site` = origin, `base` = `/repo/`. Internal links use `import.meta.env.BASE_URL`. `public/` is copied verbatim. Node 24 in CI by default. - **react-vite** — `base` in `vite.config.js`; React Router `basename` derived from `BASE_URL`; `copy-404.mjs` (a `postbuild` hook) copies `index.html` → `404.html` so deep-link refreshes work on Pages. Reference public assets as `/asset` so Vite rewrites them with the base. - **eleventy** — `pathPrefix` comes from the `PATH_PREFIX` env the workflow sets; every link/asset uses the `url` filter. Posts live in `src/posts/`, listed via `collections.posts`. Locally it serves at `/`. - **jekyll** — `baseurl` (no trailing slash) in `_config.yml`; links use `relative_url`. Built in CI by `jekyll-build-pages` (honors the `Gemfile`). Local dev needs Ruby + Bundler; CI does not. - **spectator**: VitePress reads `base` from `spectator.config.ts`. Content is free-form Markdown under `docs/`; navigation is explicit in the shared config. Preserve local search, page outlines, light/dark appearance, plain-language callouts, page feedback, selected-text feedback, and GitHub edit links. Run `npm test`, `npm run build`, and `npm run test:e2e`. ## Current repo vs. new repo - **Current repo (the default)**: assume the site is for the repo in context. The generator infers the base path from its `origin` remote when you omit `--repo`. Put the site at the root for a whole-repo site, or in a subfolder and point the workflow's `upload-pages-artifact` `path:` at it. If a `deploy.yml` already exists, reconcile — don't blindly overwrite. - **New repo (only when asked)**: create with `gh repo create`, stamp, push to `main`. For a **user site**, the repo MUST be named `<user>.github.io` and the base is `/` — the generator handles the base when you pass that repo name. ## Custom domains (documented, not automated) For a custom domain: add a `CNAME` file (for static/Jekyll, at the served root; for Astro, `public/CNAME`), set DNS at the registrar, and in Astro set `site` to the domain and drop `base`. Don't automate DNS — explain the steps. ## Template registry & contributing Templates live in **one** place: the **[`jongio/gh-pages-templates`](https://github.com/jongio/gh-pages-templates)** registry. The skill does **not** bundle its own copy — the generator fetches templates from the registry at runtime (override with `--registry <owner/repo>`, or scaffold offline from a local checkout with `--templates-dir <path>`): ```sh node scripts/new-site.mjs astro --repo octocat/blog # pinned default registry node scripts/new-site.mjs skills-catalog --repo octocat/skills \ --registry octocat/templates --registry-ref 0123456789abcdef0123456789abcdef01234567 node scripts/new-site.mjs astro --templates-dir ../gh-pages-templates/templates ``` Each template is a folder with a `template.json` manifest, a deploy workflow, base-path handling via the sentinels, and a `README.md`. The registry also renders the browsable gallery (live previews of every template) at **https://jongio.github.io/gh-pages-templates/** — the single home for browsing and previewing. Point users there to browse, and to the registry's `CONTRIBUTING.md` to submit a new template. Template changes (add/fix a template, bump an action version) land in the registry, not here. ## Validate — don't claim done on a green check 1. **Content check first.** Confirm the site is about the repo, not the template: the title/tagline, install commands, and examples are the repo's real values, and **no template demo copy survives** (grep the built output for the template's stock phrases — "Hello", "islands", "lorem", the sample post titles — and for leftover `__…__` sentinels). The page kind matches the repo type (CLI ref / API ref / feature tour / catalog). Image placeholders exist and `IMAGES.md` is present. 2. **Build it.** For `astro`/`react-vite`/`eleventy`/`spectator`, run `npm ci --ignore-scripts --no-audit --no-fund` then `npm run build` and confirm both exit 0 and emit the output dir (`dist` / `_site`). For `jekyll`, `bundle exec jekyll build` if Ruby is present. 3. **Check the base path.** Open the built output and confirm asset/link URLs carry the project prefix (`/repo/...`) — not bare `/...`. This is the failure mode that "looks deployed but renders blank." 4. **After deploy**, load the live `page_url` from the Actions run; click an internal link and (for the SPA) refresh a sub-route to confirm the `404.html` fallback works. 5. Only then report it as working. Run the skill's own tests with `npm test` (the generator + the repo-digest and placeholder checks, offline via a fixture). Template/workflow validation lives in the `jongio/gh-pages-templates` registry. ## Footguns - **Never** ship a project site built for `/` — assets 404. Set the base path (the generator does this; verify it). - **Never** put a subpath base on a **user site** (`<user>.github.io`) — it must be `/` (Jekyll: `baseurl: ""`). - **Never** use `actions/upload-artifact` for Pages — it's `upload-pages-artifact`. - **Never** reach for `peaceiris/actions-gh-pages` or a `gh-pages` branch — use the first-party Actions flow these templates ship. - **Never** forget to set **Source → GitHub Actions** in Settings → Pages; the workflow can't publish until Pages is enabled for Actions. - **Don't** leave the repo "Website" link blank — set `homepage` to the Pages URL (`gh repo edit --homepage`) so visitors find the site; it's the same as the "Use your GitHub Pages website" checkbox. - **Never** claim success because the workflow is green — load the URL and check an asset and an internal link actually resolve. - **Never** ship the template's demo content. A stamped template that still says "Hello, Astro", lists sample blog posts, or contains Project Northstar is a failure. Digest the repo and author real content of the right kind. - **Never** fabricate features, commands, or APIs to fill the page. Author only what the repo actually shows; leave a visible `TODO` when unsure. - **Don't** leave bare image references with nothing behind them — add the placeholders + `IMAGES.md`, or reuse the repo's existing images. - **Don't** ship placeholders silently — tell the user which real images the site needs and that they can paste a screenshot into the chat to fill each one. - **Don't** hand-roll a base-path setup when the generator + sentinels already do it correctly per framework. - **Never** pass a branch or tag as `--registry-ref`. Only a full commit SHA is immutable enough to validate. - **Never** compose directly into another generator's target. Stage first, check conflicts, then merge. -
thumbnail.png 243.8 KB · in bundle
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.