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.7 KiB
1.7 KiB
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