Document how to deploy to GitHub Pages

[TheKnarf]

Would be nice with some instructions for how to deploy Nextra to GitHub Pages (while using GitHub Actions).

Personally I had to use the following next.config.js:

const withNextra = require('nextra')({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.jsx'
});

module.exports = withNextra({
	output: 'export',
	images: {
		unoptimized: true,
	},
});

To actually get an out/ directory I had to set output: 'export', however that gave me some error about images. I solved that by setting image.unoptimized: true (however I wish there was a better experience out of the box).

Then I could create a GitHub Action called .github/worflows/gh-pages.yml:

name: Deploy Github Pages

on:
  push:
    branches:
      - main

jobs:
  deploy-github-pages:
    runs-on: ubuntu-latest

    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
    permissions:
      pages: write      # to deploy to Pages
      id-token: write   # to verify the deployment originates from an appropriate source

    # Deploy to the github-pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: 'Checking Out Code'
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: 'Setting up Node'
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - uses: pnpm/action-setup@v2
        with:
          version: 8

      - name: 'Setup & Build'
        run: |
          cd docs/
          pnpm install
          pnpm build

      - name: 'upload'
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./docs/out

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Seems like it could save people some time if this was documented.