Stephan Lo
97cd265063
- Add title parameter documentation to all relevant README files - Update DOCUMENTOR-GUIDE.md with title parameter example - Enhance quick-reference.md with complete parameter list - Update INTEGRATION.md with recommended shortcode usage - Simplify highlevelarch.md by using shortcode with title parameter
8.5 KiB
8.5 KiB
Documentation Platform - Visual Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ DOCUMENTATION REPOSITORY STRUCTURE │
└─────────────────────────────────────────────────────────────────────────────┘
📁 Repository Root
│
├── 📁 resources/
│ │
│ ├── 📁 edp-likec4/ ← Platform Architecture
│ │ ├── documentation-platform.c4 (Models for EDP systems)
│ │ ├── views.c4
│ │ ├── models/
│ │ └── views/
│ │
│ └── 📁 doc-likec4/ ← Documentation Platform Architecture
│ ├── documentation-platform.c4 (Models for this doc system)
│ ├── views.c4
│ ├── likec4.config.json
│ ├── package.json
│ └── README.md
│
├── 📁 content/en/docs/
│ │
│ ├── 📁 architecture/ ← Platform Architecture Docs
│ │ ├── highlevelarch.md
│ │ └── setup.md
│ │
│ └── 📁 documentation/ ← Documentation About Documentation
│ ├── _index.md (Overview for Documentors)
│ ├── local-development.md (How to work locally)
│ ├── testing.md (Quality assurance)
│ ├── cicd.md (CI/CD pipeline)
│ ├── publishing.md (Deployment to edge)
│ └── quick-reference.md (Cheat sheet)
│
├── 📄 Taskfile.yml ← Build Automation
├── 📄 .github/workflows/test.yml ← CI Pipeline
├── 📄 k8s-deployment.yaml ← Kubernetes Config
├── 📄 edgeconnectdeployment.yaml ← Edge Deployment Config
├── 📄 Dockerfile ← Container Definition
└── 📄 README-ARCHITECTURE.md ← This Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ DOCUMENTOR WORKFLOW │
└─────────────────────────────────────────────────────────────────────────────┘
👤 Documentor
│
├──> 1. Write Content
│ └── content/en/docs/**/*.md
│
├──> 2. Create Architecture Models
│ └── resources/doc-likec4/*.c4
│ resources/edp-likec4/*.c4
│
├──> 3. Local Development
│ └── task serve
│ http://localhost:1313
│
├──> 4. Test Locally
│ └── task test:quick
│ - Build validation
│ - Markdown lint
│
├──> 5. Commit & Push
│ └── git push origin feature-branch
│
└──> 6. CI/CD Pipeline
├── GitHub Actions
│ ├── Build Test
│ ├── Markdown Lint
│ ├── HTML Validation
│ └── Link Checking
│
├── Container Build
│ └── Docker Image
│
└── Edge Deployment
└── Kubernetes on Munich Cloudlet
└── http://<external-ip>
┌─────────────────────────────────────────────────────────────────────────────┐
│ ARCHITECTURE VISUALIZATION │
└─────────────────────────────────────────────────────────────────────────────┘
Two Separate LikeC4 Projects:
┌──────────────────────────────┐ ┌──────────────────────────────┐
│ resources/edp-likec4/ │ │ resources/doc-likec4/ │
│ ───────────────────── │ │ ───────────────────── │
│ │ │ │
│ Platform Architecture │ │ Documentation Platform │
│ ──────────────────── │ │ ──────────────────── │
│ │ │ │
│ • Systems │ │ • Hugo/Docsy │
│ • Services │ │ • LikeC4 Integration │
│ • Infrastructure │ │ • Taskfile │
│ • Deployment Environments │ │ • GitHub Actions │
│ │ │ • Edge Deployment │
│ What we BUILD │ │ How we DOCUMENT │
│ │ │ │
└──────────────────────────────┘ └──────────────────────────────┘
│ │
│ │
▼ ▼
content/en/docs/ content/en/docs/
architecture/ documentation/
┌─────────────────────────────────────────────────────────────────────────────┐
│ QUICK START │
└─────────────────────────────────────────────────────────────────────────────┘
For New Documentors:
1. 📖 Read the Guide
→ Open: content/en/docs/documentation/_index.md
→ Or browse: http://localhost:1313/docs/documentation/
2. 🚀 Start Development
$ task serve
3. 📊 View Architecture
$ cd resources/doc-likec4
$ npm install
$ npm start
→ Opens: http://localhost:5173
4. ✅ Test Your Changes
$ task test:quick
5. 📚 Reference
→ Quick Reference: content/en/docs/documentation/quick-reference.md
┌─────────────────────────────────────────────────────────────────────────────┐
│ AVAILABLE VIEWS │
└─────────────────────────────────────────────────────────────────────────────┘
In resources/doc-likec4/views.c4:
• overview → Complete system overview
• localDevelopment → Documentor workflow with Taskfile
• cicdPipeline → Automated testing via GitHub Actions
• deploymentFlow → Edge deployment process
• fullWorkflow → End-to-end content → production
• testingCapabilities → All automated tests
Embed in Markdown:
{{< likec4-view view="overview" project="documentation-platform" >}}
With custom title:
{{< likec4-view view="overview" project="documentation-platform" title="Platform Overview" >}}