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.
|
||
|---|---|---|
| .. | ||
| documentation-platform.c4 | ||
| likec4.config.json | ||
| node_modules | ||
| package.json | ||
| README.md | ||
Documentation Platform Architecture
This folder contains LikeC4 architecture models that document the documentation platform itself.
Purpose
These models help new Documentors understand:
- How the documentation platform works
- The local development workflow
- CI/CD pipeline and testing processes
- Deployment to edge infrastructure
Models
documentation-platform.c4- Main model with all elements and relationshipsviews.c4- View definitions for different perspectives
Views
Overview
High-level view of the entire documentation platform, showing all major components.
Local Development Workflow
How a documentor works locally with content, Taskfile, and Hugo server.
CI/CD Pipeline
Automated testing and container build process via GitHub Actions.
Deployment Flow
How documentation is deployed to the edge environment via Kubernetes.
Full Workflow
End-to-end process from content creation to published documentation.
Testing Capabilities
All automated tests that ensure documentation quality.
Usage
Start LikeC4 Development Server
cd resources/doc-likec4
npm install
npm start
This opens the LikeC4 IDE in your browser where you can:
- Edit models interactively
- Preview views in real-time
- Export diagrams
Embed in Documentation
In your Markdown files:
{{< likec4-view view="overview" project="documentation-platform" >}}
Configuration
likec4.config.json- Project configurationpackage.json- LikeC4 CLI dependencies
Related Documentation
The models are documented in: content/en/docs/documentation/
- Overview and introduction
- Local development guide
- Testing processes
- CI/CD pipeline
- Publishing to edge