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.
|
||
|---|---|---|
| .devcontainer | ||
| .github/workflows | ||
| .vscode | ||
| assets | ||
| content/en | ||
| layouts | ||
| resources | ||
| scripts | ||
| static | ||
| .dockerignore | ||
| .env.versions | ||
| .gitignore | ||
| .gitmodules | ||
| .htmltest.yml | ||
| .htmlvalidate.json | ||
| .markdownlint.json | ||
| config.yaml | ||
| devbox.json | ||
| devbox.lock | ||
| DOCKER.md | ||
| Dockerfile | ||
| go.mod | ||
| go.sum | ||
| hugo.toml | ||
| LIKEC4-QUICKSTART.md | ||
| package-lock.json | ||
| package.json | ||
| README-developer.md | ||
| README.md | ||
| RELEASE.md | ||
| Taskfile.yml | ||
| TESTING.md | ||
| VERSIONS.md | ||
IPCEICIS-DeveloperFramework Documentation
This repo contains business and architectural design and documentation of the DeveloperFramework subproject of IPCEI-CIS.
How to read and contribute to this documentation locally
The documentation is done in Hugo-format.
Hugo is a static site renderer - so to get the documentation site presented you need a running Hugo processor. Therefore there is
- either a Hugo
.devcontainer-definition - just run a devcontainer aware IDE or CLI, e.g. Visual Studio code - or a Hugo
Devbox-definition - in this case just run a devbox shell
Local installation of the Hugo documentation system
We describe two possible ways (one with devcontainer, one with devbox) to get the Hugo-documentation system locally running.
For both prepare the following three steps:
- open a terminal on your local box
- clone this repo:
git clone https://forgejo.edf-bootstrap.cx.fg1.ffm.osc.live/DevFW/website-and-documentation - change to the repo working dir:
cd website-and-documentation
Possibility 1: Hugo in a devcontainer
devcontainers are running containers as virtual systems on your local box. The defintion is in the .devcontainer folder.
Thus as preliminary you need a container daemon running, e.g. Docker.
There are several options to create and run the devcontainer - we present here two:
Option 1: Run the container triggered by and connected to an IDE, e.g. VS Code
- open the repo in an Devcontainer-aware tool/IDE (e.g.
code .) - start the
devcontainer(in VSC it'sF1 + Reopen in Devcontainer) - when the container is up & running just open your browser with
http://localhost:1313/
Option 2: Run the container natively
An alternative to get the container image is the devcontainer CLI, then you can run the devcontainer without VS Code. Thus as preliminary you need to do the install steps of the devconatiner cli.
- start the devcontainer by running:
devcontainer up --workspace-folder . - find out the IP address of the devconatiner by using
docker psanddocker inspect <id of container> - when the container is up & running just open your browser with
http://<DOCKER IP>:1313/
Possibility 2: Hugo in a devbox
Devboxes are locally isolated environments, managed by the Nix package manager. So first prepare the devbox.
Then
devbox shell- In the shell:
hugo serve
Editing
Documentation language
The documentation is done in Docsy-Theme.
So for editing content just goto the content-folder and edit content arrording to the Docsy documentation
Commiting
After having finished a unit of work commit and push.
Annex
Installation steps illustrated
When you run the above installation, the outputs could typically look like this:
In Visual Studio Code
Reopen in Container
Hugo server is running and (typically) listens to localhost:1313
After some installation time you have:
Final result in a web browser
