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.
82 lines
1.7 KiB
Markdown
82 lines
1.7 KiB
Markdown
# 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 relationships
|
|
- `views.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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```markdown
|
|
{{< likec4-view view="overview" project="documentation-platform" >}}
|
|
```
|
|
|
|
## Configuration
|
|
|
|
- `likec4.config.json` - Project configuration
|
|
- `package.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
|