Stephan Lo
9aea2a3583
Created a complete documentation system for new documentors, including
interactive architecture diagrams and step-by-step guides for all documentation
workflows.
New LikeC4 architecture project (resources/doc-likec4/):
- Created documentation-platform.c4 model with 252 lines covering:
* Actors: documentor, reviewer, CI system, edge platform
* Tools: Hugo, LikeC4, Git, VS Code, markdownlint, htmltest
* Processes: local development, testing, CI/CD pipeline
* Repositories: git repo, cloudlet registry
- Defined 6 comprehensive views:
* overview: Complete documentation platform ecosystem
* localDevelopment: Local writing and preview workflow
* cicdPipeline: Automated testing and validation
* deploymentFlow: From commit to production
* fullWorkflow: End-to-end documentation lifecycle
* testingCapabilities: Quality assurance toolchain
New documentation pages (content/en/docs/documentation/):
- _index.md: Overview and introduction for new documentors
- local-development.md: Setting up local environment, live preview
- testing.md: Running markdown, HTML, and link validation
- cicd.md: Understanding automated CI/CD pipeline
- publishing.md: Deployment to Edge Connect Munich cloudlet
- quick-reference.md: Command reference and common tasks
Hugo shortcode for embedding LikeC4 diagrams:
- Created layouts/shortcodes/likec4-view.html
- Supports loading state with animated indicator
- Graceful error handling for missing views
- Automatic shadow DOM checking to ensure webcomponent loaded
- Usage: {{< likec4-view view="viewId" project="projectName" >}}
Supporting documentation:
- resources/LIKEC4-REGENERATION.md: Guide for regenerating webcomponents
- All diagrams are interactive and explorable in the browser
- Views include zoom, pan, and element inspection
This implementation provides:
1. Self-documenting documentation platform ("meta-documentation")
2. Visual learning for complex workflows via interactive diagrams
3. Clear separation of concerns (6 focused views vs 1 overwhelming diagram)
4. Onboarding path for new team members
5. Living architecture documentation that evolves with the platform
All new documentation passes markdown linting and builds successfully.
1.8 KiB
1.8 KiB
Regenerating LikeC4 Webcomponents
After modifying LikeC4 models (.c4 files), you need to regenerate the webcomponents.
Automatic Regeneration
Add to Taskfile.yml:
likec4:generate:
desc: Generate LikeC4 webcomponents from both projects
cmds:
- cd resources/edp-likec4 && npx likec4 codegen webcomponent --webcomponent-prefix likec4 --outfile ../../static/js/likec4-webcomponent.js
- cd resources/doc-likec4 && npx likec4 codegen webcomponent --webcomponent-prefix likec4 --outfile ../../static/js/likec4-doc-webcomponent.js
Then run:
task likec4:generate
Manual Regeneration
EDP Platform Architecture
cd resources/edp-likec4
npx likec4 codegen webcomponent \
--webcomponent-prefix likec4 \
--outfile ../../static/js/likec4-webcomponent.js
Documentation Platform Architecture
cd resources/doc-likec4
npx likec4 codegen webcomponent \
--webcomponent-prefix likec4 \
--outfile ../../static/js/likec4-doc-webcomponent.js
When to Regenerate
Regenerate webcomponents when you:
- ✅ Add new elements or relationships
- ✅ Modify existing models
- ✅ Create new views
- ✅ Change element properties (colors, shapes, etc.)
File Sizes
The webcomponents are large (~6MB total):
likec4-webcomponent.js- ~3.1MB (EDP architecture)likec4-doc-webcomponent.js- ~2.9MB (Documentation platform)
This is normal as they contain:
- React runtime
- Complete model data
- Diagram rendering engine
- Interactive controls
Note
Both webcomponents are loaded in layouts/partials/hooks/head-end.html as ES modules:
<script type="module" src="{{ "js/likec4-webcomponent.js" | relURL }}"></script>
<script type="module" src="{{ "js/likec4-doc-webcomponent.js" | relURL }}"></script>