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..fceb7c6 --- /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://${{ 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 %} + diff --git a/content/codeberg-pages/index.md b/content/codeberg-pages/index.md index 8088282..4dd54c1 100644 --- a/content/codeberg-pages/index.md +++ b/content/codeberg-pages/index.md @@ -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. diff --git a/content/codeberg-pages/migrating-from-pages-v2.md b/content/codeberg-pages/migrating-from-pages-v2.md new file mode 100644 index 0000000..abe4bc7 --- /dev/null +++ b/content/codeberg-pages/migrating-from-pages-v2.md @@ -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/) diff --git a/content/codeberg-pages/pushing-output.md b/content/codeberg-pages/pushing-output.md index 7344a5f..009f55c 100644 --- a/content/codeberg-pages/pushing-output.md +++ b/content/codeberg-pages/pushing-output.md @@ -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. 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..41f5fe8 100644 --- a/content/codeberg-pages/using-custom-domain.md +++ b/content/codeberg-pages/using-custom-domain.md @@ -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.