From 555c790526b856ea1cac478adf1362502ddebbb9 Mon Sep 17 00:00:00 2001 From: Daphne Preston-Kendal Date: Fri, 30 Jan 2026 22:26:53 +0100 Subject: [PATCH] Update Codeberg Pages documentation for git-pages --- content/codeberg-pages/advanced-usage.md | 65 +++++ .../codeberg-pages/examples/docs-as-code.md | 268 ------------------ content/codeberg-pages/forgejo-actions.md | 60 ++++ content/codeberg-pages/index.md | 111 ++++++-- .../codeberg-pages/migrating-from-pages-v2.md | 77 +++-- content/codeberg-pages/pushing-output.md | 22 +- content/codeberg-pages/redirects.md | 54 ---- content/codeberg-pages/troubleshooting.md | 2 +- content/codeberg-pages/using-custom-domain.md | 15 +- 9 files changed, 304 insertions(+), 370 deletions(-) create mode 100644 content/codeberg-pages/advanced-usage.md delete mode 100644 content/codeberg-pages/examples/docs-as-code.md create mode 100644 content/codeberg-pages/forgejo-actions.md delete mode 100644 content/codeberg-pages/redirects.md diff --git a/content/codeberg-pages/advanced-usage.md b/content/codeberg-pages/advanced-usage.md new file mode 100644 index 0000000..51c9682 --- /dev/null +++ b/content/codeberg-pages/advanced-usage.md @@ -0,0 +1,65 @@ +--- +eleventyNavigation: + key: Advanced usage + title: Advanced usage + parent: CodebergPages + order: 999 +--- +## Custom error page for 404s + +You can replace the default 404 error page that Codeberg Pages will show for missing pages with your own version if you prefer. +To do so start by writing your own HTML file that you want to serve instead. + +After creating the HTML with your custom error message, save it as `404.html` in the root of your +repository that you use to serve your Codeberg Page. + +From then on, your `404.html` file will be served when the error is encountered. + +## Redirects + +Redirects can be created with a `_redirects` file with the following format: + +```text +# Comment +from to [status] +``` + +- Lines starting with `#` are ignored +- `from` - the path to redirect from +- `to` - the path or URL to redirect to +- `status` - status code to use when redirecting (optional, default 301) + +### Status codes + +- `200` - returns content from specified path (no external URLs) without changing the URL (rewrite) +- `301` - Moved Permanently (Permanent redirect) +- `302` - Found (Temporary redirect) + +### Examples + +#### Simple redirect + +Redirects a specific path. + +```text +/example https://example.com/ 301 +/path /other-path 301 +``` + +#### SPA (single-page application) rewrite + +Redirects all paths to `/index.html` for single-page apps. + +```text +/* /index.html 200 +``` + +#### Splats + +Redirects every path under `/articles` to `/posts` while keeping the path. + +```text +/articles/* /posts/:splat 302 +``` + +Example: `/articles/2022/10/12/post-1/` → `/posts/2022/10/12/post-1/` diff --git a/content/codeberg-pages/examples/docs-as-code.md b/content/codeberg-pages/examples/docs-as-code.md deleted file mode 100644 index c927fd5..0000000 --- a/content/codeberg-pages/examples/docs-as-code.md +++ /dev/null @@ -1,268 +0,0 @@ ---- -eleventyNavigation: - key: DocsAsCode - title: 'Example: Docs as Code with Sphinx' - parent: CodebergPages - order: 100 ---- - -Docs-as-code (also known as "Documentation as Code") refers to the concept of treating documentation as a codebase, -i.e. integrating the documentation process in the toolchains and workflows used by software development teams. - -Docs-as-code involves using version control systems such as Git for your documentation projects and authoring your content -with plain text markup languages such as Markdown or reStructuredText, among other things. - -To find out more about docs-as-code, head over to [its website](https://docs-as-co.de/). - -Whether you are a single technical communicator or a member of a larger documentation team, you can perfectly apply the -docs-as-code approach to your documentation projects. - -This guide will show you how to implement docs-as-code on a Linux machine using [Sphinx](https://www.sphinx-doc.org/en/master/) -as a documentation generator, [Git](https://ka2in.codeberg.page/gitinminutes.html) as a version control system -and [Codeberg Pages](https://docs.codeberg.org/codeberg-pages/) as static site hosting. - -{% admonition "info" "Note" %} - -Despite the fact that we are using Sphinx in this particular case, you can easily apply these instructions to any static -site generator (SSG) such as [Eleventy](https://www.11ty.dev/) or [Hugo](https://gohugo.io/). - -{% endadmonition %} - -## Building documentation with Sphinx - -Initially developed to generate Python documentation, Sphinx is now widely used by technical communicators and software -developers to create technical and software documentation. - -Sphinx uses [reStructuredText](https://docutils.sourceforge.io/docs/user/rst/quickref.html) as a markup language -to generate documentation content. -Among further advantages, Sphinx allows you to produce your documentation in different formats, -including HTML, LaTeX and ePub. -You can also use one of the multiple extensions developed by the community to extend its functionality. - -### Setting up the project - -To begin setting up your project, you will first need an account on Codeberg. -If you don't already have one, follow the instructions provided under [Your First Steps on Codeberg](https://docs.codeberg.org/getting-started/first-steps/). - -This guide assumes that you already have Git installed on your machine. -If you don't, you can install git as described in the article [Install Git](https://docs.codeberg.org/getting-started/install-git/). - -For the purpose of this guide, we will start a documentation project from scratch using an empty repository. -To create a new empty repository and clone it to your local workspace, -follow the steps described in the article [Your First Repository](https://docs.codeberg.org/getting-started/first-repository/) -as well as the instructions provided under "Option A: Clone the newly created, empty repository" within the same article. - -### Creating a Python virtual environment - -A "virtual" isolated environment comes in very handy to eliminate the risk of any broken dependencies while working on -your projects. In other words, setting up a virtual environment for your project allows you to run an instance of the -Python interpreter with a particular package set and a specific configuration while ensuring compatibility between all -these components inside that environment. - -Before starting, you should make sure that you have pip and Python 3 installed on your machine. -To check, type the following commands in your terminal: - -```bash -pip --version -python3 --version -``` - -If pip and Python are not installed on your Linux machine, please follow the steps described in the articles [pip Installation](https://pip.pypa.io/en/latest/installation/) -and [Installing Python 3 on Linux](https://docs.python-guide.org/starting/install3/linux/) respectively. - -Depending on your Python version, you will need to install a compatible virtual environment manager, -i.e. either "venv" for Python >= 3.3, or "virtualenv" for older Python versions. - -{% admonition "warning" %} - -Please note that Python2 has reached its EOL (End of Life) on January 1st 2020, which means that it is no longer -receiving any security updates. - -If you are using Python 3.3 or higher, you do not need to install the "venv" module, since it is already available in -your Python standard library. - -{% endadmonition %} - -The next step is to create a virtual environment. To do so, navigate to the folder where you have cloned the repository -described under the section [Setting up the project](#setting-up-the-project): - -```bash -cd ~/repositories/foobar -python3 -m venv env -``` - -You can replace the second argument "env" with any other name your like. This will be the folder hosting your virtual environment. - -{% admonition "warning" %} - -Use a **`.gitignore`** file to exclude your virtual environment directory from your version control system. -To ignore the entire "env" folder, include the corresponding path and append a **`/`** at its end, e.g. **`env/`**. - -{% endadmonition %} - -### Activating the virtual environment - -Before you begin performing any tasks on your project, you must activate your virtual environment by running the -following command: - -```bash -. env/bin/activate -``` - -To make sure that you are working inside of your virtual environment, run the command: - -```bash -which python -``` - -The output of the command above should be the **`env`** folder, e.g.: - -```bash -./env/bin/python -``` - -When you are done working on your project, run the following command to leave the virtual environment: - -```bash -deactivate -``` - -### Installing Sphinx in your virtual environment - -If you have followed the steps described up to this point, your local repository should now contain your virtual -environment's folder **`env`** in addition to the hidden **`.git`** directory and the **`.gitignore`** file that we have -already described at the end of the section [Creating a Python virtual environment](#creating-a-python-virtual-environment), -e.g.: - -```bash -├── myproject -│ ├── env -│ ├── .git -│ └── .gitignore -``` - - -You will now create an empty directory then navigate to it. For the purpose of this guide, we will call our directory -`mydocs`. You can choose any name you'd like: - -```bash -mkdir mydocs -cd mydocs -``` - -Running the command `tree -a` should now output the following: - -```bash -. -├── mydocs -├── env -├── .git -└── .gitignore -``` - -With your virtual environment activated as shown above, it is now time to install Sphinx with `pip`. To do so, run the following: - -```bash -(.venv) $ pip install -U sphinx -``` - -{% admonition "tip" %} - -If you wish to learn about the different options of **`pip install`** are, run the command **`pip install -h`**. - -{% endadmonition %} - -Once Sphinx is installed on your virtual environment, type the following command in your terminal: - -```bash -(.venv) $ sphinx-quickstart -``` - -You will then be asked to answer a series of questions regarding the configuration of your project. -Confirm that you want to **`Separate source and build directories`**. -For the rest of the questions, keep pressing **Enter** to accept the default values and fill out the requested fields -until you reach the question **`autodoc: automatically insert docstrings from modules`**, then choose **"y" (yes)**. -Keep pressing **Enter** again until you reach the question **`Create Makefile?`** and select **"y" (yes)**. - -If you now run the `tree` command from your `mydocs` folder, you should get the following output: - -```bash -. -├── build -├── make.bat -├── Makefile -└── source - ├── conf.py - ├── index.rst - ├── _static - └── _templates -``` - -Congratulations! 🎉 You have just finished installing Sphinx on your Linux machine. - -### Running a local HTTP server using Python - -To set up a local testing server for your documentation project, you can use the Python module **`http.server`**. -To do so, you will first have to build the HTML resources for the initial test by running the command: - - - -```bash -(.venv) $ sphinx-build -b html docs/source/ docs/build/html -``` - -Then navigate to the directory hosting the HTML resources: - -```bash -(.venv) $ cd docs/build/html -``` - -Once there, run the local python server with the command: - -```bash -(.venv) $ python3 -m http.server 8080 -``` - -{% admonition "info" %} - -"8080" is the TCP port on which the host server is listening for requests. - -{% endadmonition %} - -To access the default **`index.html`** file, type **`http://localhost:8080`** in your favorite browser. -You should then see the default welcome page. - -### Creating files with reStructuredText and checking the output - -You can start creating your own content by making a new reStructuredText file (.rst) in the source directory: - -```bash -(.venv) $ cd mydocs/source -(.venv) $ touch mynewfile.rst -``` - -You have just created an empty ".rst" file with the **`touch`** command. An ".rst" file is simply a plain text file that -is written with reStructuredText as a markup language. -To learn about how to use reStructuredText, follow the instructions provided in the article [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). - -You will be more productive in your writing if you use a text editor that supports syntax highlighting such as -[Emacs](https://www.gnu.org/software/emacs/download.html) or [VSCodium](https://vscodium.com/). -Linux offers plenty of powerful text editors that support syntax highlighting and other advanced features for coding and -authoring tasks. - -{% admonition "info" %} - -Whenever you create a new .rst file, you must add it manually to the `toctree` of your root document, i.e. "index.rst". - -{% endadmonition %} - -The toctree directive (toc stands for Table of Contents) inserts a tree that connects the different ".rst" files located -in your source directory with each other. -Read the article [Directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#toctree-directive) -to learn more about the toctree directive. - -Once you have added an .rst file to the `toctree`, you can check the output at any time by running the [sphinx-build](#running-a-local-http-server-using-python) -command illustrated above, then refreshing your local testing server. - -If you are satisfied with the result on your local development environment, you can publish the content on Codeberg Pages. -To find out how to do this, read the article [Pushing output from SSGs into Codeberg Pages](https://docs.codeberg.org/codeberg-pages/pushing-output/). diff --git a/content/codeberg-pages/forgejo-actions.md b/content/codeberg-pages/forgejo-actions.md new file mode 100644 index 0000000..cb4a6da --- /dev/null +++ b/content/codeberg-pages/forgejo-actions.md @@ -0,0 +1,60 @@ +--- +eleventyNavigation: + key: Deploying directly from Forgejo Actions + title: Deploying directly from Forgejo Actions + parent: CodebergPages + order: 100 +--- +{% admonition "Warning" %} + +The following instructions depend on the new git-pages server for Codeberg Pages and can currently only be used on sites which are hosted under our `codeberg.page` domain, and not with sites that should be served from custom domains. + +Follow the [old instructions for legacy v2 sites](/codeberg-pages/) if you would like to deploy to a custom domain. + +{% endadmonition %} + +Git-pages has an [associated Forgejo Action](https://codeberg.org/git-pages/action) that can be used to automatically deploy your website from a static site generation tool. +You can use any such tool you like: git-pages does not privilege any particular publishing system over others. + +If you already use a static site generator and/or already use Forgejo Actions, using the pre-made Forgejo Action is by far the simplest and most efficient way to publish your site to Codeberg Pages. + +To use it, simply add it as a final step to your workflow: + +{% raw %} + +```yaml +- uses: https://codeberg.org/git-pages/action@v2 + with: + site: https://username.codeberg.page/repository-name/ + token: ${{ forge.token }} + source: _site/ +``` + +{% endraw %} + +Replace `username` in the `site` parameter with your Codeberg username or organization name, and `repository-name` with the name of your repository. +If your repository is also called `pages`, you can also omit the repository name and deploy directly to the site `https://username.codeberg.page/`. + +The `source` parameter should point to the directory (relative to the root, after all previous steps in your workflow) where your site generator has put the generated version of your site. +This directory can also contain the `404.html` and `_redirects` files to customize your site’s behaviour, as described in the [advanced documentation](/codeberg-pages/advanced-usage/). + +The `token` will automatically be filled by Forgejo Actions with a secret token, which in turn will automatically be recognized by git-pages as authorizing this workflow to publish to this site. + +{% admonition "Warning" %} + +If you accept pull requests on your repository, or use branches to test out new features, write draft blog posts, etc., you should either limit the whole workflow, or this step only, to pushes to a default branch (usually `main` or `master`) to ensure that only finalized content is published to your site. + +To do this, either add a [`on.push.branches` list](https://forgejo.org/docs/next/user/actions/reference/#onpush) to the whole workflow, or add [an `if` condition to the step](https://forgejo.org/docs/next/user/actions/reference/#jobsjob_idstepsif-1) (or [to the whole job](https://forgejo.org/docs/next/user/actions/reference/#jobsjob_idif)) like this: + +{% raw %} + +```yaml +if: ${{ forge.ref == 'refs/heads/main'}} +``` + +{% endraw %} + +This will limit deploys so they only happen when CI is triggered by a push to the `main` branch. + +{% endadmonition %} + diff --git a/content/codeberg-pages/index.md b/content/codeberg-pages/index.md index 3d96ea0..d10152a 100644 --- a/content/codeberg-pages/index.md +++ b/content/codeberg-pages/index.md @@ -8,30 +8,27 @@ eleventyNavigation: {% admonition "Warning" %} -Codeberg Pages is currently migrating from the legacy v2 codebase to the newer "Git Pages" approach. -To avoid confusion, we have removed documentation for the v2 Pages, which can be read manually by [browsing the history](https://codeberg.org/Codeberg/Documentation/src/commit/941914f6986b93a2aef7592b2f857317bad38dee/content/codeberg-pages). +Codeberg Pages is currently migrating from the legacy v2 codebase to the newer [git-pages](https://git-pages.org/) codebase. + +Currently, websites that use custom domains can only be deployed using the old method, but we are working to fix this. +Such websites will keep working indefinitely. +You will be able to seamlessly migrate to the new version of Pages once it is supported. + +Websites hosted under the `codeberg.page` domain can already use the new git-pages method. + The new documentation is work in progress, and we appreciate your feedback. Please let us know in case you find yourself confused. {% endadmonition %} Codeberg Pages allows you to easily publish static websites with a human-friendly address (`{username}.codeberg.page`) or your custom domain on Codeberg. +You can publish an website for your user or organization, as well as websites for each repository. -Follow these simple steps below to get started, or check out the advanced usage below. - -1. Create a **public** repository named 'pages' in your user account or organization. -2. Create static content, HTML, stylesheets, fonts or images. Name the homepage file `index.html`. -3. Push your content to the default branch of the new repository. -4. - ---- - -Codeberg is using ["git-pages", which is developed on Codeberg](https://codeberg.org/git-pages/git-pages). It is free/libre open source software. +Codeberg Pages are served using a deployment of [git-pages](https://git-pages.org/), which itself is [developed on Codeberg](https://codeberg.org/git-pages/git-pages). It is free/libre open source software. See also: - [codeberg.page](https://codeberg.page) - [Troubleshooting (Codeberg Documentation)](troubleshooting) -- [Features (Codeberg Pages Repository)](https://codeberg.org/Codeberg/pages-server/src/branch/main/FEATURES.md) {% assign navPages = collections.all | eleventyNavigation %} {%- for entry in navPages %} @@ -54,28 +51,86 @@ See also: {% endif %} {%- endfor %} +## Getting started with a `codeberg.page` URL -## Advanced Usage: Custom error page for 404s +There are two ways to get started with Codeberg Pages on git-pages: -You can replace the default 404 error page that Codeberg Pages will show for missing pages with your own version if you -prefer. -To do so start by writing your own HTML file that you want to serve instead. +1. Using a [webhook](/advanced/using-webhooks/) on your repository +2. Using [Forgejo Actions](/codeberg-pages/forgejo-actions/) to deploy the output of a static site generator -After creating the HTML with your custom error message, save it as `404.html` in the root of your -repository that you use to serve your Codeberg Page. +This page documents the first method. See the [separate page on using Forgejo Actions](/codeberg-pages/forgejo-actions/) for information on the second method. -From then on, your `404.html` file will be served when the error is encountered. +### User/organization websites -## Do you have questions, feedback or have you found a bug? +1. Create a repository called `pages` under your own username or under the organization you want to create a website for -The source code for Codeberg Pages is maintained over at the [Pages Server repository](https://codeberg.org/Codeberg/pages-server); + The website will be published from a branch also called `pages`. You can also set this as the default branch, if you prefer. + +2. Go to **Settings** at the top right of your repository page. + +3. Click **Webhooks** in the sidebar on the left. + +4. Click the **Add webhook** button in the top right corner of the webhook settings page. + + Select **Forgejo** from the drop-down list of webhook types. + +5. Enter `https://username.codeberg.page/` as the **Target URL**, replacing the `username` with your Codeberg username or organization name. This is the URL your website will be available from. + +6. Set the **Branch filter** to `pages`. + +7. Click the **Add webhook** button at the bottom of the settings page. + +8. Push or upload your content to the `pages` branch, and it will automatically be published to `https://username.codeberg.page/`. + +### Repository websites + +1. Go to **Settings** at the top right of your repository page. + +2. Click **Webhooks** in the sidebar on the left. + +3. Click the **Add webhook** button in the top right corner of the webhook settings page. + + Select **Forgejo** from the drop-down list of webhook types. + +4. Enter `https://username.codeberg.page/repository-name/` as the **Target URL**, replacing the `username` with your Codeberg username or organization name, and `repository-name` with the name of your repository. This is the URL your website will be available from. + +5. Set the **Branch filter** to `pages`. + +6. Click the **Add webhook** button at the bottom of the settings page. + +7. Push or upload your content to a branch called `pages` on your repository, and it will automatically be published to `https://username.codeberg.page/repository-name/`. + +## Getting started with a custom domain + +{% admonition "warning" %} + +You can only use the ‘legacy’ v2 Pages deployment method at the moment if you want to serve your site with a custom domain. + +Websites deployed this way will keep working indefinitely. +You will be able to seamlessly migrate to the new version of Pages once it is supported. + +{% endadmonition %} + +There are two steps to getting started with a custom domain: configuration on Codeberg’s side, and configuration on the side of your DNS. + +To set up your website for publication on a custom domain on the Codeberg side, simply upload your content to a branch of a repository called `pages`. You then also need to create a plain text file called `.domains` listing the domains your website should be available at. + +You then need to set up DNS records to point to Codeberg. Instructions on how to do this are available on the [documentation page about using custom domains](/codeberg-pages/using-custom-domain/). + +## Having problems? + +See our [troubleshooting page](/codeberg-pages/troubleshooting). + +## Advanced usage: custom 404 pages, redirects, and rewrites + +For sites hosted with Codeberg Pages, you can customize the look of the 404 page when someone tries to access a page that doesn’t exist, and you can make URLs redirect to other URLs or serve the same content as at some other URL. + +See the [advanced usage](/codeberg-pages/advanced-usage/) documentation to learn how to do these things. + +## Do you have questions, feedback, or have you found a bug? + +Support for Codeberg Pages is available at the [Pages Server repository](https://codeberg.org/Codeberg/pages-server); feel free to head there to provide some feedback, suggestions, bug reports or even patches. If you need general community support or have questions, [Codeberg/Community](https://codeberg.org/Codeberg/Community) is a better place to ask, as more people will be watching there to help you out! We really appreciate your contribution. - -## Installing Pages for your own Forgejo instance - -Codeberg Pages works with any Forgejo host out there. So if you are running your own Forgejo, you can absolutely run it -yourself and help with the development. -Check out the [Pages Server repository](https://codeberg.org/Codeberg/pages-server) for more information. diff --git a/content/codeberg-pages/migrating-from-pages-v2.md b/content/codeberg-pages/migrating-from-pages-v2.md index df92246..41bc59e 100644 --- a/content/codeberg-pages/migrating-from-pages-v2.md +++ b/content/codeberg-pages/migrating-from-pages-v2.md @@ -3,8 +3,21 @@ eleventyNavigation: key: Migrating from Pages v2 title: Migrating from Pages v2 parent: CodebergPages - order: 99 + order: 120 --- +{% admonition "Warning" %} + +Codeberg Pages is currently migrating from the legacy v2 codebase to the newer [git-pages](https://git-pages.org/) codebase. + +Currently, websites that use custom domains can only be deployed using the old method, but we are working to fix this. +Such websites will keep working indefinitely. +You will be able to seamlessly migrate to the new version of Pages once it is supported. + +Websites hosted under the `codeberg.page` domain can already use the new git-pages method. + +The new documentation is work in progress, and we appreciate your feedback. Please let us know in case you find yourself confused. + +{% endadmonition %} Since December 2025, Codeberg offers a new Pages service based on [git-pages](https://codeberg.org/git-pages/git-pages). It improves performance and stability, and fixes various design issues from the current [Pages Server v2](https://codeberg.org/Codeberg/pages-server). Unfortunately, these fixed design issues require some migration and deprecation of features. @@ -13,27 +26,59 @@ It improves performance and stability, and fixes various design issues from the Please be aware of the following changes and deprecated features. -* The recommended way to deploy websites is by directly uploading them to git-pages. Fallback via a repository called "pages" is available. -* Content is no longer fetched automatically. You need to create a webhook that informs git-pages about changes. +* The recommended way to deploy websites is by directly uploading them to git-pages. +* Content is no longer fetched automatically. You need to use a method that informs git-pages about changes. * `raw.codeberg.page` is no longer available. CORS headers are now directly set on your page and this workaround is no longer necessary. -* Direct access to repos and branches is gone. You can no longer use the `/repository/@branch` access. `git-pages` restricts you to the website you explicitly deployed. Serving arbitrary resources from Codeberg was a common abuse vector and is going to be deprecated. +* Direct access to repos and branches is no longer possible. You can no longer use the `/repository/@branch` access. `git-pages` restricts you to the website you explicitly deployed. Serving arbitrary resources from Codeberg was a common abuse vector and is going to be deprecated. ## The first push -git-pages allows you to migrate without any downtime. Currently, traffic to *.codeberg.page is proxied through git-pages, and as long as it was not instructed to serve your domain, it will forward the traffic to the Pages Server v2. +Git-pages allows you to migrate without any downtime. +Your old v2 Pages deployment will continue working indefinitely. +Once you use one of the new deployment methods, your site will be served by the new server and not by the old one from then on. -As soon as you do the first deployment to the new git-pages, it will take care of your website and will stop forwarding traffic. This change applies per user.codeberg.page or custom domain. If you are currently serving a different site at user.codeberg.page/someproject, it will also vanish once you deploy something to user.codeberg.page for the first time. +Git-pages is engineered to be as compatible with existing v2 Codeberg Pages sites as possible. +Hopefully, you will only need to change the deployment method, and all your existing content will ‘just work’. -## Migration: Pushing pages +{% admonition "tip" %} -This is one of two deployment options for pages. You can now conveniently push the output of static site generators to git-pages without the previous workaround that required you to push changes back to Git repositories on Codeberg.org. +If you want to check that your content is being served with the new server, check the HTTP response headers. If your content is being served by the old server, the `Server` response header will say `pages-server`. +If it is being served by the new server, it will say `git-pages`. -This assumes you already have a workflow that builds your static site, e.g. in a CI workflow. -Replace the step that pushes the output back to a Git repository after the run with one of the options, sorted from most to least convenient: +{% endadmonition %} -* If you are using Forgejo Actions, make use of the [git-pages action](https://codeberg.org/git-pages/action) which will take care of pushing the output to git-pages. -* Use the [`git-pages-cli`}(https://codeberg.org/git-pages/git-pages-cli) to push from your static site generator. -* Use curl to upload the site: `curl https://{domain}/ -X PUT -H "Authorization: Pages {password}" -H "Content-Type: application/..." --data-binary @{archive}`. Replace the content type with one of - * `application/x-tar+zstd` for .tar.zstd. Using [Zstandard](https://facebook.github.io/zstd/) level 0 to 3 is recommended, especially for large sites: it is a very efficient compression algorithm that will likely reduce the total energy used to publish the site. - * `application/x-tar+gzip`: for .tar.gz. - * `application/zip`: for a .zip archive. \ No newline at end of file +## Direct migration of Pages sites using a webhook + +{% admonition "tip" %} + +If you generate your website with a static site generator, you may be more interested in [the next section.](#switching-to-git-pages-forgejo-action) + +{% endadmonition %} + +If you create your website by uploading or pushing files to the `pages` branch directly and manually, you can also migrate to git-pages by setting up a webhook on your repository. +To do this: + +1. Go to **Settings** at the top right of your repository page. + +2. Click **Webhooks** in the sidebar on the left. + +3. Click the **Add webhook** button in the top right corner of the webhook settings page. + + Select **Forgejo** from the drop-down list of webhook types. + +4. Enter `https://username.codeberg.page/repository-name/` as the **Target URL**, replacing the `username` with your Codeberg username or organization name, and `repository-name` with the name of your repository. This is the URL your website will be available from. + + If your repository *and* your branch are both called `pages`, you can omit the `repository-name` and just push to `https://username.codeberg.page/` directly. + +5. Set the **Branch filter** to `pages`. + +6. Click the **Add webhook** button at the bottom of the settings page. + +You’re done! +Next time you push something new to the `pages` branch, the new git-pages server will serve your content instead of the old v2 Pages server. + +## Switching to Git-pages Forgejo Action + +If your `pages` branch is currently generated by pushing the output from a static site generator – especially if this push is triggered by Forgejo Actions – another easy way to migrate is to replace the step in your workflow that pushes your content with a new step that uses the officially supported git-pages Forgejo Action to deploy the site contents directly. + +Information on how to do this is available on [the documentation page on using Forgejo Actions with git-pages.](/codeberg-pages/forgejo-actions/) diff --git a/content/codeberg-pages/pushing-output.md b/content/codeberg-pages/pushing-output.md index 7344a5f..5e67d57 100644 --- a/content/codeberg-pages/pushing-output.md +++ b/content/codeberg-pages/pushing-output.md @@ -4,9 +4,27 @@ eleventyNavigation: title: Pushing output from SSGs into Codeberg Pages parent: CodebergPages author: Fayçal Alami Hassani - https://codeberg.org/ka2in - date: January 2022 - order: 101 + order: 110 --- +{% admonition "Warning" %} + +Codeberg Pages is currently migrating from the legacy v2 codebase to the newer [git-pages](https://git-pages.org/) codebase. + +Currently, websites that use custom domains can only be deployed using the old method, but we are working to fix this. +Such websites will keep working indefinitely. +You will be able to seamlessly migrate to the new version of Pages once it is supported. + +Websites hosted under the `codeberg.page` domain can already use the new git-pages method. + +**This page documents the method used for legacy v2 Pages sites.** +You should be able to adapt the directions for git-pages (assuming you are not using a custom domain) using, for example, the [instructions on using Forgejo Actions with git-pages](/codeberg-pages/forgejo-actions/). + +The new documentation is work in progress. +We hope to update this page with information on how to use the new server directly with static side generators soon. +In the meanwhile, we appreciate your feedback. +Please let us know in case you find yourself confused. + +{% endadmonition %} 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. diff --git a/content/codeberg-pages/redirects.md b/content/codeberg-pages/redirects.md deleted file mode 100644 index 754f5fa..0000000 --- a/content/codeberg-pages/redirects.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -eleventyNavigation: - key: Redirects - title: Redirects - parent: CodebergPages - order: 102 ---- - -Redirects can be created with a `_redirects` file with the following format: - -```text -# Comment -from to [status] -``` - -- Lines starting with `#` are ignored -- `from` - the path to redirect from (Note: repository and branch names are removed from request URLs) -- `to` - the path or URL to redirect to -- `status` - status code to use when redirecting (default 301) - -## Status codes - -- `200` - returns content from specified path (no external URLs) without changing the URL (rewrite) -- `301` - Moved Permanently (Permanent redirect) -- `302` - Found (Temporary redirect) - -## Examples - -### Simple redirect - -Redirects a specific path. - -```text -/example https://example.com/ 301 -/path /other-path 301 -``` - -### SPA (single-page application) rewrite - -Redirects all paths to `/index.html` for single-page apps. - -```text -/* /index.html 200 -``` - -### Splats - -Redirects every path under `/articles` to `/posts` while keeping the path. - -```text -/articles/* /posts/:splat 302 -``` - -Example: `/articles/2022/10/12/post-1/` -> `/posts/2022/10/12/post-1/` diff --git a/content/codeberg-pages/troubleshooting.md b/content/codeberg-pages/troubleshooting.md index 80e52d4..b310b01 100644 --- a/content/codeberg-pages/troubleshooting.md +++ b/content/codeberg-pages/troubleshooting.md @@ -16,7 +16,7 @@ Use the alternative URL as a workaround ## My content is not updated -The Codeberg Pages server caches files under a certain size (currently 1 MiB). +The Codeberg Pages v2 server caches files under a certain size (currently 1 MiB). Please wait a few minutes until the cache has been invalidated. This is done to improve performance, reduce cost and server load, and save energy. diff --git a/content/codeberg-pages/using-custom-domain.md b/content/codeberg-pages/using-custom-domain.md index b4080f1..c12cc91 100644 --- a/content/codeberg-pages/using-custom-domain.md +++ b/content/codeberg-pages/using-custom-domain.md @@ -1,10 +1,23 @@ --- eleventyNavigation: key: UsingCustomDomains - title: Using Custom Domains + title: Using custom domains parent: CodebergPages order: 10 --- +{% admonition "Warning" %} + +Codeberg Pages is currently migrating from the legacy v2 codebase to the newer [git-pages](https://git-pages.org/) codebase. + +Currently, websites that use custom domains can only be deployed using the old method, but we are working to fix this. +Such websites will keep working indefinitely. +You will be able to seamlessly migrate to the new version of Pages once it is supported. + +Websites hosted under the `codeberg.page` domain can already use the new git-pages method. + +The new documentation is work in progress, and we appreciate your feedback. Please let us know in case you find yourself confused. + +{% endadmonition %} Instead of using the `codeberg.page` domain, you can also purchase your own domain from a domain registrar of your choice and configure it to serve content from Codeberg Pages.