In this tutorial we'll see how to setup Eleventy (11ty) as a website and blog engine. Create a Codeberg repository and upload your code on it. Use Codeberg continuous integration (CI) to automatically build 11ty and host your website with Codeberg Pages.

Requirements

You can check your Node.js version by passing the -v option:

node -v
v20.14.0

Same for npm:

npm -v
10.7.0

Note that while Eleventy requires Node.js 14 minimum, I recommend keeping up with the latest Long Term Support (LTS) version for security, performances and stability.

Eleventy (11ty)

As per the project website and their GitHub repository:

A simpler static site generator. An alternative to Jekyll. Written in JavaScript. Transforms a directory of templates (of varying types) into HTML.

Make a Project Directory

Create a directory for your project using the mkdir command (short for make directory):

mkdir eleventy-sample

Now move into that directory with the cd command (short for change directory):

cd eleventy-sample

Install Eleventy

Create a package.json

Installing Eleventy into a project requires a package.json file. The npm command (provided by Node.js) will create one for you with npm init -y.

-y tells npm to use default values and skips the command line questionnaire.

npm init -y

Install Eleventy

@11ty/eleventy is published on npm and we can install and save it into our project’s package.json by running:

npm install @11ty/eleventy --save-dev

Run Eleventy

We can use the npx command (also provided by Node.js) to run your local project's version of Eleventy. Let’s make sure your installation went okay and try to run Eleventy:

npx @11ty/eleventy

Here’s what your command line might look like after you run Eleventy:

npx @11ty/eleventy
[11ty] Wrote 0 files in 0.03 seconds

Eleventy didn’t process any files! This is expected—we have an empty folder with no templates inside.

Create some templates

A template is a content file written in a format such as Markdown, HTML, Liquid, Nunjucks, and more, which Eleventy transforms into a page (or pages) when building our site.

Let’s run two commands to create two new template files.

echo '<!doctype html><title>Page title</title><p>Hi</p>' > index.html
echo '# Page header' > README.md

Alternatively, you can create these using any text editor. Just make sure you save them into your project folder and they have the correct file extensions.

After you’ve created an HTML template and a Markdown template, let’s run Eleventy again with the following command:

npx @11ty/eleventy

The output might look like this:

npx @11ty/eleventy
[11ty] Writing _site/README/index.html from ./README.md (liquid)
[11ty] Writing _site/index.html from ./index.html (liquid)
[11ty] Wrote 2 files in 0.04 seconds

We’ve compiled our two content templates in the current directory into the output folder (_site/ is the default).

Gaze upon your templates

Use --serve to start up a hot-reloading local web server.

npx @11ty/eleventy --serve

Your command line might look something like:

npx @11ty/eleventy --serve
[11ty] Writing _site/index.html from ./index.html (liquid)
[11ty] Writing _site/README/index.html from ./README.md (liquid)
[11ty] Wrote 2 files in 0.04 seconds (v2.0.0)
[11ty] Watching…
[11ty] Server at http://localhost:8080/

Open http://localhost:8080/ or http://localhost:8080/README/ in your favorite web browser to see your Eleventy site live! When you save your template files, Eleventy will refresh the browser with your new changes automatically!

Codeberg

As per the project website:

A collaboration platform providing Git hosting and services for free and open source software, content and projects. It's based on Forgejo, an open source software forge, which they fund and develop.

Repository

Account & repository creation

You'll need to register an account and then create a new Git repository. Give it a name and leave the other default fields as is. Note the repository must be public.

Initialize Git on your Project Directory

Initialize git in the directory you created before:

git init

Create the main branch and add your content

First, the main branch has to be created:

git checkout -b main

Add a .gitignore file

We'll need to keep some directories away from Git tracking. You can customize and use this template of mine, vim .gitignore:

# --->  Project build
_site/

# ---> Node
# Logs
logs
*.log
npm-debug.log*

# Dependency directories
node_modules/

# Optional npm cache directory
.npm

Add your content and write the first commit

Then, you should start tracking your code with Git:

git add -A

And write your first commit:

git commit -m "first commit"

Add the remote and do the initial push

This is where you define the remote server which will host your Git repository. Replace $USER with your Codeberg username and $REPO by your repository name:

git remote add origin git@codeberg.org:$USER/$REPO.git

Let's now push your code:

git push -u origin main

Pages

Custom domain setup

Create a .domains file with this content:

example.org
$USER.codeberg.page
$REPO.$USER.codeberg.page
pages.$REPO.$USER.codeberg.page

Copy it to the _site directory:

