Pushing output from SSGs into Codeberg Pages

If you are using a static site generator (SSG) and are satisfied with the result of your project on your local development environment, you can push the files to your Codeberg Pages repository.

Manual pushing

To begin with, we will have two separate repositories, both locally and on Codeberg:

  • A main repository for the source files, i.e. where the source files related to your main project will be located. We will refer to this repository as the source repository. This repository is the one associated with your mydocs folder.

  • A second repository for Codeberg pages that we will call the pages repository. This repository will only contain the files available in the html folder located under docs/build/html.

Warning

The pages repository must be public, as Codeberg Pages will directly fetch the files from the repository, just like an ordinary user would.

Info

For the purpose of this guide, we have chosen to use two separate folders/repositories. However, you may want to have a different setup that involves creating a submodule instead of having folders and repositories in separate locations. With a submodule, your configuration may look like so:

├── sources --> This is a git repo
│   ├── build
│   │   └── html
│   │       └── pages --> This is a separate git repo
│   └── content

To copy the content of the html folder to your new pages folder, run the command:

(.venv) $ cp -R docs/build/html/ pages

We will now initialize an empty repository inside the pages folder. To do this, type the command:

git init

To check the status of your project’s files, type the command:

git status

To add all the files that are available in your directory to Git, run the command:

git add -A

Now we will commit:

git commit -m "Example commit message"

Repeat these steps in your source folder, then push your local commits to the remote repository with the command:

git push origin HEAD:your-remote-branch-name
Note

Replace your-remote-branch-name with the name of your remote branch. It is recommended to initially push your commits to a branch other than the default branch. Once you have made sure everything went smoothly, you can then make a pull request to merge it into the default branch. To learn more about pull requests, read the article Pull requests and Git flow.

You should now be able to access your content by visiting https://{username}.codeberg.page. You can find more information in the Codeberg Pages section.

Using a CI

Both the Woodpecker CI and the hosted Forgejo Actions can be used to automate the build and deployment of your static website.

For the Woodpecker CI, you can see the existing example workflows in the Codeberg-CI/examples repo, which provides examples for Jekyll, Hugo, Zola and many other popular SSG.

Currently, we do not have any examples for the Forgejo Actions yet, but individual SSG tools might have details in their own documentation:

Note that if you use Forgejo Actions to publish the website, you should make sure that .domains file will be preserved in the root directory of the output branch or repository.

Contributing

Hey there! 👋 Thank you for reading this article!

Is there something missing, or do you have an idea on how to improve the documentation? Do you want to write your own article?

You're invited to contribute to the Codeberg Documentation at its source code repository for example, by adding a pull request or joining in on the discussion in the issue tracker.

For an introduction on contributing to Codeberg Documentation, please have a look at the Contributor FAQ.