Deploy Your Astro Project to Codeberg Pages

What you'll need:

• An Astro project that doesn't use SSR
• git
• A Codeberg account
• A pages branch or repository
• A directory that will host all the required files inside your project (don't create it yet)

I’ll call the host directory pages from here on. Additionally, I will add a README.md and a .domains to it. I recommend at least adding the README.md as well.

The goal is to build the project and copy all the files from the outDir into the pages directory. By default, the outDir is dist.

Doing everything by hand each time is cumbersome. Change the build command inside package.json to copy everything you need. On Windows, change cp -r in the following example to copy.

Inside your package.json change

"build": "astro build",

to

"build": "astro build && cp -r README.md .domains dist/. pages",

or even better

"build": "astro build",
"postbuild": "cp -r README.md .domains dist/. pages",

In this case, the cp command copies everything mentioned into the pages directory. The -r flag indicates recursive copying, making it possible to copy the contents of dist as well. You only need -r for directories, as the cp command can’t copy their contents without it.

If you don’t have a README.md or .domains file or do not want to copy them, omit them from the script.

Now running the build command will copy the files into the pages directory. The postbuild command will execute on its own after building.

Your package.json scripts should look like this:

"scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "postbuild": "cp -r README.md .domains dist/. pages",
    "preview": "astro preview",
    "astro": "astro"
},

But can’t I change the outDir to be pages?

You could, but you shouldn't. The pages directory will become a git branch or repository. Building the project replaces everything inside the outDir, removing the git initialization. You’d have to reinitialize it each time you run the build command. Using another directory and copying everything into it is easier.

Using a pages Repository

To use a separate pages repository, create it first. Now initialize the pages directory as a git submodule, with that repository as the origin.

A git submodule is nothing more than a git repository inside another. This way, the pages repository will be inside your original project.

Before running the command, a pages directory shouldn't exist at the root of your project. Also, replace the username with your own.

Add the pages repository to your project with:

git submodule add https://codeberg.org/username/pages.git

That’s it! Run your build command and switch to your new pages directory. At last, commit and push your changes.

Using a pages Branch

To use a pages branch, all you'll have to do is add the pages directory to the git worktree of your project. With it, you can access other branches without switching to them.

Run the following command to add the pages branch to your projects worktree

git worktree add pages

If, before running this command, you had no pages branch, it copies the contents of your main one. Make sure to clear the pages directory before running the build command! Otherwise, it will contain unneeded files inside.

That’s it! Run your build command and switch to your new pages directory. At last, commit and push your changes.

For more information, check out the Codeberg Pages article in the docs!

Extra: TailwindCSS styles aren't applied

Change the Astro config to always use inlineStylesheets when building.

// astro.config.mjs
export default defineConfig({
    site: ...,
    build: {
        inlineStylesheets: 'always'
    },
    integrations: [
    ...
    ]
});