CLI-Referenz

Die nera-CLI (@nera-static/nera)

Ein Befehl erstellt, baut, zeigt in der Vorschau, aktualisiert und prüft eine Website. Eine neue Website erstellst du mit:

npx @nera-static/nera new <project-name>

nera new . erstellt die Website stattdessen im aktuellen, leeren Ordner, und --theme <name> startet sie mit einem Theme. --starter <name> startet sie stattdessen mit einem fertigen Starter-Kit zum Anpassen (blank, blog, business oder portfolio; nicht zusammen mit --theme), und --name "<site name>" und --lang <code> setzen name und lang in config/app.yaml:

npx @nera-static/nera new my-blog --starter blog --name "Mein Blog" --lang de

--no-install lässt das npm install am Ende weg; führe es später selbst aus.

In einem Terminal, ohne --starter oder --yes, fragt nera new, was du baust, wie die Website heißt und in welcher Sprache sie ist; mit --yes oder ohne Terminal fragt es nie. Die Details stehen unten unter Starter-Kits.

Eine erstellte Website hängt von @nera-static/nera ab, führe diese Befehle also in ihr mit npx aus, z. B. npx nera validate. Der Scaffold verknüpft außerdem build, dev und serve mit npm-Skripten, z. B. npm run dev:

Veröffentlichen mit nera publish. nera publish bringt eine Website aus ihrem Ordner über GitHub zu einer erreichbaren URL: Es meldet dich über die GitHub-App „Nera Static“ an, legt das Repository an (oder verwendet das aus config/publish.yaml weiter), erzeugt .github/workflows/deploy.yml, pusht und verfolgt den Actions-Lauf. Der Hoster ist GitHub Pages (--target github-pages, die Voreinstellung): Es schaltet Pages mit dem Build-Typ GitHub Actions ein, setzt base_path in config/app.yaml für eine Projektseite (/<repo>; keinen für ein <user>.github.io-Repository oder eine eigene Domain) und gibt die Live-URL aus. --domain <host> setzt eine eigene Domain in den Pages-Einstellungen, prüft ihr DNS und gibt die einzutragenden Records aus, wenn sie fehlen oder falsch sind. Die weiteren Optionen sind --repo <name> (Voreinstellung: der Ordnername), --private (GitHub Pages veröffentlicht ein privates Repository nur mit einem kostenpflichtigen GitHub-Plan), --yes, --json und --sign-out. Netlify folgt in einem späteren Release. Für einen anderen Hoster baust du die Website und lädst den Inhalt von public/ zu einem beliebigen statischen Hoster hoch, wie Deployment beschreibt.

Starter-Kits

Ein Starter-Kit ist eine ganze Website zum Anpassen: Beispielseiten, Config, optionale theme/-Overrides auf Website-Ebene, Assets und das Theme und die Plugins, von denen es abhängt. nera new --starter kopiert seine pages/, config/, theme/, assets/, plugins/ und .neraignore über das Basis-Template, ergänzt seine dependencies in der package.json der Website, wendet --name und --lang an, installiert und gibt den Abschnitt ## First steps aus der README des Starters aus (nichts, wenn er keinen hat). Danach gehören die Dateien der Website: Ein Starter hat keinen Update-Weg, das Theme, von dem er abhängt, wird aber weiter über npm aktualisiert.

--name "<site name>" und --lang <code> setzen name: und lang: in config/app.yaml, mit oder ohne Starter. Eine neue Sprache bekommt eine Kopie des translations:-Eintrags der bisherigen Sprache, bereit zum Übersetzen, sodass keine Seite einen rohen Übersetzungsschlüssel zeigt.

--starter nimmt:

• einen Starter-Namen: blank, blog, business oder portfolio, kurz für @nera-static/starter-blank usw.;
• einen Paketnamen: @acme/starter-shop oder ohne Scope nera-starter-shop;
• eine GitHub-URL: https://github.com/owner/repo (optional mit .git, #ref) oder github:owner/repo#ref;
• einen lokalen Pfad: ./my-starter, ../my-starter oder einen absoluten Pfad.

Pakete und GitHub-Repositories werden mit npm pack --ignore-scripts heruntergeladen, es läuft also kein Skript des Starters. Ein Starter ist ein Paket, dessen package.json ein Feld nera.starter hat ({ "label": "…", "description": "…" }); alles andere wird abgelehnt, bevor irgendetwas geschrieben wird. Ein Starter, der in seiner config/app.yaml theme: setzt, lässt die Starter-Templates des Scaffolds weg, wie --theme.

Führst du nera new my-site in einem Terminal aus, fragt es stattdessen:

What are you building?
  1) Empty — the base template, no starter
  2) …
Choose 1–2 [1]:
Site name [My Nera Site]:
Language [en]:

Die Liste kommt aus der npm-Registry (Pakete mit dem Keyword nera-starter, offizielle @nera-static/-Pakete zuerst) oder aus einer kurzen Liste, die die CLI mitbringt, wenn die Registry nicht erreichbar ist. Enter übernimmt den Standardwert. Jede Frage hat ein Flag (--starter, --name, --lang); mit --yes oder ohne Terminal (Skripte, CI, KI-Agenten) wird nichts gefragt, und nera new erstellt das Basis-Template.

Die offiziellen Starter:

Die gebaute Website prüfen

nera validate liest deine Quellen. nera check liest, was der Build erzeugt hat — die Seite, die Besucher bekommen, mit Layout, Navigation, Footer, Skripten, Stylesheets und Schriften — und sucht dort nach Problemen, die ein Parser finden kann:

nera build --check   # bauen, dann prüfen — der eine Befehl für CI
nera check           # ein vorhandenes public/ prüfen, ohne neu zu bauen

