# Publish your site

The great thing about hosting project documentation in a `git` repository is the ability to deploy it automatically when new changes are pushed. Zensical makes this ridiculously simple.

## GitHub Pages

If you're already hosting your code on GitHub, [GitHub Pages](<https://pages.github.com/>) is certainly the most convenient way to publish your project documentation. It's free of charge and pretty easy to set up.

### with GitHub Actions

Using [GitHub Actions](<https://github.com/features/actions>) you can automate the deployment of your project documentation on pushes to a specific branch in your repository.

> [!NOTE]
>
> **Prerequisite**
>
> GitHub Pages for your repository must be configured [to publish using GitHub Actions](<https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow>).

If you created your site with `zensical new`, a publishing workflow was already created for your project in `.github/workflows/docs.yml`. If you don't already have this workflow, create a new GitHub Actions workflow at the root of your repository (e.g. `.github/workflows/docs.yml`) with the following contents:

```yaml
name: Documentation
on:
  push:
    branches:
      - master
      - main
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/configure-pages@v6
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v6
        with:
          python-version: 3.x
      - run: pip install zensical
      - run: zensical build --clean # (1)!
      - uses: actions/upload-pages-artifact@v5
        with:
          path: site
      - uses: actions/deploy-pages@v5
        id: deployment
```

1. At the moment, we do not recommend using caches on CI systems as the caching functionality will undergo revisions as we optimize the performance of Zensical.

When a new commit is pushed to the branch you are using for deployment (e.g. `master` or `main`), the static site is automatically built and deployed. Push your changes to see the workflow in action.

Your documentation should shortly appear at `<username>.github.io/<repository>`.

## GitLab Pages

If you're hosting your code on GitLab, deploying to [GitLab Pages](<https://gitlab.com/pages>) can be done by using the [GitLab CI](<https://docs.gitlab.com/ee/ci/>) task runner. At the root of your repository, create a task definition named `.gitlab-ci.yml` and copy and paste the following contents:

```yaml
pages:
  stage: deploy
  image: python:latest
  script:
    - pip install zensical
    - zensical build --clean # (1)!
  pages:
    publish: site # (2)!
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
```

1. At the moment, we do not recommend using caches on CI systems as the caching functionality will undergo revisions as we optimize the performance of Zensical.
2. The Gitlab documentation says that the SSG should adapt to Gitlab Pages, which uses the folder `public` by default but it is possible to [configure the default folder](<https://docs.gitlab.com/user/project/pages/introduction/#customize-the-default-folder>) as shown here.

When a new commit is pushed to the [default branch](<https://docs.gitlab.com/ee/user/project/repository/branches/default.html>) (e.g. `master` or `main`), the static site is automatically built and deployed. Push your changes to see the workflow in action.

> [!NOTE]
>
> **Gitlab Pages settings**
>
> By default, Gitlab Pages publishes to a domain that includes a random string. Untick the `Use unique domain` box in your Gitlab Pages settings for your production deployment. Also make sure to set the visibility for Pages under `Settings > General > Visibility` if you want a public site.

Your documentation will be published under `<username>.gitlab.io/<repository>`.

## Other

We cannot document every hosting provider here. The following community guides describe how to deploy a Zensical site elsewhere. If you find an issue with one of these guides, please contact the author.

- [Azure Static Web Apps with GitHub Actions](<https://zensical-guides.hypercat.net/azure-static-web-app-github/>)
- [Azure Static Web Apps with Azure DevOps](<https://zensical-guides.hypercat.net/azure-static-web-app-devops/>)
- [Deploying Zensical on Read the Docs](<https://docs.readthedocs.com/platform/stable/intro/zensical.html>)
- [Publish Zensical to Codeberg Pages using Forgejo Actions](<https://sorenpeter.codeberg.page/zensical-on-git-pages/>)