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.
229 lines
4.3 KiB
Markdown
229 lines
4.3 KiB
Markdown
---
|
||
title: "Testing"
|
||
linkTitle: "Testing"
|
||
weight: 30
|
||
description: >
|
||
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:
|
||
|
||
```bash
|
||
task test:quick
|
||
```
|
||
|
||
This runs:
|
||
|
||
- `task test:build` - Hugo build validation
|
||
- `task test:markdown` - Markdown linting
|
||
|
||
### Full Test Suite
|
||
|
||
Before creating a pull request:
|
||
|
||
```bash
|
||
task test
|
||
```
|
||
|
||
This runs all tests including:
|
||
|
||
- `task test:build` - Build validation
|
||
- `task test:markdown` - Markdown linting
|
||
- `task test:html` - HTML validation
|
||
- `task test:links` - Link checking
|
||
|
||
## Individual Tests
|
||
|
||
You can run individual tests:
|
||
|
||
### Build Test
|
||
|
||
Validates that Hugo can build the site:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
1. Check the GitHub Actions logs
|
||
2. Look for specific test failures
|
||
3. Run the same test locally: `task test:<name>`
|
||
4. Fix the issue
|
||
5. 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
|
||
|
||
1. **Test early, test often** - Run `task test:quick` frequently
|
||
2. **Fix issues immediately** - Don't accumulate technical debt
|
||
3. **Understand failures** - Read error messages carefully
|
||
4. **Update tests** - If rules change, update config files
|
||
5. **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:
|
||
|
||
```markdown
|
||
Some text
|
||
|
||
```bash
|
||
command here
|
||
```
|
||
|
||
More text
|
||
```
|
||
|
||
### Markdown: MD032 - Blank lines around lists
|
||
|
||
**Problem:** Missing blank line before/after list
|
||
|
||
**Solution:** Add blank lines:
|
||
|
||
```markdown
|
||
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](../cicd/).
|