Astro - Starten mit einem Theme

Verwendung von Themes in Astro, einem JavaScript Framework für statische Webseiten.

Astro ist ein JavaScript Framework für statische Webseiten. Ein Astro Theme ist eigentlich eine fertige Website, die man als Template verwenden kann. Man wird daher wohl meist mit einem Theme starten und nur kleinere Anpassungen durchführen. Somit kommt man schnell dazu, sich auf die Inhalte zu konzentrieren, die man veröffentlichen will.

Die grundlegenden Konzepte von Astro, wie man damit startet, wie man Komponenten und ein Layout erstellt, das wurde im Artikel Astro Einführung erklärt. Im Artikel Astro - Meine Meinung erfährt man, warum ich Astro nun für Webseiten verwende und wie Astro sich in die vielen Frameworks einreiht.

Astro eignet sich hervorragend für Webseiten mit dem Schwerpunkt auf Content, also Blogs oder Landing Pages, die meist mit Content Management Systemen generiert werden. Doch Astro ist sehr offen und gibt wenig Struktur vor, auch aus diesem Grund ist es eine gute Idee sich von einem Template inspirieren zu lassen.

Theme auswählen

Astro listet auf ihrer Homepage die einzelnen Themes auf.

Klickt man auf eine Theme Kachel, dann bekommt man meist eine Vorschau Site, auf der dann auch ein Button Get Template oder einen Link zum GitHub Repository eingefügt wurde.

Es gibt noch sehr wenige Themes, manche sind auch kostenpflichtig. Die Doku (meist als GitHub Readme Datei vorhanden) ist auch hilfreich, um zu sehen, welche Komponenten mit dem Theme zur Verfügung stehen. Interessant sind auch, welche Integrationen (Liste aller Astro Integrations) dazugefügt wurden. Falls dies nicht dokumentiert ist, kann man sich das Astro Config File ansehen (astro.config.mjs).

Es soll hier keine Empfehlung für ein Theme ausgesprochen werden. Man wird eine ähnlich aussehende Seite suchen, wie man sie am Ende haben will. Welche Features, welche zusätzlichen Technologien werden eingeführt und hat man damit Erfahrung, das sind zusätzliche Entscheidungskriterien.
Bedenken sollte man auch, dass bei einem größeren Astro Update, einem das ausgewählte Theme die Arbeit womöglich abnimmt. Daher ist es wichtig, dass man ein aktives Theme auswählt, bei dem Aktualisierungen in letzter Zeit durchgeführt wurden.

Ich verwende das Theme AstroWind:

Repository importieren

Um später Änderungen im Template/Theme AstroWind in das eigene Repo einfacher zu mergen, verknüpft man das eigene Repo mit dem Template. Dazu erstellt man das neue Repository, indem man am Template Repository auf den Button Use this template klickt.

GitHub Use this Template

Ich habe mein Repo dann my-site genannt und auf private gesetzt: GitHub Import Dialog

Nun das neue Repo auschecken und die ursprüngliche Adresse als remote hinzufügen:

git clone https://github.com/FranzHelm/site-my-astrowind.git
cd .\site-my-astrowind\
git remote add template https://github.com/onwidget/astrowind

Updaten

Dadurch kann man jetzt mit seinem Repository arbeiten und es auch nach GitHub pushen und später kann man das ursprüngliche Template, also das Theme AstroWind, falls es aktualisiert wurde, wieder reinmergen. Das geht dann mit folgenden Commands:

git fetch template
git checkout <branch-to-merge-to>
git merge template/<branch-to-merge>

Beispiel mit ausgefüllten Branch-Namen (Hier wird zusätzlich auch ein neuer Branch angelegt.):

git fetch template
git checkout -b update-to-new-astrowind
git merge template/main

Abhilfe wenn folgender Fehler angezeigt wird:
  fatal: refusing to merge unrelated histories
git merge template/main --allow-unrelated-histories

Anmerkungen

  1. Man könnte statt merge auch rebase verwenden:
git rebase upstream/<branch-to-merge>
git push origin <branch-name> --force
  1. Alternativen zum Erstellen vom Template (GitHub Hilfe: Create a Repository from a Template) wäre mit GitHub import zu starten oder man könnte auch fork verwenden, da das Template Repository ja nicht ein eigenes GitHub Repo ist.

Entwicklung und Deployment

Hier nur eine kurze Zusammenfassung, wie man ein Astro Projekt anpasst, buildet und deployed. Details dazu findet man in meinem Artikel: Astro Einführung oder in den Astro Docs auf der Astro Homepage.

