Mit hugo-cms.nvim loslegen, Site einrichten und erster Beitrag

hugo-cms.nvim lebt komplett in neovim. Die ersten paar Schritte vom leeren Verzeichnis bis zum ersten Beitrag gehe ich hier von vorne durch. Wer noch nie mit Hugo gearbeitet hat, fängt mit dem Hugo-Intro an, hier setze ich voraus, dass hugo installiert ist und Du eine ungefähre Vorstellung davon hast, was eine Hugo-Site ist.

Leader-Tasten kurz vorab

Das Plugin selbst legt keine Tastenkürzel an. Die Befehle laufen alle über :Hugo … und Du kannst sie auf jede Taste binden, die Du magst. Im README-Beispiel hängen sie unter <leader>h…, das nehme ich auch hier durchgängig an: <leader>hn für :Hugo new, <leader>ho für :Hugo open, und so weiter. Welche Buchstaben Du vergibst, ist Dir überlassen.

Hugo-Site anlegen

Eine frische Site startest Du mit hugo new site <name>. Das gibt Dir die Standard-Verzeichnisstruktur und eine hugo.toml (oder hugo.yaml, wenn Du --format yaml anhängst). Theme dazu, üblicherweise als Git-Submodul:

git submodule add --depth=1 https://github.com/<theme-repo> themes/<name>

Theme in der Config aktivieren:

theme: <name>

Mit git init versionieren und einen ersten Commit machen, damit Du was zum Zurückrollen hast. Wenn Du die Config aufgesplittet unter config/_default/ ablegst statt direkt im Projekt-Root, erkennt hugo-cms.nvim das automatisch.

Site beim Plugin registrieren

Im Editor :Hugo site register (<leader>hS). Das Plugin fragt zwei Sachen:

Site path:    ~/sites/myblog
Display name: My Blog

Die erste registrierte Site wird die aktive. Mit :Hugo site switch wechselst Du zwischen registrierten Sites, mit :Hugo site unregister nimmst Du eine wieder raus, ohne dass irgendwas auf der Platte angefasst wird.

:Hugo site ohne Argument öffnet einen Picker mit allen Subkommandos, falls Du Dir die Subkommandos nicht merken willst.

Die Liste der registrierten Sites und alle Pfad-Pattern landen unter $XDG_DATA_HOME/nvim/hugo-cms/sites.json (typisch ~/.local/share/nvim/hugo-cms/sites.json). Wer das Setup auf einen anderen Rechner ziehen will, sichert die Datei.

Archetype, theme-neutral

Archetypes sind die Vorlagen für neue Inhalte, sie liegen unter archetypes/<name>/index.md (oder <name>.md für single-file-Inhalte). hugo-cms.nvim ist archetype-getrieben, das Plugin schreibt nur in Frontmatter-Felder, die im Archetype schon existieren. Theme-spezifische Felder gehören also in den Archetype, nicht in irgendwelche Plugin-Optionen.

Ein solider Blog-Post-Archetype als Bundle (archetypes/post/index.md):

---
title: "{{ replace .File.ContentBaseName "-" " " | title }}"
date: "{{ .Date }}"
draft: true
description: ""
slug: ""
tags: []
categories: []
cover:
  image: ""
  alt: ""
  relative: true
  caption: ""
  hidden: false
---

description ist die Meta-Description für Suchmaschinen und Social-Previews, oft vergessen. Leeres Feld als Erinnerung, das Plugin lässt es sonst in Ruhe. slug ist der URL-Override, im Default-Archetype leer, pro Sprache befüllt sobald Du übersetzt. cover.alt ist Accessibility und SEO in einem, Screenreader und Suchmaschinen lesen den Alt-Text. Das Plugin fragt beim Cover-Setzen nach Alt-Text nur dann, wenn das Feld im Frontmatter schon existiert, deshalb gehört es ins Archetype. tags und categories als leere Listen, damit das Frontmatter sauber parst, bevor Du :Hugo tags und :Hugo categories benutzt.

Wer mit single-file-Posts arbeitet (eine .md ohne Bundle), legt analog archetypes/post.md an. hugo-cms.nvim merkt am Archetype-Typ selbst, ob neue Beiträge daraus single-file oder Bundles werden.

Ersten Beitrag schreiben

Hugo bringt selbst den Befehl hugo new content/<pfad>/<slug>.md mit, der aus dem passenden Archetype eine Datei mit gefülltem title und date erzeugt. Das Plugin baut darauf auf, schickt die Pfadangabe durch einen Picker und merkt sich Dein Pfad-Pattern.

Mit aktiver Site :Hugo new (<leader>hn). Drei Prompts:

Archetype: post
Title:     Mein erster Beitrag
Path:      blog/{year}/mein-erster-beitrag

Beim Archetype zeigt das Plugin einen Picker über alles, was unter archetypes/ liegt. Wählst Du post, kommt das post-Archetype zum Einsatz.

Title ist freier Text. Der Slug wird daraus abgeleitet, Umlaute und Sonderzeichen werden transliteriert (Über mich → ueber-mich). Den title im Frontmatter behalte ich so wie ich ihn eintippe.

Path ist mit dem Archetype-spezifischen Pfad-Pattern und dem abgeleiteten Slug vorbelegt. Den Slug kannst Du noch ändern, bevor Du Enter drückst.

Beim allerersten Einsatz eines Archetypes fragt das Plugin nach dem Pfad-Pattern. Das entscheidet, wo Beiträge aus diesem Archetype landen. Beispiele:

Verfügbar sind {year}, {month} und {day}, alle nullgepaddet. Das Pattern wird pro Site und pro Archetype gespeichert. Mit :Hugo site pattern änderst Du es später, falls Du anders strukturieren willst.

Nach dem Bestätigen liegt für ein Bundle-Archetype ein Ordner content/blog/2026/mein-erster-beitrag/ mit index.md da, das Frontmatter ist mit Deinem Titel und dem aktuellen Datum gefüllt, der Rest ist leer. Schreiben kannst Du loslegen.

Was das Plugin nicht macht: das eigentliche Markdown-Schreiben. Das ist Editor-Aufgabe wie bei jeder anderen .md-Datei. Wer Inline-Rendering oder Live-Preview im Buffer haben will, schaut sich zum Beispiel markview.nvim an.

Wie es weitergeht

Damit hast Du eine Site bei hugo-cms.nvim angemeldet und den ersten Beitrag stehen. Wie Du Beiträge wiederfindest, Tags und Kategorien pflegst und das Draft-Flag schaltest, ist Thema vom Beitrag über das Verwalten von Inhalten.