mirror of
https://codeberg.org/Codeberg/Documentation.git
synced 2026-06-16 05:13:54 -07:00
Git Pages docs rework (#708)
Co-authored-by: Daphne Preston-Kendal <git@dpk.io> Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/708 Co-authored-by: fnetX <otto@codeberg.org> Co-committed-by: fnetX <otto@codeberg.org>
This commit is contained in:
fnetX
Daphne Preston-Kendal
parent
e7f3ce7f86
commit
f671f8946c
9 changed files with 333 additions and 367 deletions
65
content/codeberg-pages/advanced-usage.md
Normal file
65
content/codeberg-pages/advanced-usage.md
Normal file
|
|
@ -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/`
|
||||
|
|
@ -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
|
||||
```
|
||||
|
||||
<a name="mydocs"></a>
|
||||
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:
|
||||
|
||||
<a name="build"></a>
|
||||
|
||||
```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/).
|
||||
60
content/codeberg-pages/forgejo-actions.md
Normal file
60
content/codeberg-pages/forgejo-actions.md
Normal file
|
|
@ -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://${{ forge.repository_owner }}.codeberg.page/repository-name/"
|
||||
token: ${{ forge.token }}
|
||||
source: _site/
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
Replace `repository-name` in the `site` parameter 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 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 %}
|
||||
|
||||
|
|
@ -8,32 +8,31 @@ eleventyNavigation:
|
|||
|
||||
{% admonition "Warning" %}
|
||||
|
||||
Codeberg Pages is currently provided with a best effort approach.
|
||||
To be exact, the software behind this feature is currently in [maintenance mode](https://codeberg.org/Codeberg/pages-server/issues/399).
|
||||
Codeberg Pages is currently migrating from the legacy v2 codebase to the newer [git-pages](https://git-pages.org/) codebase.
|
||||
|
||||
Please do not rely on it for critical websites, as we can't guarantee high availability like some other providers do.
|
||||
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.
|
||||
Take note of some minor [changes and deprecations](/codeberg-pages/migrating-from-pages-v2/#breaking-changes-and-deprecations).
|
||||
|
||||
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`)
|
||||
via Git on Codeberg.
|
||||
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. You should now be able to access your content by visiting `{username}.codeberg.page`.
|
||||
|
||||
---
|
||||
|
||||
This project is developed "in-house" by Codeberg. You can find [the source code in our repository](https://codeberg.org/Codeberg/pages-server/).
|
||||
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.
|
||||
Git-pages works with any Forgejo host out there, as well as many other Git forges.
|
||||
If you are running your own forge, you can also run it yourself and help with the development.
|
||||
|
||||
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 %}
|
||||
|
|
@ -56,41 +55,86 @@ See also:
|
|||
{% endif %}
|
||||
{%- endfor %}
|
||||
|
||||
## Advanced Usage: Canonical URLs
|
||||
## Getting started with a `codeberg.page` URL
|
||||
|
||||
The Codeberg Pages server responds to four different URLs:
|
||||
There are two ways to get started with Codeberg Pages on git-pages:
|
||||
|
||||
- `https://raw.codeberg.page/username/reponame/`: raw content, uses correct MIME types (HTML is forbidden though)
|
||||
and is accessible with CORS.
|
||||
- `https://username.codeberg.page`: user page, points the default branch of a user's or organization's `pages` repository
|
||||
- `https://username.codeberg.page/reponame/`: repo page, points to the `pages` branch of the repository
|
||||
- `https://example.org`: custom domain, points to a repo of choice as outlined below
|
||||
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
|
||||
|
||||
In all cases, you can append a branch using an `@` (e.g. `https://username.codeberg.page/@develop/README.md`).
|
||||
If the branch name contains a slash (`/`), they need to be replaced with a tilde (`~`) (e.g. the branch `docs/develop`
|
||||
can be accessed via `https://username.codeberg.page/@docs~develop/README.md`).
|
||||
This page documents the first method. See the [separate page on using Forgejo Actions](/codeberg-pages/forgejo-actions/) for information on the second method.
|
||||
|
||||
## Advanced Usage: Custom error page for 404s
|
||||
### User/organization websites
|
||||
|
||||
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. Create a repository called `pages` under your own username or under the organization you want to create a website for
|
||||
|
||||
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.
|
||||
The website will be published from a branch also called `pages`. You can also set this as the default branch, if you prefer.
|
||||
|
||||
From then on, your `404.html` file will be served when the error is encountered.
|
||||
2. Go to **Settings** at the top right of your repository page.
|
||||
|
||||
## Do you have questions, feedback or have you found a bug?
|
||||
3. Click **Webhooks** in the sidebar on the left.
|
||||
|
||||
The source code for Codeberg Pages is maintained over at the [Pages Server repository](https://codeberg.org/Codeberg/pages-server);
|
||||
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.
|
||||
|
|
|
|||
86
content/codeberg-pages/migrating-from-pages-v2.md
Normal file
86
content/codeberg-pages/migrating-from-pages-v2.md
Normal file
|
|
@ -0,0 +1,86 @@
|
|||
---
|
||||
eleventyNavigation:
|
||||
key: Migrating from Pages v2
|
||||
title: Migrating from Pages v2
|
||||
parent: CodebergPages
|
||||
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.
|
||||
Take note of some minor [changes and deprecations](/codeberg-pages/migrating-from-pages-v2/#breaking-changes-and-deprecations).
|
||||
|
||||
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.
|
||||
|
||||
## Breaking changes and deprecations
|
||||
|
||||
Please be aware of the following changes and deprecated features.
|
||||
|
||||
* 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 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.
|
||||
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.
|
||||
|
||||
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’.
|
||||
|
||||
{% admonition "tip" %}
|
||||
|
||||
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, there will be a `Server` response header saying `pages-server`.
|
||||
If it is being served by the new server, it will say `git-pages` only.
|
||||
|
||||
{% endadmonition %}
|
||||
|
||||
## 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/)
|
||||
|
|
@ -4,9 +4,28 @@ 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.
|
||||
Take note of some minor [changes and deprecations](/codeberg-pages/migrating-from-pages-v2/#breaking-changes-and-deprecations).
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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/`
|
||||
|
|
@ -16,7 +16,7 @@ Use the alternative URL <https://pages.codeberg.org/user.name/> 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,24 @@
|
|||
---
|
||||
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.
|
||||
Take note of some minor [changes and deprecations](/codeberg-pages/migrating-from-pages-v2/#breaking-changes-and-deprecations).
|
||||
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue