Github Pages Publisher

GitHub Pages Publisher

Publish already-built static artifacts to a GitHub Pages repository.

This skill is the deployment/output layer for page artifacts created by other skills.

Required repository layout

Every published artifact must go into this path shape inside the target repo:

<year>/<year>-<month>/<page-slug>/

Example:

• 2026/2026-03/my-landing-page/

Never publish flat at repo root.

Never skip the year or year-month nesting.

What this skill expects

Input should already exist as one of these:

• a folder of built static files
• a single HTML artifact plus local assets
• a small static site ready to serve from a subdirectory

This skill should not do major frontend design work. It should package and publish what already exists.

Default publishing rules

• preserve relative asset paths when possible
• prefer index.html as entrypoint inside the target page directory
• keep the output self-contained inside the page folder
• avoid breaking existing published pages
• if the same slug is republished, update the existing folder contents deliberately

URL contract

Always return the final public URL of the artifact.

Assume GitHub Pages serves from the repo's configured Pages base URL.

The final URL should be:

<pages-base-url>/<year>/<year>-<month>/<page-slug>/

or, if needed explicitly:

.../<page-slug>/index.html

Prefer the clean directory URL when it resolves correctly.

Workflow

• Determine the publish date bucket:
• year = YYYY
• year-month = YYYY-MM
• Create or update target directory:
• <year>/<year-month>/<page-slug>/
• Copy artifact files into that directory
• Optimize oversized raster images when practical, unless original-size sharing is intentional
• Verify there is an entrypoint (index.html normally)
• Run pre-publish validation (see section above)
• Commit and push to the Pages repo using the configured fine-grained token workflow
• Return the final public URL

Publishing command

python3 scripts/publish_static.py --source <dir-or-html> --slug <name> [--date YYYY-MM-DD] [--image-max-kb 500]

The script copies the artifact into YYYY/YYYY-MM/slug/, optimizes oversized .jpg, .jpeg, .png, and .webp images, commits, pushes, and prints the final public URL.

Image optimization

Image optimization is a recommendation, not a hard requirement. By default, the publishing script tries to keep each raster image under 500KB by stripping metadata, recompressing, and resizing long edges when needed.

Use --image-max-kb <kb> for a different target.

Use --keep-large-images or --image-max-kb 0 when the user explicitly needs original-size images (for example, a full-resolution infographic, map, or downloadable media asset).

The original --source artifact is not changed. Optimization happens only after files are copied into the publish repo target directory. If Pillow/uv is unavailable or optimization fails, continue publishing originals and mention the warning.

Manual console run for a prepared artifact:

uv run --with pillow python3 scripts/optimize_images.py <artifact-dir> --max-kb 500

Slug rules

• use lowercase letters, digits, and hyphens
• keep it short and descriptive
• avoid spaces, underscores, Cyrillic, timestamps unless needed for uniqueness
• if the title is user-facing, the slug can still be normalized separately

Pre-publish validation

Before pushing, the agent must verify:

• artifact has index.html entrypoint
• oversized raster images are optimized when practical, unless original-size sharing is intentional
• no absolute local paths in HTML/CSS
• no secrets in files
• all local assets reachable from the target folder
• page renders correctly (if browser tools are available, check at desktop 1440px and mobile 375px)

Safety rules

• do not delete unrelated directories in the Pages repo
• only replace contents of the target page directory being published
• if overwriting, say so in the result
• do not expose the token in output, logs, or committed files
• do not push artifacts that fail local viewport validation

Config

Read config/README.md for required environment variables and URL derivation.

References

Read if needed:

• references/publish-checklist.md — operational checklist before pushing