feat(docs): restructure documentation with new framework and templates

- Archive old docs to docs-old/ for reference - Create new top-down documentation structure: * Platform Overview: purpose, audience, product structure * Components: individual platform components (Forgejo, Kubernetes, Backstage) * Getting Started: onboarding and quick start guides * Operations: deployment, monitoring, troubleshooting * Governance: ADRs, project history, compliance - Add DOCUMENTATION-GUIDE.md with writing guidelines and templates - Add component template (TEMPLATE.md) for consistent documentation - Simplify root README and move technical docs to doc/ folder - Update test configuration: * Exclude legacy content from markdown linting * Relax HTML validation for theme-generated content * Skip link checking for legacy content in test:links * Keep 'task test' clean for technical writers (100% pass) * Add 'task test:full' with comprehensive link checking - Update home page with corrected markdown syntax - Fix internal links in archived content BREAKING CHANGE: Documentation structure changed from flat to hierarchical top-down approach
2025-11-16 13:32:10 +01:00 · 2025-11-16 13:32:10 +01:00 · 62999b41d0
commit 62999b41d0
parent 2ec2efe9fc
196 changed files with 907 additions and 160 deletions
--- a/content/en/docs-old/documentation/testing.md
+++ b/content/en/docs-old/documentation/testing.md
@ -0,0 +1,229 @@
+---
+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/).