GitHub Pages

GitHub Pages is ideal for documentation and static sites. Use static export (e.g., Next.js output: 'export') and publish the out/ directory to the gh-pages branch using your CI workflow or the gh-pages npm package. The CLI helps with opening dashboards and general docs flows; it does not publish to GitHub Pages directly.

No capability data.

Prerequisites

  • A GitHub repo with an origin remote
  • Push permissions for gh-pages
  • Pages configured to build from the gh-pages branch (root)

Static export (Next.js 15)

Next 15 supports static export via output: 'export'. Add this to next.config.ts:

ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  output: 'export',
  images: { unoptimized: true },
  trailingSlash: true,
  // If hosting at https://<owner>.github.io/<repo>, set basePath/assetPrefix to '/<repo>'
  // basePath: '/<repo>',
  // assetPrefix: '/<repo>'
}

export default nextConfig

Then build:

bash
pnpm build

This produces out/. Ensure a .nojekyll marker exists so _next/* assets are served by GitHub Pages.

Open dashboard

bash
opd open github

This opens the repository’s Pages settings/dashboard.

CI (GitHub Actions)

Use a workflow (e.g., deploy-docs.yml) to publish the out/ folder with the gh-pages npm package or actions like peaceiris/actions-gh-pages.

If your site is hosted at /repo, set NEXT_BASE_PATH=/<repo> in the build step, or set basePath/assetPrefix in next.config.ts.

Troubleshooting

  • Icons or images missing: ensure basePath and assetPrefix are set to /<repo> in next.config.ts (or set NEXT_BASE_PATH=/<repo> in CI), and .nojekyll exists in out/.
  • Seeing the repo README instead of the site: set Pages source to gh-pages → / (root) under Settings → Pages.
  • Custom domain: add a CNAME file in public/ and configure DNS to point to <owner>.github.io.
PreviousCloudflare Pages