cp .domains _site/

In the meantime you also need to add the appropriate entries to your custom domain DNS zone file:

@ 10800 IN A  217.197.91.145
@ 10800 IN AAAA 2001:67c:1401:20f0::1
@ 10800 IN TXT "pages.$REPO.$USER.codeberg.page."
www 10800 IN CNAME example.org.

Move in your build directory

Use cd to move into your _site/ directory:

cd _site

Initialize Git

Initialize git in the build directory as well:

git init

Create the pages branch and add your content

The pages branch which will be used to host your website has to be created:

git checkout -b pages

Add your content and write the first commit

Then, you should start tracking your website content with Git:

git add -A

And write your first commit:

git commit -m "first commit"

Add the remote and do the initial push

Use the same remote server that host your project Git repository:

git remote add origin git@codeberg.org:$USER/$REPO.git

Push your website content:

git push -u origin pages

After waiting a few minutes, for the TLS certificates generation from Codeberg Pages systems and for the DNS propagation, you should be able to access your website at https://example.org.

Woodpecker CI

Learn more about Codeberg's Woodpecker CI instance on their dedicated documentation page.

Request access

As mentioned on the previous linked page, you have to fill out a form to request access to the Woodpecker instance.

Don't be hasty, it has to be approved by a human. In my case I got an answer in the next 48 hours. While waiting, you can carry on with the following steps.

Create the .woodpecker.yml configuration file

From the _site/ directory, go back to your main repository:

cd ..

Woodpecker will look for a configuration file at the root of your repository. You can use this template, vim .woodpecker.yml:

steps:
  build:
    when:
      event: push
    image: node
    secrets: [ token, email, user, repo ]
    commands:
      # Avoid permission denied errors
      - chmod -R a+w .
      # Set up git in a working way
      - git config --global --add safe.directory /woodpecker/src/codeberg.org/$USER/$REPO/_site
      - git config --global user.email "$EMAIL"
      - git config --global user.name "CI Builder"
      # clone and move the target repo
      - git clone -b pages https://codeberg.org/$USER/$REPO.git _site
      - chmod -R a+w _site
      - cd _site
      # Prepare for push
      - git remote set-url origin https://$TOKEN@codeberg.org/$USER/$REPO.git
      - cd ..
      # Run 11ty build stage
      - npm install
      - npm run build
      # Only needed for custom domains
      - cp .domains _site/
      # Push to target
      - cd _site
      - git add -A
      - git commit -m "Woodpecker CI 11ty Build at $( env TZ=Europe/Paris date +"%Y-%m-%d %X %Z" )"
      - git push -u origin pages

Generate an access token for your account

As you can see on the previous example file, you'll need a token for Woodpecker to be able to push on your repository.

You can get it from https://codeberg.org/user/settings/applications:

  1. Give the token a name, like "Woodpecker CI"
  2. Switch from "All" to "Public only" for Repository and Organization Access
  3. Choose "Read and write" as repository permissions
  4. Click the blue Generate token button

Note down the generated token, as indicated it won't be shown to you again.

Setup Woodpecker on your repository

As soon as you get access to it, login on https://ci.codeberg.org.

  1. Click the + Add repository button on the right
  2. Select your repository in the list and click the Enable button
  3. You are now redirected to its page, click the cog wheel button on the right
  4. Go to the Secrets tab and click the + Add secret button
  5. Create each needed ones by entering their Name and Value:
    • token, the one you noted down previously
    • email, the email linked to your Codeberg account, used to sign commits
    • user, your Codeberg username
    • repo, the repository name

When all secrets are added, setting up Woodpecker should be done. It's time to try your new automated build setup!

Test the continuous integration

Add one more line to your index.html template:

echo '<p>CI works!</p>' >> index.html

Add and commit your changes:

git add .woodpecker.yml index.html
git commit -m "try continuous integration"

Push them to automatically trigger a Woodpecker job:

git push -u origin main

You can follow the build run for your repository from Codeberg CI. If the build fails, look at the logs from the web interface and diagnose the issue.

If everything works as expected, your website should be built into the _site folder, which is a sub-repository working on a dedicated branch. The changes pushed to the pages branch should be avaible and can be seen on https://codeberg.org/$USER/$REPO/src/branch/pages.

Wrapping up

Here is how you can setup Codeberg continuous integration to build your Eleventy website on a single Git repository! For a more in-depth example, check out the sources of this very website you are actually reading.

For more informations please see the following documentation:

Tags: english tutorial technology 11ty Codeberg continuous integration