Astro verwendet Node.js. Ich verwende zunächst npm um alle nötigen Libraries, aufgelistet im package.json, zu installieren (dazu gehören natürlich viele JavaScript Libraries von Astro selbst).

npm install

Anpassungen

Während der Entwicklung einer Seite verwendet man npm start, dass einen lokalen WebServer betreibt und bei Änderungen in den Dateien, wird der Build Prozess intern getriggert, sodass man schnell das Ergebnis in einem Browser ansehen kann (http://localhost:3000/).

npm start

Build und Deploy

Will man die Seite nun auf einem Webserver hosten lassen, dann muss man zunächst das Projekt builden. Dieser Buildvorgang kompiliert jetzt nicht einfach TypeScript in JavaScript, sondern es werden HTML Seiten erzeugt (inklusive aller Assets wie Bilder, CSS, JavaScript, Fonts, …). Dabei können auch z.B. Bilder in der Größe angepasst werden oder zusätzliche Files, wie z.B. eine Sitemap, ein RSS Feed, usw. generiert werden.

npm run build

Das Ergebnis findet man im Ordner dist.

Dort sind nun alle Dateien, die man jetzt auf einem WebServer hochladen würde, um sie zu hosten.

Anpassungen und Content erstellen mit Theme AstroWind

Da wir nun wissen, wie man die Seite erstellen kann, beginnen wir Anpassungen durchzuführen, um dann die Seite mit den eigenen Inhalten zu füllen. Natürlich ist jedes Theme anders aufgebaut, doch ähnliche Konstrukte findet man überall. Hier beziehe ich mich auf das Theme AstroWind (in der Version 0.4.1).

Anpassungen

Globale Settings

AstroWind definiert ein eigenes config file: src\config.mjs, indem man globale Settings zu seiner Seite, wie den Namen usw. konfigurieren kann.

Komponenten

Dieses Theme AstroWind ist sehr schön unterteilt in Komponenten und man findet sich sehr schnell zurecht. Anpassungen sind fast immer in nur einer Datei durchzuführen und diese werden in allen Seiten richtig angezeigt. Ein gutes Beispiel dafür ist der Footer (src\components\widgets\Footer.astro).

Layout und CSS

Layout Komponenten (zu finden unter src/layouts) sind auch nur Astro Files, die einen speziellen Tag (<slot />) enthalten, der als Platzhalter für den Inhalt dient. Diese einzelnen Layout Files können angepasst werden, oder man erstellt daneben eigene Layouts Dateien.

Das Styling kann in jeder Komponente in einem <style>-Tag erfolgen oder man inkludiert ein CSS File. Bei AstroWind gibt es nur ein CSS file: src\assets\styles\base.css. Hier kann man seine eigenen globalen Style Anpassungen durchführen oder man legt zusätzlich ein CSS File daneben an und inkludiert dieses im base layout file (src\layouts\BaseLayout.astro).

Images

Bilder die angepasst werden und daher in den Komponenten verarbeitet werden müssen, legt man nach src/assets/images. Bilder die unangepasst gehostet werden sollen, werden in den public Ordner abgelegt.

Content erstellen

Die Inhalte, wie die Blog Artikel erstellt man in Markdown unter data/blog.

Die mitgelieferten Beispielseiten will man vermutlich nicht ausliefern, man kann sie entfernen oder man kennzeichnet sie nur, dass sie nicht gelistet werden. Dies hat den Vorteil, dass bei einem Update, Änderungen besser sichtbar werden. Dazu fügt man in den Frontmatter Bereich der Markdown Files draft: true ein:

---
publishDate: "Aug 02 2022"
title: "Markdown elements demo post"
...
draft: true
---

Das Theme AstroWind berücksichtigt dieses Property und zeigt diese so markierten Dateien nicht an.

Fazit

Um eine Anpassung an diversen Stellen kommt man nicht umhin, da man vermutlich nicht alles so haben will, wie es einem der Theme vorgibt. Doch der Vorteil mit einer fertigen Struktur zu starten ist sehr groß. Man kann sich viel abschauen, manche Teile einfach auskommentieren und durch die meist tolle Gliederung kommt man auch schnell auf gute Ergebnisse. Natürlich wäre es praktischer, wenn man alle Anpassungen in Konfigurationsfiles machen könnte und somit ein Update des Themes leichter wäre, doch man würde die Flexibilität verlieren. Indem man sich schon beim Starten Gedanken macht, wie ein Update Szenario des Themes aussieht, kann man hoffentlich allzu große Probleme vermeiden.

HLC-astro-theme-twitter


Artikel in diesem Blog


Weitere Astro Artikel.