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.
275 lines
4.7 KiB
Markdown
275 lines
4.7 KiB
Markdown
---
|
|
title: "Quick Reference"
|
|
linkTitle: "Quick Reference"
|
|
weight: 60
|
|
description: >
|
|
Cheat sheet for common documentor tasks.
|
|
---
|
|
|
|
## Common Commands
|
|
|
|
### Local Development
|
|
|
|
```bash
|
|
# Start development server (with hot reload)
|
|
task serve
|
|
|
|
# Build for production
|
|
task build
|
|
|
|
# Build for development (faster, no minification)
|
|
task build:dev
|
|
|
|
# Clean build artifacts
|
|
task clean
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# Quick tests (build + markdown)
|
|
task test:quick
|
|
|
|
# Full test suite
|
|
task test
|
|
|
|
# Individual tests
|
|
task test:build # Hugo build validation
|
|
task test:markdown # Markdown linting
|
|
task test:html # HTML validation
|
|
task test:links # Link checking
|
|
```
|
|
|
|
### Dependencies
|
|
|
|
```bash
|
|
# Install dependencies
|
|
task deps:install
|
|
|
|
# Update dependencies
|
|
task deps:update
|
|
|
|
# Ensure npm dependencies (auto-installs if missing)
|
|
task deps:ensure-npm
|
|
```
|
|
|
|
### Container Operations
|
|
|
|
```bash
|
|
# Build OCI/Docker image
|
|
task build:oci-image
|
|
|
|
# Build and test container
|
|
task test:oci-image
|
|
```
|
|
|
|
## File Locations
|
|
|
|
### Content
|
|
|
|
| Path | Description |
|
|
|------|-------------|
|
|
| `content/en/docs/` | Main documentation |
|
|
| `content/en/blog/` | Blog posts |
|
|
| `content/en/_index.md` | Homepage |
|
|
|
|
### Architecture Models
|
|
|
|
| Path | Description |
|
|
|------|-------------|
|
|
| `resources/edp-likec4/` | Platform architecture models |
|
|
| `resources/doc-likec4/` | Documentation platform models |
|
|
|
|
### Configuration
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `hugo.toml` | Hugo configuration |
|
|
| `config.yaml` | Docsy theme config |
|
|
| `Taskfile.yml` | Task definitions |
|
|
| `package.json` | npm dependencies and scripts |
|
|
| `.markdownlint.json` | Markdown linting rules |
|
|
| `.htmlvalidate.json` | HTML validation rules |
|
|
| `.htmltest.yml` | Link checker config |
|
|
|
|
### Build Output
|
|
|
|
| Path | Description |
|
|
|------|-------------|
|
|
| `public/` | Generated static site |
|
|
| `resources/_gen/` | Generated resources (Hugo) |
|
|
| `data/build_info.json` | Build metadata (git commit, version) |
|
|
|
|
## Markdown Frontmatter
|
|
|
|
### Standard Page
|
|
|
|
```yaml
|
|
---
|
|
title: "Page Title"
|
|
linkTitle: "Short Title"
|
|
weight: 10
|
|
description: >
|
|
Brief description for SEO and navigation.
|
|
---
|
|
```
|
|
|
|
### Blog Post
|
|
|
|
```yaml
|
|
---
|
|
title: "Post Title"
|
|
date: 2025-01-15
|
|
author: "Your Name"
|
|
description: >
|
|
Post summary.
|
|
---
|
|
```
|
|
|
|
## Embedding Architecture Diagrams
|
|
|
|
### Basic Embed
|
|
|
|
```markdown
|
|
{{< likec4-view view="view-name" project="project-name" >}}
|
|
```
|
|
|
|
### Examples
|
|
|
|
```markdown
|
|
{{< likec4-view view="overview" project="documentation-platform" >}}
|
|
{{< likec4-view view="localDevelopment" project="documentation-platform" >}}
|
|
{{< likec4-view view="cicdPipeline" project="documentation-platform" >}}
|
|
```
|
|
|
|
## LikeC4 Commands
|
|
|
|
### Regenerate Webcomponents
|
|
|
|
After modifying `.c4` files:
|
|
|
|
```bash
|
|
task likec4:generate
|
|
```
|
|
|
|
This regenerates both:
|
|
|
|
- `static/js/likec4-webcomponent.js` (EDP architecture)
|
|
- `static/js/likec4-doc-webcomponent.js` (Documentation platform)
|
|
|
|
### Start Development Server
|
|
|
|
```bash
|
|
cd resources/doc-likec4 # or resources/edp-likec4
|
|
npm install
|
|
npm start
|
|
```
|
|
|
|
Opens LikeC4 IDE at `http://localhost:5173`
|
|
|
|
### Export Diagrams
|
|
|
|
```bash
|
|
cd resources/doc-likec4
|
|
npx likec4 export png -o ./images .
|
|
```
|
|
|
|
## Git Workflow
|
|
|
|
### Feature Branch
|
|
|
|
```bash
|
|
# Create feature branch
|
|
git checkout -b feature/your-feature
|
|
|
|
# Make changes and test
|
|
task serve
|
|
task test:quick
|
|
|
|
# Commit
|
|
git add .
|
|
git commit -m "Description of changes"
|
|
|
|
# Push
|
|
git push origin feature/your-feature
|
|
|
|
# Create pull request on GitHub
|
|
```
|
|
|
|
### Update from Main
|
|
|
|
```bash
|
|
git checkout main
|
|
git pull origin main
|
|
git checkout feature/your-feature
|
|
git rebase main
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Port 1313 in use
|
|
|
|
```bash
|
|
lsof -ti:1313 | xargs kill -9
|
|
```
|
|
|
|
### Build errors
|
|
|
|
```bash
|
|
task clean
|
|
task build:dev
|
|
```
|
|
|
|
### Missing dependencies
|
|
|
|
```bash
|
|
task deps:install
|
|
```
|
|
|
|
### Hugo module issues
|
|
|
|
```bash
|
|
hugo mod clean
|
|
hugo mod get -u
|
|
hugo mod tidy
|
|
```
|
|
|
|
### LikeC4 language server
|
|
|
|
In VS Code: `Ctrl+Shift+P` → "LikeC4: restart language server"
|
|
|
|
## URLs
|
|
|
|
### Local Development
|
|
|
|
- **Documentation:** <http://localhost:1313>
|
|
- **LikeC4 IDE:** <http://localhost:5173> (when running `npm start` in likec4 folder)
|
|
|
|
### Production
|
|
|
|
Check `edgeconnectdeployment.yaml` for deployment URL or run:
|
|
|
|
```bash
|
|
kubectl get service edpdoc -n <namespace>
|
|
```
|
|
|
|
## Quick Checks Before Committing
|
|
|
|
1. ✅ `task test:quick` passes
|
|
2. ✅ Preview looks correct in browser
|
|
3. ✅ No broken links (visual check)
|
|
4. ✅ Architecture diagrams render
|
|
5. ✅ Frontmatter is correct
|
|
|
|
## Getting Help
|
|
|
|
- **Hugo docs:** <https://gohugo.io/documentation/>
|
|
- **Docsy theme:** <https://www.docsy.dev/docs/>
|
|
- **LikeC4:** <https://likec4.dev/>
|
|
- **Task:** <https://taskfile.dev/>
|
|
|
|
## View Documentation Architecture
|
|
|
|
To understand how this documentation platform works:
|
|
|
|
→ Start here: [Documentation About Documentation](../)
|