Gyschuaner/from-idea-to-personal-site

Publish Static Site

Goal

Publish or prepare deployment for a finished static website.

This skill is for deployable HTML/CSS/JS output such as site/, dist/, out/, public/, or docs/. It can also publish framework projects after they produce a static output folder, but it should not turn a plain static site into a framework project just to deploy it.

Default posture:

• Prefer simple static hosting over framework-specific deployment.
• Prefer Git-based deployment for sites the user will continue editing.
• Prefer direct upload only for quick one-off publishing.
• Do not create remote repositories, push code, change DNS, add domains, or deploy to a paid account unless the user explicitly asks for that action.

Contract

Inputs:

• Static deploy root such as site/, dist/, out/, public/, docs/, or repository root.
• Preferred platform or target: GitHub Pages, Cloudflare Pages, Netlify, Vercel, custom domain, guidance only, or live deployment.
• Current Git/repository state, platform account access, CLI/browser login, and any deployment constraints.

Outputs:

• Concrete deployment settings: platform, branch, build command, base directory, publish/output directory, and config files when needed.
• Optional platform-specific config such as GitHub Pages workflow, netlify.toml, vercel.json, .nojekyll, or CNAME.
• Live URL and post-deploy verification when deployment is actually performed.
• Manual dashboard steps when credentials or account access are unavailable.

Boundaries:

• Do not build or redesign the site; route defects to the appropriate child skill.
• Do not push, create repos/projects, upload, bind domains, change DNS, or use paid resources unless explicitly authorized.
• Do not use deployment as a workaround for broken local/static path compatibility unless the user explicitly accepts server-root-only behavior.

Success gate:

• review-static-site has passed or unresolved risks are explicit.
• The deploy root contains index.html and the platform will publish the correct folder.
• Online URL loads homepage, assets, navigation, and representative subpages after deployment.

If gate fails:

• Fix path, asset, encoding, or page-type blockers before deployment.
• Route content/design/import issues to personalize-site, edit-site-part, add-blog-posts, make-personal-site, or copy-website-style.
• Re-run review-static-site and then retry or update deployment settings.

References

Load only the reference needed for the chosen platform or issue:

• Path strategy and direct-open compatibility: references/path-strategy.md.
• Cloudflare Pages Git integration and Direct Upload: references/cloudflare-pages.md.
• GitHub Pages branch source and Actions workflows: references/github-pages.md.
• Netlify dashboard and netlify.toml: references/netlify.md.
• Vercel dashboard and vercel.json: references/vercel.md.

Official docs:

• GitHub Pages publishing source: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
• GitHub Pages custom workflows: https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
• Cloudflare Pages Static HTML: https://developers.cloudflare.com/pages/framework-guides/deploy-anything/
• Cloudflare Pages Git integration: https://developers.cloudflare.com/pages/get-started/git-integration/
• Cloudflare Pages Direct Upload: https://developers.cloudflare.com/pages/get-started/direct-upload/
• Netlify create deploys: https://docs.netlify.com/deploy/create-deploys/
• Netlify build configuration: https://docs.netlify.com/build/configure-builds/overview/
• Vercel deployments: https://vercel.com/docs/deployments
• Vercel project configuration: https://vercel.com/docs/project-configuration

Deployment Modes

First determine what the user actually wants:

• Guidance only: explain platform choice and exact settings. Do not edit files unless useful.
• Prepare repo: add the needed config files and tell the user what to click in the hosting dashboard.
• Deploy now: perform remote actions only if the user explicitly asked and the required CLI/auth/session exists.
• Verify live URL: open the deployed URL in a browser and check it against the local site.

If credentials, account access, browser login, or CLI authentication are missing, provide exact dashboard steps instead of inventing a workaround.

Workflow

1. Identify the static output folder and the user's preferred platform, if any.
2. Call or suggest using review-static-site before publishing.
3. Confirm the deploy root contains index.html.
4. Inspect asset paths and convert accidental root-absolute site-local paths before publishing. Load references/path-strategy.md when path behavior is unclear.
5. Choose the simplest matching platform and deployment mode.
6. Load the chosen platform reference and add only the config files required by that platform.
7. If deploying through Git, check Git status and avoid including unrelated or private files.
8. If the user authorized remote actions, push or deploy exactly what was agreed.
9. After publishing, open the live URL and verify the deployed site in a browser.

Preflight Checklist

Run these checks before writing deployment configs or telling the user settings:

• Deploy root: choose the folder that directly contains index.html.
• Entry page: index.html must exist at the deploy root top level.
• Direct-open preview: the root index.html should keep CSS, JS, images, and navigation when opened directly from the filesystem, unless the user explicitly accepted server-only behavior.
• Local HTTP: serve the deploy root with python -m http.server and confirm it works over http://127.0.0.1:<port>/.
• Static audit: run or recommend review-static-site for links, UTF-8 readability, placeholder residue, browser rendering, privacy residue, and mobile layout.
• Asset paths: inspect href, src, srcset, CSS url(...), fonts, favicons, cover images, RSS, sitemap, and manifest links.
• Private data: make sure tokens, local filesystem paths, draft notes, source-site identities, and personal secrets are not being published.
• Output completeness: confirm subpages, posts, images, vendor fonts, KaTeX/math assets, and copied media are inside the deploy root.

Treat these as blockers:

• No index.html in the deploy root.
• Broken local CSS, JS, image, font, RSS, sitemap, or vendor asset paths.
• Source files contain mojibake or unreadable encoding.
• The generated personal site still contains copied source identity that should have been replaced.
• Accidental root-absolute site-local paths such as /assets/..., /posts/..., /data/..., or /images/... remain in a generated plain static site.
• The site works over local HTTP only because root-absolute paths are being served from 127.0.0.1, but direct file opening or subpath deployment would lose CSS/JS/images.
• Privacy-sensitive files or secrets would be deployed.
• The platform would deploy the wrong folder.

Platform Choice

Use this default ranking for plain static personal sites:

1. Cloudflare Pages Git integration: best default for a generated site/ folder and future updates.
2. GitHub Pages with GitHub Actions: best when the user wants everything inside GitHub.
3. Netlify: simple static hosting with friendly previews and dashboard settings.
4. Vercel: good when the user already uses Vercel or may later move to Next.js, but not the default for plain HTML.

Decision rules:

• If the user wants the least friction and has a GitHub repo: Cloudflare Pages Git integration. Load references/cloudflare-pages.md.
• If the user wants GitHub-only hosting: GitHub Pages. Load references/github-pages.md.
• If deploy files live in repository root or /docs: GitHub Pages branch source is acceptable.
• If deploy files live in site/, dist/, out/, or another custom folder: prefer GitHub Actions for GitHub Pages.
• If the user wants manual upload today: Cloudflare Direct Upload or Netlify manual deploy.
• If the user already has a Vercel account/project: use Vercel with explicit output directory settings.

Framework Static Output

If the site is not plain HTML/CSS/JS:

• Inspect package.json, framework config, and existing scripts.
• Use the project's existing build command; do not invent npm workflows.
• Publish the final static output folder, not the source folder.
• Common outputs include dist, out, build, .output/public, and public, depending on the framework.
• For Next.js static export, verify the project is actually configured for static export before treating out/ as final output.
• For Vue/Vite/Astro-style projects, publish the configured output directory after a successful build.

If the user asked for plain static publishing and no framework files exist, do not introduce npm.

Config File Policy

Only add config files that match the chosen platform:

• GitHub Pages Actions: .github/workflows/pages.yml.
• GitHub Pages custom domain: CNAME in the deployed root, only when the user supplied the domain.
• GitHub Pages Jekyll bypass: .nojekyll in the deployed root when useful.
• Netlify: netlify.toml only when dashboard settings are not enough or the user wants config in Git.
• Vercel: vercel.json only when Vercel needs explicit output settings.
• Cloudflare Pages: usually dashboard settings are enough for plain static sites.

Do not add deployment configs for every platform at once.

Git And Remote Safety

Before any remote action, state what will happen and confirm the user asked for it:

• Creating a GitHub repository.
• Adding a remote.
• Staging or committing files.
• Pushing commits to a remote branch.
• Enabling GitHub Pages.
• Creating Cloudflare, Netlify, or Vercel projects.
• Uploading files to a hosting provider.
• Adding environment variables.
• Adding custom domains or changing DNS records.

Before staging or pushing:

• Run git status --short.
• Identify generated site files versus unrelated user changes.
• Do not stage unrelated changes.
• Do not publish private notes, credentials, local paths, screenshots with secrets, or temporary files.

Never put secrets, tokens, private notes, or local filesystem paths into the static site or deployment config.

Post-Deploy Verification

After the platform reports a live URL:

• Open the deployed URL with an actually available interactive browser tool. "Available" means it is exposed in the current turn's callable tool list. In Codex this may be the Browser/in-app browser plugin when routed into the turn.
• Verify the homepage is not a 404, blank page, or directory listing.
• Verify CSS, JavaScript, images, fonts, favicon, RSS, sitemap, and vendor assets load from the deployed domain.
• Click primary navigation and at least one representative subpage per page type.
• Test desktop and mobile widths.
• Check browser console for missing assets or JavaScript errors.
• Confirm metadata, title, description, Open Graph image, canonical URL, RSS, sitemap, and robots files when present.
• If using GitHub project Pages, specifically check subpages and asset URLs under the repository subpath.
• If using a custom domain, verify HTTPS and redirects between apex and www if configured.

If no interactive browser tool is callable, do not pretend live browser verification happened. Ask the user to enable or invoke the browser tool if live visual verification matters; for Codex, that may mean sending a request that explicitly mentions @browser. If the user does not re-route or the client has no such tool, fall back to Playwright, screenshots, HTTP checks, or static checks and state the limitation.

Do not default to Playwright or screenshots-only live verification when an interactive browser tool is actually callable. Use Playwright only as a fallback, or when the user explicitly asks for scripted deployment checks.

If the deployed site differs from local preview, inspect the deploy log, output directory, and asset path strategy before changing design code.

Output

Keep the final user-facing report concise:

• Platform chosen and why.
• Static folder published or prepared.
• Deployment mode: guidance, prepared config, Git integration, direct upload, or live deploy.
• Settings used: branch, build command, base directory, publish/output directory.
• Config files changed, if any.
• Official guide URL for the chosen platform.
• Live URL, if deployment happened.
• Verification performed and any remaining manual step.

If only guidance was requested, do not pretend the site was deployed. Give concrete platform settings and official guide links.