Codeberg/Community

Fork 12

Ask for advice/discussion: Documentation for Hugo websites on Codeberg Pages #2370

New issue

Open

opened 2026-02-10 18:16:36 +01:00 by steiger · 5 comments

steiger commented

2026-02-10 18:16:36 +01:00

Comment

Question: Is there a setup we would recommend for hosting a Hugo based website on Codeberg pages?

BACKGROUND

I aim to transition my Hugo based website (https://gohugo.io) from a
GitHub (repo) + AWS Amplify (website build + hosting) setup
to
Codeberg (Repo) + Codeberg Pages (hosting) .
I am happy to summarize all my learnings in a documentation for everyone. Therefore, I would like to take a "good" approach.

ISSUE DESCRIPTION

For the setup described above, I am struggling with the right Git setup (and I am not a git expert at all).
This is how I see it:

Local built and enhancement: The website would be updated and built on my local machine.
CODE REPO: For the hugo website code, I can create a dedicated repo in Codeberg. In order to not make this a lean repo, the public folder would be added to the .gitignore.
PAGES REPO: For the website hosting, I would need to push the public folder to the dedicated pages repository in Codeberg.

In this setup, the issue arises by having the public folder in the .gitignore. From what I understand, there are multiple options to work around that. E.g. I could create a dedicated git repository in the public folder. Is this what we would recommend?

### Comment Question: **Is there a setup we would recommend for hosting a Hugo based website on Codeberg pages?** ### BACKGROUND I aim to transition my Hugo based website (https://gohugo.io) from a `GitHub (repo) + AWS Amplify (website build + hosting)` setup to `Codeberg (Repo) + Codeberg Pages (hosting)` . I am happy to summarize all my learnings in a documentation for everyone. Therefore, I would like to take a "good" approach. ### ISSUE DESCRIPTION For the setup described above, I am struggling with the right Git setup (and I am not a git expert at all). This is how I see it: * Local built and enhancement: The website would be updated and built on my local machine. * CODE REPO: For the hugo website code, I can create a dedicated repo in Codeberg. In order to not make this a lean repo, the `public` folder would be added to the `.gitignore`. * PAGES REPO: For the website hosting, I would need to push the `public` folder to the dedicated pages repository in Codeberg. In this setup, the issue arises by having the `public` folder in the `.gitignore`. From what I understand, there are multiple options to work around that. E.g. I could create a dedicated git repository in the public folder. Is this what we would recommend?

mahlzahn commented

2026-02-10 18:43:16 +01:00

Member

I suggest you checkout the documentation about the new /git-pages server. In particular, the documentation of the Forgejo action might be useful if you decide to build the website using Codeberg’s CI.

You might have

a single code repository with all content needed to build the website
no extra pages repository
on push to main run the build and publish action that
- builds the website with hugo
- uploads it to user.codeberg.page using the git-pages action

Alternatively, if you don’t want to put stress on the CI and build your website locally, you can use the git-pages CLI tool to upload to user.codeberg.page from your local computer.

PS: Checking your repositories, /steiger/pegel-konstanz_website and /steiger/davidbeckonline-site, I realized that a free and open source licence is missing, which is a condition according to Codeberg’s Terms of Use.

I suggest you checkout the documentation about the new [[/git-pages]] server. In particular, the [documentation of the Forgejo action](https://codeberg.org/git-pages/action#with-a-wildcard-domain-non-matching) might be useful if you decide to build the website using Codeberg’s CI. You might have - a single code repository with all content needed to build the website - no extra pages repository - on push to main run the build and publish action that - builds the website with hugo - uploads it to user.codeberg.page using the git-pages action Alternatively, if you don’t want to put stress on the CI and build your website locally, you can use the [git-pages CLI tool](/git-pages/git-pages-cli) to upload to user.codeberg.page from your local computer. PS: Checking your repositories, [[/steiger/pegel-konstanz_website]] and [[/steiger/davidbeckonline-site]], I realized that a free and open source licence is missing, which is a condition according to [Codeberg’s Terms of Use](https://codeberg.org/Codeberg/org/src/branch/main/TermsOfUse.md#2-allowed-content-usage).

👀 1

steiger commented

2026-02-10 19:08:38 +01:00

Author

Thank you very much for your feedback and all the suggestions, @mahlzahn . Very helpful.
I will take me some time to check all the content, but I will get back to you.

Thank you very much for your feedback and all the suggestions, @mahlzahn . Very helpful. I will take me some time to check all the content, but I will get back to you.

steiger commented

2026-02-13 21:35:58 +01:00

Author

Hey @mahlzahn .
Thank you again for your feedback and suggestions.

Policy files - added. I missed this requirement, I have to admit.
git-pages CLI tool - not an option. I recognized that I cannot install this tool on my machine due to restrictions.
Forgejo actions for git-pages server. Sounds perfect. I tested this a little bit in https://codeberg.org/steiger/davidbeckonline-site . But then I recognized that these actions are not available (out of the box) in Codeberg and should be should be self-hosted (https://docs.codeberg.org/ci/actions/). I don't think that I would want to self-host at the moment.

If my understanding is correct, then I tend to think that I might return to the original idea of two distinct git repositories ("Code" excluding public and "pages" containing only the public content).

Hey @mahlzahn . Thank you again for your feedback and suggestions. 1. **Policy files - added.** I missed this requirement, I have to admit. 2. **git-pages CLI tool - not an option.** I recognized that I cannot install this tool on my machine due to restrictions. 3. **Forgejo actions for git-pages server.** Sounds perfect. I tested this a little bit in https://codeberg.org/steiger/davidbeckonline-site . But then I recognized that these actions are not available (out of the box) in Codeberg and should be should be self-hosted (https://docs.codeberg.org/ci/actions/). I don't think that I would want to self-host at the moment. If my understanding is correct, then I tend to think that I might return to the original idea of two distinct git repositories ("Code" excluding public and "pages" containing only the public content).

mahlzahn commented

2026-02-14 09:11:39 +01:00

Member

@steiger wrote in #2370 (comment):

But then I recognized that these actions are not available (out of the box) in Codeberg and should be should be self-hosted

Codeberg hosts some runners for lightweight jobs, too! See https://codeberg.org/actions/meta/

Yesterday, Codeberg's documentation was updated to include instructions how to use the new git-pages server, see https://codeberg.page/ and https://docs.codeberg.org/codeberg-pages/. In particular, https://docs.codeberg.org/codeberg-pages/forgejo-actions/.

Let me know if this works for you, else you also can use the legacy version with pages repository.

@steiger wrote in https://codeberg.org/Codeberg/Community/issues/2370#issuecomment-10567294: > But then I recognized that these actions are not available (out of the box) in Codeberg and should be should be self-hosted Codeberg hosts some runners for lightweight jobs, too! See https://codeberg.org/actions/meta/ Yesterday, Codeberg's documentation was updated to include instructions how to use the new git-pages server, see https://codeberg.page/ and https://docs.codeberg.org/codeberg-pages/. In particular, https://docs.codeberg.org/codeberg-pages/forgejo-actions/. Let me know if this works for you, else you also can use the legacy version with `pages` repository.

steiger commented

2026-02-19 09:04:52 +01:00

Author

Thank you very much, @mahlzahn .

As a quick update for today: I was able to use the "Set up your website (new method with CI)" and create

Website: https://steiger.codeberg.page/davidbeckonline-site/
From repo: https://codeberg.org/steiger/davidbeckonline-site

The YAML file for the forgejo action looks as follows:

name: Publish
on:
  push:
    branches:
      - main
jobs:
  publish:
    runs-on: codeberg-small
    steps:
      - uses: actions/checkout@v5
        with:
          submodules: true
      - run: |
          wget -q https://github.com/gohugoio/hugo/releases/download/v0.155.3/hugo_0.155.3_linux-amd64.tar.gz
          tar -xzf hugo_0.155.3_linux-amd64.tar.gz   
          ./hugo --baseURL https://steiger.codeberg.page/davidbeckonline-site/
      - uses: actions/git-pages@v2
        with:
          site: https://steiger.codeberg.page/davidbeckonline-site/
          token: ${{ forge.token }}
          source: public/

From what I understand, custom domains are not yet supported.

My next step is to create a simple example repo for a Hugo website and document this in a separate repository. If there should be any issues with the existing documentation, I will highlight this.

Thank you very much, @mahlzahn . As a quick update for today: I was able to use the "Set up your website (new method with CI)" and create * Website: https://steiger.codeberg.page/davidbeckonline-site/ * From repo: https://codeberg.org/steiger/davidbeckonline-site The YAML file for the forgejo action looks as follows: ~~~~ name: Publish on: push: branches: - main jobs: publish: runs-on: codeberg-small steps: - uses: actions/checkout@v5 with: submodules: true - run: | wget -q https://github.com/gohugoio/hugo/releases/download/v0.155.3/hugo_0.155.3_linux-amd64.tar.gz tar -xzf hugo_0.155.3_linux-amd64.tar.gz ./hugo --baseURL https://steiger.codeberg.page/davidbeckonline-site/ - uses: actions/git-pages@v2 with: site: https://steiger.codeberg.page/davidbeckonline-site/ token: ${{ forge.token }} source: public/ ~~~~ From what I understand, custom domains are not yet supported. My next step is to create a simple example repo for a Hugo website and document this in a separate repository. If there should be any issues with the existing documentation, I will highlight this.

❤️ 1

No milestone

No project

No assignees

2 participants

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

Codeberg/Community#2370

No description provided.

Rows
Columns