forked from DevFW-CICD/website-and-documentation

Stephan Lo 8785b327dd feat(docs): integrate LikeC4 interactive diagrams into Hugo/Docsy

Implement complete integration of LikeC4 interactive architecture
diagrams into the Hugo/Docsy documentation system, enabling embedded
web components for exploring C4 models directly in documentation pages.

Integration Components:

Static Assets:
- static/js/likec4-webcomponent.js (3.1 MB) - Generated web component
  containing all 54 C4 views as interactive embeddable elements
- static/js/likec4-loader.js - Dynamic ES6 module loader with fallback
  paths for robust component loading across different page depths
- static/css/likec4-styles.css - Styling for diagram containers with
  dark mode support for Docsy theme compatibility

Hugo Configuration:
- hugo.toml - Added params.likec4.enable configuration flag
- layouts/partials/hooks/head-end.html - Hook to inject CSS and JS
  when LikeC4 is enabled site-wide

Documentation:
- content/en/docs/architecture/_index.md - Architecture section index
- content/en/docs/architecture/highlevelarch.md - Example page with
  interactive OTC FaaS deployment diagram demonstrating integration
- content/en/docs/architecture/setup.md - Comprehensive setup guide
  covering installation, usage, workflow, and troubleshooting
- resources/likec4/INTEGRATION.md - Technical integration details
- LIKEC4-QUICKSTART.md - Quick start guide for developers

Features:
- Interactive diagram exploration (click components for details)
- Automatic loading indicators with timeout fallback
- Graceful degradation for non-JS environments
- Dark mode support matching Docsy theme
- Multiple diagrams per page support
- Browser compatibility detection

Usage Pattern:
```html
<div class="likec4-container">
    <div class="likec4-header">Diagram Title</div>
    <likec4-view view-id="otc-faas" browser="true"></likec4-view>
    <div class="likec4-loading">Loading...</div>
</div>
```

Workflow:
1. Edit .c4 files in resources/likec4/
2. Run: npx likec4 gen webcomponent --webcomponent-prefix likec4
   --outfile ../../static/js/likec4-webcomponent.js
3. Commit both model changes and regenerated webcomponent

Available Views:
- otc-faas, edp, landscape, edpbuilderworkflow
- keycloak, forgejo, argocd, crossplane, monitoring
- And 40+ more component and deployment views

The integration preserves the MkDocs-style embedding approach from
edp-doc while adapting it to Hugo's static site generation model.

This completes the migration making this repository the central hub
for both C4 architecture models and their rendered documentation.

2025-10-24 13:08:59 +02:00

3.2 KiB

Raw Blame History

LikeC4 Integration - Quick Start

Dieses Repository enthält jetzt die LikeC4-Architekturdokumentation aus edp-doc mit vollständiger Git-Historie.

Was wurde gemacht?

✅ LikeC4-Modelle migriert - resources/likec4/ enthält alle C4-Modelle mit Git-Historie
✅ Hugo-Integration erstellt - CSS, JS und Loader-Scripte für Hugo/Docsy
✅ Beispielseiten erstellt - Dokumentation unter content/en/docs/architecture/
✅ Konfiguration - hugo.toml und Layout-Hooks konfiguriert

Nächste Schritte

1. Webcomponent generieren

cd resources/likec4

# Dependencies installieren (nur einmalig)
npm install

# Webcomponent generieren
npx likec4 codegen webcomponent \
  --webcomponent-prefix likec4 \
  --outfile ../../static/js/likec4-webcomponent.js

Dies erzeugt static/js/likec4-webcomponent.js (~2-3 MB).

2. Hugo Server starten

# Im Repository-Root
hugo server -D

# Öffne http://localhost:1313/docs/architecture/highlevelarch/

3. Änderungen committen

git add resources/likec4/
git add static/
git add layouts/
git add content/en/docs/architecture/
git add hugo.toml
git commit -m "feat: integrate LikeC4 architecture documentation from edp-doc"

Verfügbare Seiten

/docs/architecture/ - Architektur-Übersicht
/docs/architecture/highlevelarch/ - High-Level Architektur mit interaktivem Diagramm
/docs/architecture/setup/ - Setup und Verwendungs-Anleitung

Workflow für Architektur-Änderungen

Modelle bearbeiten: .c4 Dateien in resources/likec4/models/ oder views/
Vorschau: cd resources/likec4 && npx likec4 start (öffnet http://localhost:5173)
Generieren: Webcomponent neu generieren (siehe oben)
Testen: Hugo Server starten und Seiten prüfen
Committen: Sowohl .c4 Dateien als auch static/js/likec4-webcomponent.js

Technische Details

Integration-Komponenten

resources/likec4/ - LikeC4 Quellcode (migriert mit Git-Historie)
static/js/likec4-loader.js - Dynamischer Module Loader
static/css/likec4-styles.css - Styling inkl. Dark Mode
layouts/partials/hooks/head-end.html - Hugo Hook für JS/CSS Einbindung
hugo.toml - Konfiguration (params.likec4.enable = true)

Verwendung in Markdown

<div class="likec4-container">
    <div class="likec4-header">
        Dein Diagramm-Titel
    </div>
    <likec4-view view-id="otc-faas" browser="true"></likec4-view>
    <div class="likec4-loading" id="likec4-loading">
        Loading...
    </div>
</div>

Verfügbare View-IDs finden

cd resources/likec4
grep -r "view\s\+\w" views/ models/ --include="*.c4"

Häufige View-IDs

otc-faas - OTC FaaS Deployment
edp - EDP Übersicht
landscape - Developer Landscape
edpbuilderworkflow - Builder Workflow
keycloak, forgejo, argoCD, etc. - Komponenten-Views

Migration von edp-doc

Dieses Repository ist jetzt die primäre Quelle für LikeC4-Architektur. Das edp-doc Repository kann diese Modelle bei Bedarf als Git Submodule referenzieren.

Support

Bei Problemen siehe:

resources/likec4/INTEGRATION.md - Detaillierte Integration-Dokumentation
content/en/docs/architecture/setup.md - Setup-Anleitung
https://likec4.dev/ - LikeC4 Dokumentation

3.2 KiB Raw Blame History