Gitea Pages

You can publish pages for your organization or your project via gitea pages. The static web pages are taken from a branch called gitea-pages in your repository.

By default the pages are only accessible from the PSI intranet. Pages are always published with your organization as subdomain of *.pages.psi.ch. The https certificate is automatically configured.

If you want to have your pages published to the Internet or use a custom domain name, then they need to be added to PSI reverse proxy by security team. This can be done by following ServiceNow workflow: Publish Gitea Page

!!! note In the following examples, replace YOUR_ORGANIZATION, YOUR_REPOSITORY, YOUR_SITE_NAME with your names!

YOUR_ORGANIZATION.pages.psi.ch

If you want to publish your content in the "root directory" of your organization you have to create a repository called gitea-pages. Within this repository all content in the branch gitea-pages will be published to https://YOUR_ORGANIZATION.pages.psi.ch/.

You may have other branches too.

YOUR_ORGANIZATION.pages.psi.ch/YOUR_REPOSITORY

If you just put a branch gitea-pages in a repository in your organization, the repository name will be used as location in the URL like shown in the chapter title. You may have multiple Repos with a "Pages Branch".

Example Pages Project

You can use any static site generator you like. However if you have no strong preferences we recommend to use Zensical together with Gitea Actions.

You can easily create a static site with Zensical and publish it automatically with Gitea Actions to the gitea-pages branch. The following example workflow shows how to do this.

Create a new repository on the Gitea web frontend for your documentation or website and clone it to your local machine
```
git clone https://gitea.psi.ch/YOUR_ORGANIZATION/YOUR_REPOSITORY.git
cd YOUR_REPOSITORY
```

Add a docs directory with your Markdown files

mkdir docs
echo "# My Documentation" > docs/index.md

Add a Zensical configuration file zensical.toml in the root of your repository like the following example

[project]
repo_url = "https://gitea.psi.ch/YOUR_ORGANIZATION/YOUR_REPOSITORY"
edit_uri = "_edit/main/docs/"

site_name = "YOUR_SITE_NAME"

site_description = """
Documentation for YOUR_SITE_NAME
"""

site_author = "Paul Scherrer Institute"

site_url = "https://YOUR_ORGANIZATION.pages.psi.ch/YOUR_REPOSITORY/"

copyright = """
Copyright &copy; 2026 Paul Scherrer Institute
"""

language = "en"

features = [
    "announce.dismiss",
    "content.action.edit",
    "content.code.annotate",
    "content.code.copy",
    "content.code.select",
    "content.footnote.tooltips",
    "content.tabs.link",
    "content.tooltips",
    "navigation.footer",
    "navigation.indexes",
    "navigation.instant",
    "navigation.instant.prefetch",
    "navigation.path",
    "search.highlight",
    "navigation.top",
    "navigation.tracking",
]

[project.theme]
# do not use google fonts
font = false

[[project.theme.palette]]
scheme = "default"
toggle.icon = "lucide/sun"
toggle.name = "Switch to dark mode"

[[project.theme.palette]]
scheme = "slate"
toggle.icon = "lucide/moon"
toggle.name = "Switch to light mode"

[project.theme.icon]
logo = "simple/gitea"
repo = "simple/gitea"

Create a Gitea Actions workflow to build and publish the site. Create a workflow file in .gitea/workflows/publish-site.yml with following content:

name: Build and Publish Site

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  docker:
    runs-on: ubuntu-latest-intranet
    container:
      image: gitea.psi.ch/images/alpine-zensical
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build page
        run: /opt/python-env/bin/zensical build

      - name: Configure Git
        run: |
          git config --global user.name "Gitea Actions"
          git config --global user.email "actions@gitea.local"

      - name: Push to gitea-pages branch
        run: |
          git checkout --orphan gitea-pages
          git reset --hard
          mv site/* .
          git add .
          git commit -m "Update site - $(date)"
          git push -f https://${{ secrets.GITHUB_TOKEN }}@gitea.psi.ch/${{ github.repository }}.git gitea-pages

Commit and push your changes to the main branch

git add --all
git commit -m "Initial commit"
git push origin main

Wait for the Gitea Actions workflow to complete. Once done, your site will be published and accessible at: https://YOUR_ORGANIZATION.pages.psi.ch/YOUR_REPOSITORY/

4.9 KiB Raw Permalink Blame History

Gitea Pages

YOUR_ORGANIZATION.pages.psi.ch

YOUR_ORGANIZATION.pages.psi.ch/YOUR_REPOSITORY

Example Pages Project

4.9 KiB

Raw Permalink Blame History