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.
53 lines
2.1 KiB
HTML
53 lines
2.1 KiB
HTML
{{- $view := .Get "view" -}}
|
|
{{- $project := .Get "project" | default "architecture" -}}
|
|
{{- $title := .Get "title" | default (print "Architecture View: " $view) -}}
|
|
{{- $uniqueId := printf "likec4-loading-%s" (md5 $view) -}}
|
|
|
|
<div class="likec4-container">
|
|
<div class="likec4-header">
|
|
{{ $title }}
|
|
</div>
|
|
<likec4-view view-id="{{ $view }}" browser="true"></likec4-view>
|
|
<div class="likec4-loading" id="{{ $uniqueId }}">
|
|
Loading architecture diagram...
|
|
</div>
|
|
</div>
|
|
|
|
<script>
|
|
(function() {
|
|
const loadingId = '{{ $uniqueId }}';
|
|
document.addEventListener('DOMContentLoaded', function() {
|
|
let attempts = 0;
|
|
const maxAttempts = 10;
|
|
|
|
function checkLikeC4Loading() {
|
|
attempts++;
|
|
const component = document.querySelector('likec4-view[view-id="{{ $view }}"]');
|
|
const loading = document.getElementById(loadingId);
|
|
|
|
if (component && component.shadowRoot && component.shadowRoot.children.length > 0) {
|
|
if (loading) loading.style.display = 'none';
|
|
console.log('LikeC4 component "{{ $view }}" loaded successfully');
|
|
} else if (attempts >= maxAttempts) {
|
|
console.warn('LikeC4 component "{{ $view }}" failed to load');
|
|
if (loading) {
|
|
loading.innerHTML = 'Interactive diagram failed to load. <br><small>Please ensure JavaScript is enabled and the webcomponent is generated.</small>';
|
|
loading.style.color = '#dc3545';
|
|
}
|
|
} else {
|
|
setTimeout(checkLikeC4Loading, 1000);
|
|
}
|
|
}
|
|
|
|
if (typeof window.customElements !== 'undefined') {
|
|
setTimeout(checkLikeC4Loading, 1500);
|
|
} else {
|
|
const loading = document.getElementById(loadingId);
|
|
if (loading) {
|
|
loading.innerHTML = 'Interactive diagrams require a modern browser with JavaScript enabled.';
|
|
loading.style.color = '#dc3545';
|
|
}
|
|
}
|
|
});
|
|
})();
|
|
</script>
|