Führe zuerst nera build aus; ohne public/ bricht nera check mit „run nera build first“ ab. Ein Problem in einem Template wird einmal gemeldet, mit der Zahl der Seiten, auf denen es auftritt.

Jeder Befund ist standardmäßig eine Warnung, der Befehl endet also mit 0. Mit 1 endet er nur, wenn eine Regel anschlägt, die du auf error hochgestuft hast — so wird daraus eine Schranke in der CI.

Das sind Hinweise, keine Rechtsberatung. Ein sauberer Lauf ist kein Nachweis von Konformität: Automatische Tests finden nur einen Teil der Barrierefreiheitsprobleme (etwa ein Drittel der WCAG-Verstöße). Farbkontrast, sichtbarer Fokus und die Frage, ob ein Gesetz für deine Website überhaupt gilt, werden nicht geprüft. Jeder Bericht endet mit diesem Hinweis.

Die Prüfungen konfigurierst du in config/validate.yaml (optional — ohne die Datei gelten die Standards oben):

rules:
  a11y-img-alt: error         # hochstufen: die Prüfung schlägt fehl
  a11y-target-blank: warning  # eine Opt-in-Regel einschalten
  a11y-skip-link: off         # abschalten
legal:
  imprint:                    # je Sprache die Seite, auf die jede Seite verlinkt
    de: /de/impressum.html
    en: /en/imprint.html
  privacy:
    de: /de/datenschutz.html
    en: /en/privacy.html
privacy:
  allowed_hosts:              # Drittanbieter-Hosts, die du berücksichtigt hast
    - cdn.example.org

Um eine Regel auf einer einzelnen Seite stummzuschalten, trage sie im Frontmatter der Seite ein: validate_ignore: [a11y-h1].

Um eine Regel für ganze Dateien oder Ordner stummzuschalten, liste sie unter ignore auf. Das wirkt auch bei nera validate — etwa für layout-missing bei Inhaltsbausteinen, die eine andere Seite einbindet, oder bei Entwürfen, die absichtlich kein layout haben:

ignore:
  layout-missing:
    - pages/*/references      # ein Ordner umfasst alles darunter
    - pages/de/blog/drafts    # * steht für einen Ordnernamen

Die Pfade sind relativ zum Wurzelordner der Website. Das braucht @nera-static/validate 1.3.0, das npm update in eine bestehende Website holt.

Dein eigener Host. Um deine Ressourcen von denen Dritter zu unterscheiden, liest privacy-third-party origin aus config/app.yaml, sonst app_origin aus config/canonical-links.yaml (mit und ohne www.). Ist beides nicht gesetzt, gelten nur relative URLs als deine eigenen.

Ressourcen hinter einer Einwilligung. Ein Skript oder eine Einbettung im Markup von @nera-static/plugin-consent (type="text/plain" mit data-src, oder data-consent-src statt src) lädt beim Seitenaufruf nichts, also meldet privacy-third-party es nicht. Ein Element mit data-consent, das trotzdem lädt, meldet privacy-consent-leak. Das Tutorial Einen Consent-Banner einbauen — oder keinen zeigt beides.

Links zu Impressum und Datenschutz nur auf Deutsch und Englisch. Ohne legal-Konfiguration werden die Links an ihrem Text erkannt — Impressum, Imprint, Legal notice, Datenschutz, Privacy, Data protection — und nur auf deutschen und englischen Seiten. Für jede andere Sprache nennst du die Seiten unter legal.imprint.<lang> und legal.privacy.<lang>.

Die vollständigen Regelbeschreibungen stehen in der README von @nera-static/validate.

Anweisungen für KI-Assistenten

Jede neu angelegte Website enthält eine AGENTS.md – die Datei, die Codex, Cursor, Copilot und andere Assistenten zuerst lesen – und eine CLAUDE.md mit der einzigen Zeile @AGENTS.md, damit Claude Code denselben Text lädt. AGENTS.md endet mit einem Abschnitt Notes for this site für deine eigenen Anweisungen, unterhalb der Markierungszeile <!-- nera:site-notes … -->. Lass diese Zeile stehen: Der Teil darüber gehört Nera, der Teil darunter dir.

Ab @nera-static/nera 1.7.0 hält nera update beide Dateien aktuell, ohne zusätzliche Option. Nach dem Aktualisieren der Pakete (und nach nera update --migrate)

• legt es AGENTS.md und CLAUDE.md an, wenn sie fehlen, sodass auch eine ältere Website sie bekommt;
• ersetzt es nur den Teil von AGENTS.md oberhalb der Markierungszeile durch den Text aus dem installierten @nera-static/nera; die Markierungszeile und deine Notizen darunter bleiben genau, wie sie sind;
• lässt es eine AGENTS.md ohne Markierungszeile unverändert und gibt einen Hinweis aus – kopiere die Markierungszeile aus der Vorlage direkt über deine eigenen Notizen, um mitzumachen;
• fasst es eine vorhandene CLAUDE.md nie an.

Eine Datei wird nur geschrieben, wenn sich ihr Inhalt ändert; ein erneutes nera update ändert also nichts.

Eine ältere (geklonte) Website migrieren

Vor der CLI erstellte Websites waren Git-Klone, die die Engine unter src/ mitführten. Führe in einer solchen Website nera update --migrate aus — das fügt die Abhängigkeit @nera-static/nera hinzu, schreibt die Skripte um, entfernt die mitgeführte src/-Engine und installiert, während deine pages/, config/ und theme/ unangetastet bleiben.

Plugin-Publish-Befehle

Jedes Template-ausliefernde Plugin stellt ein Bin bereit, um sein Pug nach theme/views/vendor/ zu kopieren, z. B.:

npx nera-navigation
npx nera-tags
npx nera-search --force   # overwrite existing published templates