ReadBeanIceCream

Build Your Blog in Open Source

May 04, 2026 | Indie Web, Blogging, Open Source

Last year (almost to the day), I posted how easy setting up a blog is with mkdocs and surge.sh. Well, now that I have migrated this site to Codeberg, I thought I would update that post. Spoiler Alert: It’s still easy.

This time, I am moving away from the click-baity title.

Initial Setup

Install Mkdocs

To get started we must install Mkdocs. I actually prefer Material for Mkdocs.

pip install mkdocs-material

Create Project

Now, we can create our blog project.

mkdocs new blog

Mkdocs will create the following directory structure:

blog
├─ docs/
│  └─ index.md
└─ mkdocs.yml

Setup Your Blog

Open mkdocs.yml and set your site attributes. At minimum, for a blog you must include:

site_name: My site
site_url//username.codeberg.page
theme:
  name: material

plugins:
  - search
  - blog

However, I would recommend adding a RSS feed and some navigation.

plugins:
  - search
  - blog:
      blog_dir: .
      blog_toc: true
      archive: false
      categories: true
      categories_toc: true
      categories_name: Categories
  - rss:
      match_path: posts/.* 
      use_git: false
      date_from_meta:
        as_creation: date.created
      categories:
        - categories

For more information about theme options, see the Material for Mkdocs documentation.

!!! note “Mkdocs-material is being deprecated, so you may want to use Zensical. However, Zensical has one to one parity with mkdocs-material, so all the steps are still valid.”

Set Up Codeberg Pages

Codeberg Pages hosts your site directly from a git repository. Here’s how to get set up:

1. Create a free account at codeberg.org if you don’t have one.

2. Create a new repository named pages. Codeberg will automatically serve it at https://username.codeberg.page.

3. In your local blog directory, initialize git and add your remote:

   git init
   git remote add origin https://codeberg.org/username/pages.git

4. Add a .gitignore to keep things tidy:

   echo "site/" > .gitignore

Codeberg Pages serves from the root of the repository’s default branch. When you deploy, you will push only the contents of the built site/ directory to a dedicated pages branch. Do not include your source files.

!!! info “Codeberg Pages is simple to use and entirely FOSS. The documentation covers custom domains, branch configuration, and more.”

Start Writing

Create a Test Environment

Once you have the initial setup complete, you are ready to start writing. Run mkdocs serve to create a local test environment so you can view your website changes before deploying. Running this command lets you test, play around with options, and be satisfied with the results before publishing.

cd blog
mkdocs serve

Create Your Post

Time to write your first post.

1. In your docs directory, create a posts directory.
2. Go to posts.
3. Create a markdown file and name it with a date: 2025-05-02.md.
4. Write!

As you save your file, the local test environment will render it with your changes. Writing this way makes it really easy to get your post exactly the way you want it. Once you have written your post, you are now ready to publish.

Publish Your Site

Once you are ready to publish your site and/or blog posts:

1. Go to your blog directory: cd blog.

2. Build your site: mkdocs build. This generates your static site in the site/ directory.

3. Enter the built site and push it to Codeberg:

   cd site
   git add .
   git commit -m "Summary of changes"
   git push

4. Enter your Codeberg credentials when prompted.

??? tip “After the first deploy, you can simplify this with a small shell script or alias so publishing really does come down to one command. Expand to view.”

```bash
#!/usr/bin/env bash
# deploy.sh
    
mkdocs build
cd site
git add .
git commit -m "Deploy $(date '+%Y-%m-%d')"
git push
```

Codeberg will detect the push and your site will be live at https://username.codeberg.page within moments.

Easy Blogging with Mkdocs & Codeberg

After the initial setup, you will only have to complete the Start Writing and Publish Your Site steps to keep your blog going. As you get used to the process, you can check out the Material for Mkdocs documentation to add more bells and whistles, such as analytics.

With Mkdocs and Codeberg, blogging couldn’t be easier…unless you were just posting a plain text file.