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.
This commit is contained in:
parent
286b427ed8
commit
8785b327dd
9 changed files with 1465 additions and 1 deletions
112
LIKEC4-QUICKSTART.md
Normal file
112
LIKEC4-QUICKSTART.md
Normal file
|
|
@ -0,0 +1,112 @@
|
||||||
|
# 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
|
||||||
9
content/en/docs/architecture/_index.md
Normal file
9
content/en/docs/architecture/_index.md
Normal file
|
|
@ -0,0 +1,9 @@
|
||||||
|
---
|
||||||
|
title: "Architecture"
|
||||||
|
linkTitle: "Architecture"
|
||||||
|
weight: 3
|
||||||
|
description: >
|
||||||
|
System architecture documentation and interactive diagrams
|
||||||
|
---
|
||||||
|
|
||||||
|
This section contains architecture documentation for the IPCEI-CIS Developer Framework, including interactive C4 architecture diagrams.
|
||||||
125
content/en/docs/architecture/highlevelarch.md
Normal file
125
content/en/docs/architecture/highlevelarch.md
Normal file
|
|
@ -0,0 +1,125 @@
|
||||||
|
---
|
||||||
|
title: "High Level Architecture"
|
||||||
|
linkTitle: "High Level Architecture"
|
||||||
|
weight: 1
|
||||||
|
description: >
|
||||||
|
Interactive high-level architecture overview of the Enterprise Development Platform
|
||||||
|
---
|
||||||
|
|
||||||
|
This document describes the high-level architecture of our Enterprise Development Platform (EDP) system.
|
||||||
|
|
||||||
|
## Interactive Architecture Diagram
|
||||||
|
|
||||||
|
<div class="likec4-container">
|
||||||
|
<div class="likec4-header">
|
||||||
|
Enterprise Development Platform - OTC FaaS Deployment Architecture
|
||||||
|
</div>
|
||||||
|
<likec4-view view-id="otc-faas" browser="true"></likec4-view>
|
||||||
|
<div class="likec4-loading" id="likec4-loading">
|
||||||
|
Loading architecture diagram...
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<script>
|
||||||
|
// Enhanced loading check with fallback
|
||||||
|
document.addEventListener('DOMContentLoaded', function() {
|
||||||
|
let attempts = 0;
|
||||||
|
const maxAttempts = 10;
|
||||||
|
|
||||||
|
function checkLikeC4Loading() {
|
||||||
|
attempts++;
|
||||||
|
const component = document.querySelector('likec4-view');
|
||||||
|
const loading = document.getElementById('likec4-loading');
|
||||||
|
|
||||||
|
if (component && component.shadowRoot && component.shadowRoot.children.length > 0) {
|
||||||
|
if (loading) loading.style.display = 'none';
|
||||||
|
console.log('LikeC4 component loaded successfully');
|
||||||
|
} else if (attempts >= maxAttempts) {
|
||||||
|
console.warn('LikeC4 component failed to load');
|
||||||
|
if (loading) {
|
||||||
|
loading.innerHTML = 'Interactive diagram failed to load. <br><small>Please ensure JavaScript is enabled and the webcomponent is generated.</small>';
|
||||||
|
loading.style.color = '#dc3545';
|
||||||
|
}
|
||||||
|
} else {
|
||||||
|
setTimeout(checkLikeC4Loading, 1000);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check if LikeC4 loader is available
|
||||||
|
if (typeof window.customElements !== 'undefined') {
|
||||||
|
setTimeout(checkLikeC4Loading, 1500);
|
||||||
|
} else {
|
||||||
|
const loading = document.getElementById('likec4-loading');
|
||||||
|
if (loading) {
|
||||||
|
loading.innerHTML = 'Interactive diagrams require a modern browser with JavaScript enabled.';
|
||||||
|
loading.style.color = '#dc3545';
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
</script>
|
||||||
|
|
||||||
|
{{< alert title="Interactive Diagram" >}}
|
||||||
|
The diagram above is interactive when viewed in a compatible browser.
|
||||||
|
You can click on components to explore the architecture details.
|
||||||
|
|
||||||
|
**Note:** The interactive diagram requires the LikeC4 webcomponent to be generated.
|
||||||
|
See the [setup instructions]({{< ref "/docs/architecture/setup" >}}) for details.
|
||||||
|
{{< /alert >}}
|
||||||
|
|
||||||
|
## Architecture Overview
|
||||||
|
|
||||||
|
The Enterprise Development Platform consists of several key components working together to provide a comprehensive development and deployment environment.
|
||||||
|
|
||||||
|
### Key Components
|
||||||
|
|
||||||
|
1. **OTC Foundry** - Central management and orchestration layer
|
||||||
|
2. **Per-Tenant EDP** - Isolated development environments for each tenant
|
||||||
|
3. **FaaS Environment** - Function-as-a-Service deployment targets on Open Telekom Cloud
|
||||||
|
4. **Cloud Services** - Managed services including databases, storage, and monitoring
|
||||||
|
|
||||||
|
### Deployment Environments
|
||||||
|
|
||||||
|
- **Development Environment** (`*.t09.de`) - For platform team development and testing
|
||||||
|
- **Production Environment** (`*.buildth.ing`) - For production workloads and tenant services
|
||||||
|
|
||||||
|
## Component Details
|
||||||
|
|
||||||
|
The interactive diagram above shows the relationships between different components and how they interact within the system architecture. You can explore the diagram by clicking on different elements to see more details.
|
||||||
|
|
||||||
|
### Infrastructure Components
|
||||||
|
|
||||||
|
- **Kubernetes Clusters** - Container orchestration using OTC CCE (Cloud Container Engine)
|
||||||
|
- **ArgoCD** - GitOps continuous deployment and application lifecycle management
|
||||||
|
- **Forgejo** - Git repository management and CI/CD pipelines
|
||||||
|
- **Observability Stack** - Monitoring (Prometheus, Grafana), logging (Loki), and alerting
|
||||||
|
|
||||||
|
### Security and Management
|
||||||
|
|
||||||
|
- **Keycloak** - Identity and access management (IAM)
|
||||||
|
- **OpenBao** - Secrets management (Hashicorp Vault fork)
|
||||||
|
- **External Secrets Operator** - Kubernetes secrets integration
|
||||||
|
- **Crossplane** - Infrastructure as Code and cloud resource provisioning
|
||||||
|
|
||||||
|
### Developer Experience
|
||||||
|
|
||||||
|
- **Backstage** - Internal developer portal and service catalog
|
||||||
|
- **Forgejo Actions** - CI/CD pipeline execution
|
||||||
|
- **Development Workflows** - GitOps-based inner and outer loop workflows
|
||||||
|
|
||||||
|
## Setup and Maintenance
|
||||||
|
|
||||||
|
To update or modify the architecture diagrams:
|
||||||
|
|
||||||
|
1. Edit the `.c4` files in `resources/likec4/`
|
||||||
|
2. Regenerate the webcomponent:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd resources/likec4
|
||||||
|
npx likec4 codegen webcomponent \
|
||||||
|
--webcomponent-prefix likec4 \
|
||||||
|
--outfile ../../static/js/likec4-webcomponent.js
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Commit both the model changes and the regenerated JavaScript file
|
||||||
|
|
||||||
|
For more information, see the [LikeC4 Integration Guide]({{< ref "/docs/architecture/setup" >}}).
|
||||||
291
content/en/docs/architecture/setup.md
Normal file
291
content/en/docs/architecture/setup.md
Normal file
|
|
@ -0,0 +1,291 @@
|
||||||
|
---
|
||||||
|
title: "LikeC4 Setup Guide"
|
||||||
|
linkTitle: "Setup"
|
||||||
|
weight: 10
|
||||||
|
description: >
|
||||||
|
How to set up and use LikeC4 interactive architecture diagrams
|
||||||
|
---
|
||||||
|
|
||||||
|
This guide explains how to set up and use LikeC4 interactive architecture diagrams in this documentation.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
LikeC4 enables you to create interactive C4 architecture diagrams as code. The diagrams are defined in `.c4` files and compiled into a web component that can be embedded in any HTML page.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- Node.js (v18 or later)
|
||||||
|
- npm or yarn
|
||||||
|
|
||||||
|
## Initial Setup
|
||||||
|
|
||||||
|
### 1. Install Dependencies
|
||||||
|
|
||||||
|
Navigate to the LikeC4 directory and install dependencies:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd resources/likec4
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Generate the Web Component
|
||||||
|
|
||||||
|
Create the web component that Hugo will load:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx likec4 codegen webcomponent \
|
||||||
|
--webcomponent-prefix likec4 \
|
||||||
|
--outfile ../../static/js/likec4-webcomponent.js
|
||||||
|
```
|
||||||
|
|
||||||
|
This command:
|
||||||
|
- Reads all `.c4` files from `models/` and `views/`
|
||||||
|
- Generates a single JavaScript file with all architecture views
|
||||||
|
- Outputs to `static/js/likec4-webcomponent.js`
|
||||||
|
|
||||||
|
### 3. Verify Integration
|
||||||
|
|
||||||
|
The integration should already be configured in:
|
||||||
|
|
||||||
|
- `hugo.toml` - Contains `params.likec4.enable = true`
|
||||||
|
- `layouts/partials/hooks/head-end.html` - Loads CSS and loader script
|
||||||
|
- `static/css/likec4-styles.css` - Diagram styling
|
||||||
|
- `static/js/likec4-loader.js` - Dynamic module loader
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
resources/likec4/
|
||||||
|
├── models/ # C4 model definitions
|
||||||
|
│ ├── components/ # Component models
|
||||||
|
│ ├── containers/ # Container models
|
||||||
|
│ ├── context/ # System context
|
||||||
|
│ └── code/ # Code-level workflows
|
||||||
|
├── views/ # View definitions
|
||||||
|
│ ├── deployment/ # Deployment views
|
||||||
|
│ ├── edp/ # EDP views
|
||||||
|
│ ├── high-level-concept/ # Conceptual views
|
||||||
|
│ └── dynamic/ # Process flows
|
||||||
|
├── package.json # Dependencies
|
||||||
|
└── INTEGRATION.md # Integration docs
|
||||||
|
```
|
||||||
|
|
||||||
|
## Using in Documentation
|
||||||
|
|
||||||
|
### Basic Usage
|
||||||
|
|
||||||
|
Add this to any Markdown file:
|
||||||
|
|
||||||
|
```html
|
||||||
|
<div class="likec4-container">
|
||||||
|
<div class="likec4-header">
|
||||||
|
Your Diagram Title
|
||||||
|
</div>
|
||||||
|
<likec4-view view-id="YOUR-VIEW-ID" browser="true"></likec4-view>
|
||||||
|
<div class="likec4-loading" id="likec4-loading">
|
||||||
|
Loading architecture diagram...
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Available View IDs
|
||||||
|
|
||||||
|
To find available view IDs, search the `.c4` files:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd resources/likec4
|
||||||
|
grep -r "view\s\+\w" views/ models/ --include="*.c4"
|
||||||
|
```
|
||||||
|
|
||||||
|
Common views:
|
||||||
|
- `otc-faas` - OTC FaaS deployment
|
||||||
|
- `edp` - EDP overview
|
||||||
|
- `landscape` - Developer landscape
|
||||||
|
- `edpbuilderworkflow` - Builder workflow
|
||||||
|
- `keycloak` - Keycloak component
|
||||||
|
|
||||||
|
### With Hugo Alert
|
||||||
|
|
||||||
|
Combine with Docsy alerts for better UX:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
<div class="likec4-container">
|
||||||
|
<div class="likec4-header">
|
||||||
|
System Architecture
|
||||||
|
</div>
|
||||||
|
<likec4-view view-id="otc-faas" browser="true"></likec4-view>
|
||||||
|
<div class="likec4-loading" id="likec4-loading">
|
||||||
|
Loading...
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
{{</* alert title="Note" */>}}
|
||||||
|
Click on components in the diagram to explore the architecture.
|
||||||
|
{{</* /alert */>}}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Workflow for Changes
|
||||||
|
|
||||||
|
### 1. Modify Architecture Models
|
||||||
|
|
||||||
|
Edit the `.c4` files in `resources/likec4/`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Edit a model
|
||||||
|
vi resources/likec4/models/containers/argocd.c4
|
||||||
|
|
||||||
|
# Or edit a view
|
||||||
|
vi resources/likec4/views/deployment/otc/otc-faas.c4
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Preview Changes Locally
|
||||||
|
|
||||||
|
Use the LikeC4 CLI to preview:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd resources/likec4
|
||||||
|
|
||||||
|
# Start preview server
|
||||||
|
npx likec4 start
|
||||||
|
|
||||||
|
# Opens browser at http://localhost:5173
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Regenerate Web Component
|
||||||
|
|
||||||
|
After making changes:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd resources/likec4
|
||||||
|
npx likec4 codegen webcomponent \
|
||||||
|
--webcomponent-prefix likec4 \
|
||||||
|
--outfile ../../static/js/likec4-webcomponent.js
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Test in Hugo
|
||||||
|
|
||||||
|
Start the Hugo development server:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# From repository root
|
||||||
|
hugo server -D
|
||||||
|
|
||||||
|
# Open http://localhost:1313
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Commit Changes
|
||||||
|
|
||||||
|
Commit both the model files and the regenerated web component:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add resources/likec4/
|
||||||
|
git add static/js/likec4-webcomponent.js
|
||||||
|
git commit -m "feat: update architecture diagrams"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Advanced Configuration
|
||||||
|
|
||||||
|
### Custom Styling
|
||||||
|
|
||||||
|
Modify `static/css/likec4-styles.css` to customize appearance:
|
||||||
|
|
||||||
|
```css
|
||||||
|
.likec4-container {
|
||||||
|
height: 800px; /* Adjust height */
|
||||||
|
border-radius: 8px; /* Rounder corners */
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Multiple Diagrams Per Page
|
||||||
|
|
||||||
|
You can include multiple diagrams on a single page:
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- First diagram -->
|
||||||
|
<div class="likec4-container">
|
||||||
|
<div class="likec4-header">Deployment View</div>
|
||||||
|
<likec4-view view-id="otc-faas" browser="true"></likec4-view>
|
||||||
|
<div class="likec4-loading">Loading...</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<!-- Second diagram -->
|
||||||
|
<div class="likec4-container">
|
||||||
|
<div class="likec4-header">Component View</div>
|
||||||
|
<likec4-view view-id="edp" browser="true"></likec4-view>
|
||||||
|
<div class="likec4-loading">Loading...</div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Disable for Specific Pages
|
||||||
|
|
||||||
|
Add to page front matter:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
title: "My Page"
|
||||||
|
params:
|
||||||
|
disable_likec4: true
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
Then update `layouts/partials/hooks/head-end.html`:
|
||||||
|
|
||||||
|
```html
|
||||||
|
{{ if and .Site.Params.likec4.enable (not .Params.disable_likec4) }}
|
||||||
|
<!-- LikeC4 scripts -->
|
||||||
|
{{ end }}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Diagram Not Loading
|
||||||
|
|
||||||
|
1. **Check browser console** (F12 → Console)
|
||||||
|
2. **Verify webcomponent exists:**
|
||||||
|
```bash
|
||||||
|
ls -lh static/js/likec4-webcomponent.js
|
||||||
|
```
|
||||||
|
3. **Regenerate if missing:**
|
||||||
|
```bash
|
||||||
|
cd resources/likec4
|
||||||
|
npm install
|
||||||
|
npx likec4 codegen webcomponent \
|
||||||
|
--webcomponent-prefix likec4 \
|
||||||
|
--outfile ../../static/js/likec4-webcomponent.js
|
||||||
|
```
|
||||||
|
|
||||||
|
### View Not Found
|
||||||
|
|
||||||
|
- Check view ID matches exactly (case-sensitive)
|
||||||
|
- Search for the view in `.c4` files:
|
||||||
|
```bash
|
||||||
|
grep -r "view otc-faas" resources/likec4/
|
||||||
|
```
|
||||||
|
|
||||||
|
### Styling Issues
|
||||||
|
|
||||||
|
- Clear browser cache (Ctrl+Shift+R)
|
||||||
|
- Check `static/css/likec4-styles.css` is loaded in browser DevTools → Network
|
||||||
|
|
||||||
|
### Build Errors
|
||||||
|
|
||||||
|
If LikeC4 codegen fails:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd resources/likec4
|
||||||
|
rm -rf node_modules package-lock.json
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
- [LikeC4 Documentation](https://likec4.dev/)
|
||||||
|
- [C4 Model](https://c4model.com/)
|
||||||
|
- [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components)
|
||||||
|
- [Hugo Documentation](https://gohugo.io/documentation/)
|
||||||
|
|
||||||
|
## Migration Notes
|
||||||
|
|
||||||
|
This LikeC4 integration was migrated from the edp-doc repository. This repository (`ipceicis-developerframework`) is now the primary source for architecture models.
|
||||||
|
|
||||||
|
The edp-doc repository can reference these models via git submodule if needed.
|
||||||
|
|
@ -175,3 +175,9 @@ svg_image_url = "https://www.plantuml.com/plantuml/svg/"
|
||||||
# When svg is set to true, diagrams are displayed using <svg /> tags, maintaining functionality like links e.g.
|
# When svg is set to true, diagrams are displayed using <svg /> tags, maintaining functionality like links e.g.
|
||||||
# default = false
|
# default = false
|
||||||
svg = true
|
svg = true
|
||||||
|
|
||||||
|
# LikeC4 interactive architecture diagrams configuration
|
||||||
|
[params.likec4]
|
||||||
|
enable = true
|
||||||
|
# The webcomponent file will be generated from resources/likec4 and placed in static/js/
|
||||||
|
webcomponent_file = "likec4-webcomponent.js"
|
||||||
5
layouts/partials/hooks/head-end.html
Normal file
5
layouts/partials/hooks/head-end.html
Normal file
|
|
@ -0,0 +1,5 @@
|
||||||
|
{{ if .Site.Params.likec4.enable }}
|
||||||
|
<!-- LikeC4 Interactive Architecture Diagrams -->
|
||||||
|
<link rel="stylesheet" href="{{ "css/likec4-styles.css" | relURL }}">
|
||||||
|
<script src="{{ "js/likec4-loader.js" | relURL }}"></script>
|
||||||
|
{{ end }}
|
||||||
70
static/css/likec4-styles.css
Normal file
70
static/css/likec4-styles.css
Normal file
|
|
@ -0,0 +1,70 @@
|
||||||
|
/* LikeC4 Component Styles for Hugo/Docsy */
|
||||||
|
likec4-view {
|
||||||
|
display: block;
|
||||||
|
width: 100%;
|
||||||
|
height: 100%;
|
||||||
|
border: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.likec4-container {
|
||||||
|
width: 100%;
|
||||||
|
height: 600px;
|
||||||
|
border: 1px solid #ddd;
|
||||||
|
border-radius: 4px;
|
||||||
|
background: #f9f9f9;
|
||||||
|
position: relative;
|
||||||
|
overflow: hidden;
|
||||||
|
margin: 2rem 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.likec4-loading {
|
||||||
|
position: absolute;
|
||||||
|
top: 50%;
|
||||||
|
left: 50%;
|
||||||
|
transform: translate(-50%, -50%);
|
||||||
|
color: #666;
|
||||||
|
font-size: 14px;
|
||||||
|
font-family: system-ui, sans-serif;
|
||||||
|
}
|
||||||
|
|
||||||
|
.likec4-loading::after {
|
||||||
|
content: '';
|
||||||
|
display: inline-block;
|
||||||
|
width: 12px;
|
||||||
|
height: 12px;
|
||||||
|
margin-left: 8px;
|
||||||
|
border: 2px solid #dee2e6;
|
||||||
|
border-top: 2px solid #007bff;
|
||||||
|
border-radius: 50%;
|
||||||
|
animation: likec4-spin 1s linear infinite;
|
||||||
|
}
|
||||||
|
|
||||||
|
@keyframes likec4-spin {
|
||||||
|
0% { transform: rotate(0deg); }
|
||||||
|
100% { transform: rotate(360deg); }
|
||||||
|
}
|
||||||
|
|
||||||
|
.likec4-header {
|
||||||
|
background: #f8f9fa;
|
||||||
|
border-bottom: 1px solid #e9ecef;
|
||||||
|
padding: 8px 16px;
|
||||||
|
font-size: 12px;
|
||||||
|
color: #495057;
|
||||||
|
border-radius: 4px 4px 0 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Dark mode support for Docsy */
|
||||||
|
body[data-dark-mode] .likec4-container {
|
||||||
|
background: #1e1e1e;
|
||||||
|
border-color: #444;
|
||||||
|
}
|
||||||
|
|
||||||
|
body[data-dark-mode] .likec4-header {
|
||||||
|
background: #2d2d2d;
|
||||||
|
border-bottom-color: #444;
|
||||||
|
color: #ccc;
|
||||||
|
}
|
||||||
|
|
||||||
|
body[data-dark-mode] .likec4-loading {
|
||||||
|
color: #ccc;
|
||||||
|
}
|
||||||
86
static/js/likec4-loader.js
Normal file
86
static/js/likec4-loader.js
Normal file
|
|
@ -0,0 +1,86 @@
|
||||||
|
/* LikeC4 Webcomponent Loader for Hugo/Docsy */
|
||||||
|
(function() {
|
||||||
|
'use strict';
|
||||||
|
|
||||||
|
// Check if the component is already loaded
|
||||||
|
if (customElements.get('likec4-view')) {
|
||||||
|
console.log('LikeC4 component already loaded');
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Function to dynamically import the ES6 module
|
||||||
|
function loadLikeC4Module() {
|
||||||
|
// Try different possible paths for the webcomponent
|
||||||
|
const possiblePaths = [
|
||||||
|
// Absolute Hugo paths (most likely to work)
|
||||||
|
'/js/likec4-webcomponent.js',
|
||||||
|
// Relative paths from current page
|
||||||
|
'../js/likec4-webcomponent.js',
|
||||||
|
'../../js/likec4-webcomponent.js',
|
||||||
|
'../../../js/likec4-webcomponent.js',
|
||||||
|
// Fallback paths
|
||||||
|
'./js/likec4-webcomponent.js',
|
||||||
|
'js/likec4-webcomponent.js'
|
||||||
|
];
|
||||||
|
|
||||||
|
let pathIndex = 0;
|
||||||
|
|
||||||
|
function tryNextPath() {
|
||||||
|
if (pathIndex >= possiblePaths.length) {
|
||||||
|
console.error('All module paths failed');
|
||||||
|
showErrorMessage('Failed to load interactive diagram module');
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
const modulePath = possiblePaths[pathIndex];
|
||||||
|
console.log(`Trying to load LikeC4 module from: ${modulePath}`);
|
||||||
|
|
||||||
|
// Dynamic import with error handling
|
||||||
|
try {
|
||||||
|
const importFunction = new Function('specifier', 'return import(specifier)');
|
||||||
|
importFunction(modulePath)
|
||||||
|
.then(function(module) {
|
||||||
|
console.log('LikeC4 webcomponent loaded successfully');
|
||||||
|
// Hide any loading indicators
|
||||||
|
hideLoadingIndicators();
|
||||||
|
})
|
||||||
|
.catch(function(error) {
|
||||||
|
console.warn(`Failed to load from ${modulePath}:`, error.message);
|
||||||
|
pathIndex++;
|
||||||
|
tryNextPath();
|
||||||
|
});
|
||||||
|
} catch (error) {
|
||||||
|
console.warn(`Dynamic import failed for ${modulePath}:`, error.message);
|
||||||
|
pathIndex++;
|
||||||
|
tryNextPath();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
tryNextPath();
|
||||||
|
}
|
||||||
|
|
||||||
|
function hideLoadingIndicators() {
|
||||||
|
const loadingElements = document.querySelectorAll('.likec4-loading, #likec4-loading');
|
||||||
|
loadingElements.forEach(function(el) {
|
||||||
|
el.style.display = 'none';
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function showErrorMessage(message) {
|
||||||
|
const containers = document.querySelectorAll('.likec4-container');
|
||||||
|
containers.forEach(function(container) {
|
||||||
|
const errorDiv = document.createElement('div');
|
||||||
|
errorDiv.style.cssText = 'position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); color: #dc3545; text-align: center; font-size: 14px; max-width: 300px;';
|
||||||
|
errorDiv.textContent = message;
|
||||||
|
container.appendChild(errorDiv);
|
||||||
|
});
|
||||||
|
hideLoadingIndicators();
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check if DOM is ready
|
||||||
|
if (document.readyState === 'loading') {
|
||||||
|
document.addEventListener('DOMContentLoaded', loadLikeC4Module);
|
||||||
|
} else {
|
||||||
|
loadLikeC4Module();
|
||||||
|
}
|
||||||
|
})();
|
||||||
760
static/js/likec4-webcomponent.js
Normal file
760
static/js/likec4-webcomponent.js
Normal file
File diff suppressed because one or more lines are too long
Loading…
Add table
Add a link
Reference in a new issue