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.
4.3 KiB
| title | linkTitle | weight | description |
|---|---|---|---|
| Testing | Testing | 30 | Quality assurance processes for documentation. |
Testing Philosophy
Quality documentation requires testing. Our testing process validates:
- Build integrity - Hugo can generate the site
- Content quality - Markdown follows best practices
- HTML validity - Generated HTML is well-formed
- Link integrity - No broken internal or external links
Testing Capabilities
{{< likec4-view view="testingCapabilities" project="documentation-platform" >}}
Local Testing
Before committing changes, run tests locally:
Quick Tests
For rapid feedback during development:
task test:quick
This runs:
task test:build- Hugo build validationtask test:markdown- Markdown linting
Full Test Suite
Before creating a pull request:
task test
This runs all tests including:
task test:build- Build validationtask test:markdown- Markdown lintingtask test:html- HTML validationtask test:links- Link checking
Individual Tests
You can run individual tests:
Build Test
Validates that Hugo can build the site:
task test:build
This runs: hugo --gc --minify --logLevel info
What it checks:
- Hugo configuration is valid
- Content files have correct frontmatter
- Templates render without errors
- No circular dependencies in content structure
Markdown Lint
Checks Markdown syntax and style:
task test:markdown
This uses markdownlint with custom rules in .markdownlint.json.
What it checks:
- Consistent heading hierarchy
- Proper list formatting
- Code blocks have language tags
- No trailing whitespace
- Consistent line length (where applicable)
Common issues:
- Missing blank lines around code blocks
- Inconsistent list markers
- Heading levels skipped
HTML Validation
Validates generated HTML:
task test:html
This uses htmlvalidate with rules in .htmlvalidate.json.
What it checks:
- Well-formed HTML5
- Proper nesting of elements
- Valid attributes
- Accessible markup
Link Checking
Verifies all links are valid:
task test:links
This uses htmltest configured in .htmltest.yml.
What it checks:
- Internal links point to existing pages
- External links are reachable
- Anchor links target existing elements
- No redirects (301/302)
Note: This test can be slow for large sites with many external links.
CI Testing
All tests run automatically on:
- Push to
main- Full test suite - Pull requests - Full test suite
View the GitHub Actions workflow: .github/workflows/test.yml
CI Test Results
If tests fail in CI:
- Check the GitHub Actions logs
- Look for specific test failures
- Run the same test locally:
task test:<name> - Fix the issue
- Commit and push
Artifacts
CI uploads test artifacts:
htmltest-report/- Link checking results
Download these from the GitHub Actions run to investigate failures.
Test Configuration Files
| File | Purpose |
|---|---|
.markdownlint.json |
Markdown linting rules |
.htmlvalidate.json |
HTML validation rules |
.htmltest.yml |
Link checker configuration |
Best Practices
- Test early, test often - Run
task test:quickfrequently - Fix issues immediately - Don't accumulate technical debt
- Understand failures - Read error messages carefully
- Update tests - If rules change, update config files
- Document exceptions - If you need to ignore a rule, document why
Common Issues and Solutions
Markdown: MD031 - Blank lines around fences
Problem: Missing blank line before/after code block
Solution: Add blank lines:
Some text
```bash
command here
```
More text
Markdown: MD032 - Blank lines around lists
Problem: Missing blank line before/after list
Solution: Add blank lines:
Text before
- List item 1
- List item 2
Text after
HTML: Invalid nesting
Problem: Elements improperly nested
Solution: Check template files and shortcodes
Link Check: 404 Not Found
Problem: Link points to non-existent page
Solution:
- Fix the link
- Create the missing page
- Remove the link if no longer relevant
Next Steps
Learn about the automated CI/CD pipeline.