Blog mit Astro & Cloudflare Pages deployen – mein Setup 2026

Bisher hatte ich Websites hauptsächlich mit Wordpress gehostet. Aber wollte ich mir das wirklich wieder antun?

Warum ich mich gegen Wordpress entschieden habe#

Für einen einfachen Blog hat mir Wordpress einfach viel zu viel Overhead:

• PHP notwendig
• MySQL Datenbank erforderlich
• bringt eine API mit
• Admin Backend mit Login
• umfangreiche .htaccess um die Website zu schützen
• zusätzlich noch Plugins für alles mögliche:
  • Multilanguage
  • Image Optimizer
  • Caching
  • SEO
  • Kontaktformular
  • Suche
  • Security Plugins, um die Sicherheitslücken von anderen Plugins wieder zu stopfen
  • usw.

Das Ganze muss dann natürlich gewartet, regelmäßig Updates eingespielt und immer wieder Anpassungen vorgenommen werden. Bei jedem dritten Update geht dann wieder etwas anderes kaputt und man muss nach Fixes und Workarounds suchen.

Auf all das hatte ich keine Lust und so hab ich mich nach Alternativen umgesehen.

Static Site Generatoren als Alternative#

Von GitLab / GitHub Pages kannte ich schon Static Site Generatoren wie Hugo. Mit ihnen gearbeitet hatte ich aber noch nicht wirklich.

Also habe ich mir neben Hugo noch ein paar andere Tools und zugehörige Themes angesehen und bin dann letztendlich bei Astro und dem relativ neuen Velocity Theme von Southwellmedia hängen geblieben. Weshalb ich mich für Astro und gegen Hugo entschieden habe kann ich gar nicht genau sagen. Mir haben persönlich die Demo Themes besser gefallen. Technisch und von der ganzen Vorgehensweise ähneln sich die beiden ziemlich.

Astro & das Velocity Theme#

Beides ist komplett Open Source und bringt alles mit, was ich an Anforderungen hatte:

• kein CMS mit Backend etc.
• keine Datenbank notwendig
• Multilanguage fähig
• einfach anzupassen
• Image Optimization integriert
• SEO
• Suche
• klein und schnell

Das Theme hat die i18n Funktionalität von Astro schon integriert, so dass ich das nicht mehr einbauen musste. In Lighthouse erreicht die Demo Seite 100 von 100 Punkten.

Ich musste somit nur Änderungen am Design vornehmen und ein paar Funktionen auf meine Bedürfnisse anpassen. Mit der umfangreichen Dokumentation, viel Trial & Error und etwas Hilfe von Claude war das aber in ein paar Abenden machbar 😅

Folgende Funktionen habe ich hinzugefügt:

• Copy Button in Code Blocks (rehype Plugin)
• Reading Progress Bar
• Reading Time
• Prev/Next Navigation zwischen Posts
• Typewriter-Effekt auf der Homepage
• Language Toggle mit Erkennung der Browsersprache und Cookie Speicherung

Wenn der Unterbau erstmal steht, ist das Hinzufügen von Content ganz einfach. Posts werden einfach in Markdown verfasst:

---
title: "Test Post"
description: "Post description"
publishedAt: 2026-04-01
updatedAt: 2026-04-15 # optional
author: "Tobi"
image: ./image.jpg # optional
imageAlt: "Image description" # optional
tags: # optional
  - astro
  - tutorial
draft: true # optional
featured: false # optional
locale: en # optional
---
# start writing in markdown here.

Beim Build wird dann alles in HTML gerendert und im Output Ordner landet eine simple Static Website Struktur, die mit jedem x-beliebigen Webserver gehostet werden kann.

Quickstart: Projekt aufsetzen#

Das Velocity Theme arbeitet mit dem Paketmanager pnpm.
pnpm kann einfach über npm installiert werden:

npm install -g pnpm@latest

Als ersten Schritt das Demo Projekt vom Quick Start zu erstellen ist denkbar einfach:

1. Repo über das Velocity Cli erstellen.

pnpm create velocity-astro my-project

2. Ins Projektverzeichnis wechseln und Dev Server starten.

cd my-project
pnpm dev

Anschließend kann die Demo Seite im Browser über http://localhost:4321/ aufgerufen werden.

Für den richtigen Build muss noch die Env Datei angelegt werden und die Site URL konfiguriert werden:

cp .env.example .env

Darin die Variable entsprechend konfigurieren, z.B.:

SITE_URL=https://homelabdiary.dev

Nun kann der Build durchgeführt werden:

pnpm build

Im Ordner dist befindet sich anschließend die generierte Website Struktur. Diese muss jetzt nur noch mit einem Webserver bereit gestellt werden.

Hosting mit Cloudflare Pages#

Ich hoste meinen Blog mit dem Free Plan von Cloudflare Pages. Es gibt zwei Wege, um eine Website via Cloudflare Pages zu veröffentlichen:

1. Man kann Cloudflare einfach mit einem GitHub oder GitLab Repo verbinden. Wird auf den Main Branch ein Push durchgeführt, übernimmt Cloudflare den Build und stellt den generierten Output bereit. Im Free Plan sind 500 Builds im Monat inbegriffen.

2. Alternativ kann man den Build auch selbst durchführen und den Output entweder im Cloudflare Dashboard manuell hochladen oder via Wrangler automatisiert deployen.

Ich habe mich für den zweiten Weg entschieden, da ich meinen eigenen Forgejo Server und einen entsprechenden Runner zu Hause hoste.

Bei jedem Push auf den main Branch wird eine Forgejo Action (kompatibel zu GitHub Actions) ausgeführt, welche das Projekt baut und zu Cloudflare deployed.

Die deploy.yml für den Workflow sieht so aus:

name: Deploy to Cloudflare Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: debian-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install pnpm
        uses: pnpm/action-setup@v4
        with:
          version: latest

      - name: Install dependencies
        run: pnpm install

      - name: Build
        run: pnpm build
        env:
          SITE_URL: https://homelabdiary.dev

      - name: Deploy to Cloudflare Pages
        run: npx wrangler pages deploy dist --project-name=homelabdiary --branch=main
        env:
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Die beiden Variablen CLOUDFLARE_ACCOUNT_ID und CLOUDFLARE_API_TOKEN sind im Repo als Secrets hinterlegt.

Neuen Post veröffentlichen#

Wenn ich nun einen neuen Post veröffentlichen möchte, ist der Workflow eigentlich ganz einfach:

• neue Markdown Datei im entsprechenden Pfad anlegen & mit Inhalt befüllen
• git add --all
• git commit -m 'new post'
• git push origin main

Anschließend wird das Projekt automatisch gebaut, zu Cloudflare deployed und unter https://homelabdiary.dev veröffentlicht.

Das ist genau der Workflow, den ich wollte: schlank, wartungsarm und (in der Regel) ohne Überraschungen.♥️