New Semantics

English

Deutsch

English

Deutsch

Theme

New Semantics Docs ​

Entwickler-Dokumentation fuer das New Semantics CMS (PHP + Nuxt 4). Gebaut mit VitePress und Scalar fuer die interaktive OpenAPI-Referenz.

Voraussetzungen ​

  • Node.js 20+ (Produktion: 25.9.0)
  • npm
  • PHP CLI (nur fuer build:openapi, Scan der swagger-php Annotationen)

Hinweis zu Scalar-Version: @scalar/api-reference ist bewusst auf ^1.25.0 gepinnt (Legacy-Range). Scalar hat in 2025 einen 2.x-Major veroeffentlicht — Upgrade ist fuer zukuenftige Releases geplant, nach lokalem Test.

Setup ​

bash
cd docs
npm install

Entwicklung ​

Dev-Server auf http://localhost:5173 starten:

bash
npm run dev

Hot-Reload fuer alle Markdown- und Theme-Dateien.

Production-Build ​

bash
npm run build

Ausgabe: docs/.vitepress/dist/ — statische Site, nginx-kompatibel.

Preview des Production-Builds:

bash
npm run preview

OpenAPI-Spec neu generieren ​

Scannt _core/system/api/ + _public/extensions/core/backend/ nach swagger-php Annotationen und schreibt docs/public/openapi.json:

bash
npm run build:openapi

Das Script ruft _core/libs/swagger-php/bin/openapi mit PHP CLI auf. Voraussetzung: PHP ≥ 8.2 im PATH.

OG-Image rasterisieren ​

Quelle: public/og-image.svg. Rasterisierung nach public/og-image.png (1200x630) via:

bash
npm run build:og

Das Script nutzt rsvg-convert (empfohlen), magick, convert oder inkscape — der erste verfuegbare Tool wird benutzt. Ohne Tool laeuft der Build weiter, nur ohne OG-Image.

Struktur ​

docs/
├── .vitepress/
│   ├── config.ts           Site-Meta, Nav, Sidebar, Suche
│   └── theme/
│       ├── index.ts        Theme-Override (erweitert default)
│       └── custom.css      Brand-Farben (Electric Indigo #4F46E5)
├── api-reference/          Scalar-Embed
├── getting-started/        Installation, Config, Directory Structure
├── plugins/                Plugin-Entwicklungs-Doku
├── widgets/                Widget-Entwicklungs-Doku
├── themes/                 Theme- und Projekt-Doku
├── public/
│   ├── openapi.json        Generierte OpenAPI-Spec (Scalar-Quelle)
│   ├── favicon.svg         Favicon (Brand-Gradient)
│   └── og-image.svg        OG-Image-Quelle (PNG via build:og)
├── scripts/
│   ├── build-openapi.sh    Wrapper fuer swagger-php
│   └── build-og-image.sh   SVG -> PNG Rasterizer fuer OG-Image
├── deploy/
│   ├── nginx-plesk.conf                Plesk-Zusatz-Direktiven (produktiv)
│   ├── nginx-standalone.conf           Alternative für nginx ohne Plesk
│   └── README.md                       Deploy-Anleitung
├── 404.md                  404-Fallback-Seite
└── index.md                Startseite (Hero + Feature-Kacheln)

Deployment ​

Der statische Build unter .vitepress/dist/ wird per nginx auf docs.new-semantics.com ausgeliefert (aktuell via Plesk). Komplette Anleitung (Plesk-Setup, rsync-Deploy, GitHub Actions, Rollback, Analytics-Nachrüstung) in deploy/README.md, nginx-Configs in deploy/nginx-plesk.conf (produktiv) und deploy/nginx-standalone.conf (Alternative ohne Plesk).