Stephan Lo
8785b327dd
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.
112 lines
3.2 KiB
Markdown
112 lines
3.2 KiB
Markdown
# LikeC4 Integration - Quick Start
|
|
|
|
Dieses Repository enthält jetzt die LikeC4-Architekturdokumentation aus edp-doc mit vollständiger Git-Historie.
|
|
|
|
## Was wurde gemacht?
|
|
|
|
1. ✅ **LikeC4-Modelle migriert** - `resources/likec4/` enthält alle C4-Modelle mit Git-Historie
|
|
2. ✅ **Hugo-Integration erstellt** - CSS, JS und Loader-Scripte für Hugo/Docsy
|
|
3. ✅ **Beispielseiten erstellt** - Dokumentation unter `content/en/docs/architecture/`
|
|
4. ✅ **Konfiguration** - `hugo.toml` und Layout-Hooks konfiguriert
|
|
|
|
## Nächste Schritte
|
|
|
|
### 1. Webcomponent generieren
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# Im Repository-Root
|
|
hugo server -D
|
|
|
|
# Öffne http://localhost:1313/docs/architecture/highlevelarch/
|
|
```
|
|
|
|
### 3. Änderungen committen
|
|
|
|
```bash
|
|
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
|
|
|
|
1. **Modelle bearbeiten**: `.c4` Dateien in `resources/likec4/models/` oder `views/`
|
|
2. **Vorschau**: `cd resources/likec4 && npx likec4 start` (öffnet http://localhost:5173)
|
|
3. **Generieren**: Webcomponent neu generieren (siehe oben)
|
|
4. **Testen**: Hugo Server starten und Seiten prüfen
|
|
5. **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
|
|
|
|
```html
|
|
<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
|
|
|
|
```bash
|
|
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
|