{"schemaVersion":1,"title":"Deploy to GitHub Pages","url":"https://appgram.github.io/docsy/guides/deployment/github-pages","markdownUrl":"https://appgram.github.io/docsy/format-md/guides/deployment/github-pages","jsonUrl":"https://appgram.github.io/docsy/agent/pages/guides/deployment/github-pages.json","version":"current","locale":"en","markdown":"# Deploy to GitHub Pages\n\nPublish an open-mode Docsy site from GitHub Actions with the correct origin and base path.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nGitHub Pages is a good fit for a public Docsy project running in open mode. Pages serves static files, so it cannot enforce lock-mode permissions.\n\n> Public Docsy portal\n>\n> This repository is public, and its documentation portal is published at [appgram.github.io/docsy](https://appgram.github.io/docsy/). Main-branch validation invokes the Pages workflow after all checks pass, with `DOCSY_ENABLE_PAGES=true`. For a generated site of your own, deployment remains opt-in until you enable Pages and its repository variable. Publishing documentation does not publish the CLI package to npm.\n\n## Generate the workflow\n\nCreate a site with `--ci --deploy github-pages --repo https://github.com/OWNER/REPOSITORY`. The CLI writes validation and Pages workflows, derives the origin and repository base path, and prints the expected URL. It does not push, enable Pages, or publish anything. Run `npm run docsy -- doctor` inside the generated site to check the setup.\n\n## Configure the public URL\n\nFor a project site at `https://ORGANIZATION.github.io/REPOSITORY/`, configure the host and repository path separately:\n\n```yaml\nsite:\n  origin: https://ORGANIZATION.github.io\n  basePath: /REPOSITORY\n\naccess:\n  mode: open\n```\n\nFor this repository, those values are `https://appgram.github.io` and `/docsy`. The Astro build then emits links and asset URLs that work below the repository path.\n\n## Add the deployment workflow\n\nCreate `.github/workflows/pages.yml`:\n\n```yaml\nname: Deploy documentation\n\non:\n  push:\n    branches: [main]\n  workflow_dispatch:\n\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n\nconcurrency:\n  group: pages\n  cancel-in-progress: true\n\njobs:\n  build:\n    if: vars.DOCSY_ENABLE_PAGES == 'true'\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v7\n      - name: Setup Node\n        uses: actions/setup-node@v7\n        with:\n          node-version: 22\n          cache: npm\n      - name: Install dependencies\n        run: npm ci\n      - name: Configure Pages\n        uses: actions/configure-pages@v6\n      - name: Build\n        run: npm run build\n      - name: Upload Pages artifact\n        uses: actions/upload-pages-artifact@v5\n        with:\n          path: dist\n\n  deploy:\n    environment:\n      name: github-pages\n      url: ${{ steps.deployment.outputs.page_url }}\n    runs-on: ubuntu-latest\n    needs: build\n    steps:\n      - name: Deploy\n        id: deployment\n        uses: actions/deploy-pages@v5\n```\n\nThe deployed artifact must be `dist`, not `release/REPOSITORY`. GitHub Pages already mounts the artifact at the repository path, while Astro's `base` setting makes internal URLs point there.\n\n## Enable the Pages source\n\nOnly when publication is explicitly intended: in repository settings, open **Pages** and choose **GitHub Actions** as the build source, then add the Actions repository variable `DOCSY_ENABLE_PAGES` with value `true`. Push to `main` or run the workflow manually. Leave the variable unset during private development; the build/deploy jobs are skipped.\n\nThe workflow requires `pages: write` and `id-token: write`, and deploys through the `github-pages` environment.\n\n## Verify the production build locally\n\nRun the same build before pushing:\n\n```bash\nnpm ci\nnpm run validate\nnpm run build\n```\n\nConfirm that `dist/index.html` exists and that generated links begin with the configured base path. A `.nojekyll` file under `public/` is copied into the output so GitHub Pages serves Astro's generated assets unchanged.\n\n## Do not publish protected sources\n\nGitHub Pages sites are public even when the repository itself is private. Do not use Pages for protected documentation or publish sensitive Markdown, OpenAPI, or SDK inputs through the static artifact. Use locked mode on a Node or Bun server instead.\n\n","contentLocale":"en","isFallback":false,"authorship":{"authors":[{"name":"nedimf","kind":"human","github":"nedimf","avatar":"/docsy/assets/authors/nedimf.png","role":"AppGram","id":"nedimf","url":"https://github.com/nedimf"},{"name":"AppGram","kind":"organization","github":"AppGram","url":"https://appgram.dev","avatar":"/docsy/assets/ag-logo.svg","id":"appgram"}],"contributors":[],"reviewedBy":[]},"editUrl":"https://github.com/AppGram/docsy/edit/main/content/deployment/github-pages.md"}