Added two complementary quick-start guides to help new contributors get
productive quickly without reading extensive documentation.
DOCUMENTOR-GUIDE.md:
- Quick-start guide for new documentation contributors
- Covers essential workflows: local dev, testing, committing
- Provides command reference for common tasks
- Links to detailed documentation platform guides
- Targets: writers, editors, content contributors
- Goal: Productive in 5 minutes
README-ARCHITECTURE.md:
- Quick-start guide for architecture diagram contributors
- Explains LikeC4 setup and project structure
- Covers both edp-likec4 (platform) and doc-likec4 (meta-docs) projects
- Provides regeneration workflow for webcomponents
- Targets: architects, system designers, technical writers
- Goal: Productive diagram editing in 5 minutes
These guides complement the detailed documentation in content/en/docs/documentation/
by providing a fast-track onboarding path. New contributors can start with these
quick-start guides and refer to detailed documentation as needed.
Documentation hierarchy:
1. Quick-start (these guides) - Get started in minutes
2. Full guides (content/en/docs/documentation/) - Comprehensive workflows
3. Architecture diagrams - Visual learning and exploration
Benefits:
- Reduced onboarding time for new team members
- Self-service documentation for common tasks
- Clear separation between quick reference and detailed guides
- Consistent documentation patterns across roles
Added .markdownlintignore to exclude legacy v1 documentation and blog posts
from markdown linting. This allows the team to focus on maintaining quality
for actively maintained documentation while avoiding the need to fix 200+
pre-existing lint errors in historical content.
Excluded paths:
- content/en/docs/v1/** (legacy v1 documentation with historical lint debt)
- content/en/blog/** (blog posts with varied formatting styles)
Fixed markdown linting errors in current documentation:
- content/en/docs/_index.md: Removed excessive blank lines
- content/en/docs/decisions/0001-pipeline-tools.md:
* Converted emphasis (**Pro**, **Con**) to proper h4 headings
* Improves document structure and accessibility
* Maintains visual hierarchy while meeting markdown standards
Fixed sample v1 files that were blocking CI:
- content/en/docs/v1/solution/tools/Crossplane/provider-kind/_index.md:
* Replaced hard tabs with spaces (MD010)
* Added language tags to code blocks (bash)
- content/en/docs/v1/solution/tools/kyverno integration/_index.md:
* Added blank line before list items (MD032)
* Added language tags to code blocks (bash)
Impact:
- task test:quick now passes cleanly
- CI pipeline markdown validation succeeds
- New documentation maintains high quality standards
- Legacy content preserved without blocking development
This approach balances:
1. Maintaining quality for actively developed docs
2. Not requiring massive refactoring of legacy content
3. Enabling clean CI/CD pipeline
4. Providing clear quality standards for future contributions
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.
Renamed resources/likec4 to resources/edp-likec4 to better reflect that this
directory contains the Enterprise Developer Platform architecture models,
not documentation platform architecture.
Extended element kinds in edp-likec4/models/spec.c4 to support documentation
platform modeling:
- Added person, tool, process, repository element kinds
- These allow modeling of documentation workflows and processes
Consolidated webcomponent generation:
- Combined both architecture projects (edp-likec4 and doc-likec4) into a
single webcomponent output at static/js/likec4-webcomponent.js
- Updated Taskfile.yml to generate from edp-likec4 directory
- Removed duplicate webcomponent script loading in head-end.html
- Fixed CustomElementRegistry duplicate registration issue
Embedded TeleNeoOffice corporate fonts:
- Added font files to static/fonts/ and static/ root
- Required for correct rendering of diagrams in webcomponent
- Fonts are embedded in webcomponent but also served from Hugo static paths
- Fixed 404 errors for font loading
Updated architecture documentation:
- Fixed markdown linting issues (trailing spaces, fence spacing)
- Updated all references from resources/likec4 to resources/edp-likec4
- Enhanced setup.md with correct directory structure
This refactoring enables:
1. Clear separation between EDP architecture and documentation platform models
2. Single consolidated webcomponent containing all architecture views
3. Proper font loading for corporate branding in diagrams
4. Foundation for future architecture documentation expansion
Breaking changes: None (paths updated in documentation)
- Enable offlineSearch = true for client-side search functionality
- Disable Google Custom Search to avoid external API dependency
- Provides instant search across all documentation content
- Works completely offline without server requirements
- Display current branch/tag and commit hash in navbar center
- Show dirty working directory indicator with yellow badge
- Add automatic build info generation in Task workflow
- Include build timestamp and user information
- Style with responsive design (hidden on mobile)
- Add .gitignore entries for generated build artifacts
- Add deps:ensure-npm task to automatically install npm packages when needed
- Configure build, serve, and test tasks to depend on npm dependencies
- Use Task's sources/generates/status for intelligent dependency detection
- Prevents build failures due to missing PostCSS and other npm packages
- Improves developer experience by eliminating manual npm install steps
Pin package versions from @latest to concrete versions for reproducible
development environments across the team.
Changes:
- go: latest → 1.25.1
- hugo: latest → 0.151.0
- nodejs: latest → 24.10.0
- Added nixpkgs-unstable entry (2025-10-20)
This ensures all developers use identical tool versions, improving
build reproducibility and reducing "works on my machine" issues.
Implement complete integration of LikeC4 interactive architecture
diagrams into the Hugo/Docsy documentation system, enabling embedded
web components for exploring C4 models directly in documentation pages.
Integration Components:
Static Assets:
- static/js/likec4-webcomponent.js (3.1 MB) - Generated web component
containing all 54 C4 views as interactive embeddable elements
- static/js/likec4-loader.js - Dynamic ES6 module loader with fallback
paths for robust component loading across different page depths
- static/css/likec4-styles.css - Styling for diagram containers with
dark mode support for Docsy theme compatibility
Hugo Configuration:
- hugo.toml - Added params.likec4.enable configuration flag
- layouts/partials/hooks/head-end.html - Hook to inject CSS and JS
when LikeC4 is enabled site-wide
Documentation:
- content/en/docs/architecture/_index.md - Architecture section index
- content/en/docs/architecture/highlevelarch.md - Example page with
interactive OTC FaaS deployment diagram demonstrating integration
- content/en/docs/architecture/setup.md - Comprehensive setup guide
covering installation, usage, workflow, and troubleshooting
- resources/likec4/INTEGRATION.md - Technical integration details
- LIKEC4-QUICKSTART.md - Quick start guide for developers
Features:
- Interactive diagram exploration (click components for details)
- Automatic loading indicators with timeout fallback
- Graceful degradation for non-JS environments
- Dark mode support matching Docsy theme
- Multiple diagrams per page support
- Browser compatibility detection
Usage Pattern:
```html
<div class="likec4-container">
<div class="likec4-header">Diagram Title</div>
<likec4-view view-id="otc-faas" browser="true"></likec4-view>
<div class="likec4-loading">Loading...</div>
</div>
```
Workflow:
1. Edit .c4 files in resources/likec4/
2. Run: npx likec4 gen webcomponent --webcomponent-prefix likec4
--outfile ../../static/js/likec4-webcomponent.js
3. Commit both model changes and regenerated webcomponent
Available Views:
- otc-faas, edp, landscape, edpbuilderworkflow
- keycloak, forgejo, argocd, crossplane, monitoring
- And 40+ more component and deployment views
The integration preserves the MkDocs-style embedding approach from
edp-doc while adapting it to Hugo's static site generation model.
This completes the migration making this repository the central hub
for both C4 architecture models and their rendered documentation.
Port the complete LikeC4 architecture documentation from the edp-doc
repository to this repository, establishing it as the primary source
for C4 architecture models.
Migration Details:
- Migrated all C4 models from edp-doc/docs/likec4 to resources/likec4/
- Preserved Git history using git filter-branch and git read-tree
- Includes 54 C4 source files covering deployment, components, and views
- Updated LikeC4 to v1.42.1 (from deprecated v0.40.0)
Directory Structure:
- resources/likec4/models/ - C4 model definitions (components, containers, context, code)
- resources/likec4/views/ - View definitions (deployment, EDP, high-level concepts, dynamic)
- resources/likec4/deployment/ - Deployment-specific models (KIND, OTC)
- resources/likec4/doc/ - Documentation and screenshots
Architecture Coverage:
- OTC FaaS deployment architecture
- EDP component and container models
- Developer landscape and workflows
- GitOps inner/outer loop processes
- Infrastructure components (ArgoCD, Forgejo, Keycloak, Crossplane, etc.)
Dependencies:
- likec4@1.42.1
- @likec4/cli@0.40.0
This migration makes the ipceicis-developerframework repository the
authoritative source for architecture documentation. The edp-doc
repository may reference these models via git submodule if needed.
Related: Migration from https://edp.buildth.ing/DevFW/edp-doc
Use Docker's TARGETARCH variable to download the correct architecture
binaries for Go and Hugo during multi-platform builds. This fixes the
build failure for linux/arm64 where amd64 binaries were being downloaded.
- Add ARG TARGETARCH to capture target architecture
- Replace hardcoded linux-amd64 with linux-${TARGETARCH}
- Applies to both Go and Hugo downloads
- Backwards compatible with local single-platform builds
- Remove package-lock.json from .gitignore
- Add package-lock.json to repository (required for npm ci in Docker build)
- npm ci requires package-lock.json to ensure reproducible builds
Remove auto-generated Hugo image files from resources/_gen/.
These files are build artifacts and should not be version controlled
(already listed in .gitignore but were previously committed).
- Add multi-stage Dockerfile with pinned tool versions (Node 24.10.0, Go 1.25.1, Hugo 0.151.0)
- Create .env.versions as single source of truth for all tool versions
- Add GitHub Actions CI workflow for automated OCI image builds
- Multi-arch support (amd64, arm64)
- Automatic version loading from .env.versions
- Docker registry push with metadata tags
- Add Taskfile tasks for local OCI image building and testing
- task build:oci-image - Build with version-pinned dependencies
- task test:oci-image - Build and test container locally
- Pin devbox.json to specific versions matching .env.versions
- Add comprehensive documentation (DOCKER.md, VERSIONS.md)
- Add helper script (scripts/get-versions.sh) for version extraction
This enables consistent development and production environments with
identical tool versions across local devbox, Docker builds, and CI/CD.
- Style inline code blocks (backticks) with soft pink background
- Use Telekom magenta for code text color
- Add border-radius and padding for better readability
- Distinguish inline code from fenced code blocks
- Add TeleNeo font family with all weights (300-700)
- Implement Telekom brand colors (magenta #E20074 as primary)
- Add dark mode support with inverted color palette
- Style navigation with soft hover states and active indicators
- Override Bootstrap/Docsy variables for consistent theming
- Fix deprecated Hugo template syntax for Disqus integration
- Apply Telekom-inspired styling to all UI components
- Move all existing docs content (concepts, project, solution) to /docs/v1/
- Add legacy banner component to warn users about archived documentation
- Create v1 index page with legacy notice and redirect guidance
- Implement automatic banner display for all v1 paths
- Preserve all original content for reference during migration
This enables incremental content migration while maintaining access to
original documentation.
- Add npm test scripts for build, markdown, HTML, and link validation
- Install markdownlint-cli for content quality checks
- Install html-validate for HTML5 conformity validation
- Add htmltest (via devbox) for internal/external link checking
- Configure test rules in .htmltest.yml, .htmlvalidate.json, .markdownlint.json
- Add GitHub Actions workflow for automated CI testing
- Add TESTING.md documentation for test usage
- Upgrade Hugo from v0.125.4 to v0.151.0+extended
- Upgrade Docsy theme from v0.10.0 to v0.12.0
- Update Bootstrap to v5.3.8
- Update Go to v1.25.1
- Add Node.js for PostCSS support
- Install PostCSS, autoprefixer dependencies
- Remove obsolete custom render-heading template
- Update minimum Hugo version requirement to 0.151.0
