Patrick.Sy/website-and-documentation
1
0
Fork 0
forked from DevFW-CICD/website-and-documentation
Code Pull requests Activity

feat(docs): add comprehensive documentation platform architecture and guides

Browse source 
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.
This commit is contained in:
Stephan Lo 2025-11-07 11:50:58 +01:00
parent 3239cfbc62
commit 9aea2a3583
14 changed files with 2619 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

43
content/en/docs/documentation/_index.md Normal file
View file

@ -0,0 +1,43 @@
---
title: "Documentation About Documentation"
linkTitle: "Documentation"
weight: 10
description: >
Learn how to create, maintain, and publish documentation for the developer platform.
---
Welcome to the meta-documentation! This section explains how our documentation platform works and guides you through the documentor role.
## What is a Documentor?
A **Documentor** is responsible for creating, maintaining, and publishing the developer platform documentation. This includes:
- Writing and updating content in Markdown
- Creating architecture diagrams with LikeC4
- Testing locally before committing
- Following the CI/CD pipeline to production
## Documentation Platform Architecture
Our documentation is built on a modern stack:
- **Hugo** with the **Docsy** theme for static site generation
- **LikeC4** for architecture visualization
- **Taskfile** for local development automation
- **GitHub Actions** for continuous testing
- **Edge deployment** for hosting
### System Overview
{{< likec4-view view="overview" project="documentation-platform" >}}
This high-level view shows all major components of the documentation platform.
## Getting Started
Continue to the next sections to learn about:
1. [Local Development](local-development/) - How to work on documentation locally
2. [Testing](testing/) - Quality assurance processes
3. [CI/CD Pipeline](cicd/) - Automated testing and deployment
4. [Publishing](publishing/) - How documentation reaches production

264
content/en/docs/documentation/cicd.md Normal file
View file

@ -0,0 +1,264 @@
---
title: "CI/CD Pipeline"
linkTitle: "CI/CD"
weight: 40
description: >
Automated testing and container build process.
---
## Overview
Our documentation uses a continuous integration and deployment pipeline to ensure quality and automate deployment.
{{< likec4-view view="cicdPipeline" project="documentation-platform" >}}
## GitHub Actions Workflow
The CI/CD pipeline is defined in `.github/workflows/test.yml` and runs on:
- **Pushes to `main` branch**
- **Pull requests to `main` branch**
### Workflow Steps
#### 1. Checkout Code
```yaml
- uses: actions/checkout@v4
with:
submodules: recursive
fetch-depth: 0
```
- Clones repository with full history
- Includes Git submodules (Hugo modules)
#### 2. Setup Hugo
```yaml
- name: Setup Hugo
uses: peaceiris/actions-hugo@v3
with:
hugo-version: 'latest'
extended: true
```
- Installs Hugo Extended
- Uses latest stable version
#### 3. Setup Node.js
```yaml
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '24'
cache: 'npm'
```
- Installs Node.js v24
- Caches npm dependencies for faster builds
#### 4. Install Dependencies
```bash
npm ci
go install github.com/wjdp/htmltest@latest
```
- Installs npm packages (markdownlint, htmlvalidate)
- Installs htmltest for link checking
#### 5. Run Tests
```bash
npm run test:build
npm run test:markdown
npm run test:html
```
- Validates Hugo build
- Lints Markdown files
- Validates HTML output
#### 6. Link Checking
```yaml
- name: Run link checker
run: htmltest
continue-on-error: true
```
- Checks all links
- Continues even if links fail (soft requirement)
#### 7. Upload Results
```yaml
- name: Upload htmltest results
uses: actions/upload-artifact@v4
if: always()
with:
name: htmltest-report
path: tmp/.htmltest/
```
- Uploads link check report
- Available for download from GitHub Actions
## Container Build Process
After tests pass, a container image is built:
```bash
task build:oci-image
```
### Build Process
1. **Reads version information** from `.env.versions`:
- `NODE_VERSION`
- `GO_VERSION`
- `HUGO_VERSION`
2. **Builds Docker image** using `Dockerfile`:
- Multi-stage build
- Hugo generates static site
- Nginx serves the content
3. **Tags image** with:
- `latest`
- Git commit SHA (short)
### Dockerfile Structure
```dockerfile
# Build stage
FROM node:${NODE_VERSION} as builder
# Install Hugo, build dependencies
# Run: hugo --gc --minify
# Output: public/ directory
# Runtime stage
FROM nginx:alpine
# Copy public/ to /usr/share/nginx/html/
# Configure Nginx
```
### Testing the Container
```bash
task test:oci-image
```
This:
1. Builds the image
2. Starts container on port 8080
3. Tests HTTP endpoint
4. Cleans up container
## Package.json Scripts
The `package.json` defines test scripts:
```json
{
"scripts": {
"test:build": "hugo --gc --minify --logLevel info",
"test:markdown": "markdownlint 'content/**/*.md'",
"test:html": "htmlvalidate 'public/**/*.html'"
}
}
```
## Running CI Locally
Simulate the CI environment locally:
```bash
task ci
```
This runs the same tests as GitHub Actions.
## Monitoring CI Results
### Successful Build
✅ All tests pass → Ready to deploy
### Failed Build
❌ Tests fail:
1. Click on the failed workflow in GitHub Actions
2. Expand the failed step
3. Read the error message
4. Fix locally: `task test:<specific-test>`
5. Commit and push fix
### Viewing Artifacts
1. Go to GitHub Actions
2. Click on workflow run
3. Scroll to "Artifacts" section
4. Download `htmltest-report`
## Best Practices
1. **Don't push to main directly** - Use feature branches and PRs
2. **Wait for CI before merging** - Green checkmark required
3. **Fix broken builds immediately** - Don't let main stay red
4. **Review CI logs** - Understand why tests fail
5. **Update dependencies** - Keep versions current in `.env.versions`
## Continuous Deployment
After successful CI:
1. Container image is built
2. Image is pushed to registry
3. Deployment process begins (see [Publishing](../publishing/))
## Troubleshooting
### Tests pass locally but fail in CI
**Possible causes:**
- Different Hugo version
- Different Node.js version
- Missing dependencies
- Environment-specific issues
**Solution:** Check versions in `.env.versions` and ensure local matches CI
### Build timeouts
**Possible causes:**
- Link checker taking too long
- Large number of external links
**Solution:**
- Use `continue-on-error: true` for link checks
- Configure `.htmltest.yml` to skip slow checks
### Cache issues
**Solution:** Clear GitHub Actions cache:
```yaml
- uses: actions/cache@v4
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
```
Update the cache key to force refresh.
## Next Steps
Learn about [deployment to Edge environment](../publishing/).

196
content/en/docs/documentation/local-development.md Normal file
View file

@ -0,0 +1,196 @@
---
title: "Local Development"
linkTitle: "Local Development"
weight: 20
description: >
Set up your local environment and learn the documentor workflow.
---
## Prerequisites
Before you start, ensure you have:
- **Devbox** or the following tools installed:
- Hugo Extended (latest version)
- Node.js (v24+)
- Go (for htmltest)
- Git
## Installation
1. Clone the repository:
```bash
git clone <repository-url>
cd ipceicis-developerframework
```
2. Install dependencies:
```bash
task deps:install
```
## Local Development Workflow
{{< likec4-view view="localDevelopment" project="documentation-platform" >}}
### Starting the Development Server
The easiest way to work locally is to start the Hugo development server:
```bash
task serve
```
This will:
- Generate build information (git commit, version)
- Start Hugo server on `http://localhost:1313`
- Enable hot reload - changes appear instantly in the browser
### Content Structure
```text
content/
└── en/ # English content
├── _index.md # Homepage
├── blog/ # Blog posts
└── docs/ # Documentation
├── architecture/ # Architecture docs
├── decisions/ # ADRs
└── v1/ # Version-specific docs
```
### Creating Content
1. **Add a new documentation page:**
```bash
# Create a new markdown file
vim content/en/docs/your-topic/_index.md
```
2. **Add frontmatter:**
```yaml
---
title: "Your Topic"
linkTitle: "Your Topic"
weight: 10
description: >
Brief description of your topic.
---
```
3. **Write your content** in Markdown
4. **Preview changes** - they appear immediately if `task serve` is running
### Creating Architecture Diagrams
Architecture diagrams are created with LikeC4:
1. **Navigate to the appropriate LikeC4 project:**
- `resources/edp-likec4/` - Platform architecture
- `resources/doc-likec4/` - Documentation platform architecture
2. **Edit or create `.c4` files** with your model
3. **Regenerate webcomponents:**
```bash
task likec4:generate
```
4. **Embed diagrams in Markdown:**
```markdown
{{< likec4-view view="localDevelopment" title="Local Development Workflow" >}}
```
Available views:
- `overview` - Complete system overview
- `localDevelopment` - Documentor workflow
- `cicdPipeline` - CI/CD process
- `deploymentFlow` - Edge deployment
- `fullWorkflow` - End-to-end workflow
- `testingCapabilities` - Testing overview
## Available Tasks
View all available tasks:
```bash
task --list
```
### Common Development Tasks
| Task | Description |
|------|-------------|
| `task serve` | Start development server with hot reload |
| `task build` | Build production-ready site |
| `task build:dev` | Build development version |
| `task clean` | Remove build artifacts |
| `task test` | Run all tests |
| `task test:quick` | Run tests without link checking |
## Quick Testing
Before committing, run quick tests:
```bash
task test:quick
```
This validates:
- Hugo build succeeds
- Markdown syntax is correct
For comprehensive testing, including link checking:
```bash
task test
```
## Tips for Documentors
1. **Write in present tense** - "The system processes..." not "The system will process..."
2. **Use code blocks** with syntax highlighting
3. **Include diagrams** for complex concepts
4. **Test locally** before pushing
5. **Keep it concise** - readers appreciate brevity
6. **Update regularly** - stale docs are worse than no docs
## Troubleshooting
### Port 1313 already in use
```bash
# Find and kill the process
lsof -ti:1313 | xargs kill -9
```
### Build errors
```bash
# Clean and rebuild
task clean
task build:dev
```
### Missing dependencies
```bash
# Reinstall all dependencies
task deps:install
```
## Next Steps
Now that you can develop locally, learn about:
- [Testing processes](../testing/)
- [CI/CD pipeline](../cicd/)

339
content/en/docs/documentation/publishing.md Normal file
View file

@ -0,0 +1,339 @@
---
title: "Publishing to Edge"
linkTitle: "Publishing"
weight: 50
description: >
How documentation is deployed to the edge environment.
---
## Deployment Overview
After successful CI/CD, the documentation is deployed to an edge computing environment.
{{< likec4-view view="deploymentFlow" project="documentation-platform" >}}
## Deployment Architecture
### Edge Connect Platform
Our documentation is deployed using **Edge Connect**, which orchestrates deployments to edge cloudlets.
Configuration: `edgeconnectdeployment.yaml`
```yaml
kind: edgeconnect-deployment
metadata:
name: "edpdoc"
appVersion: "1.0.0"
organization: "edp2"
spec:
k8sApp:
manifestFile: "./k8s-deployment.yaml"
infraTemplate:
- region: "EU"
cloudletOrg: "TelekomOP"
cloudletName: "Munich"
flavorName: "EU.small"
```
**Key settings:**
- **Deployment name:** `edpdoc`
- **Region:** EU (Munich)
- **Cloudlet:** TelekomOP Munich
- **Flavor:** EU.small (resource allocation)
### Kubernetes Deployment
The application runs on Kubernetes: `k8s-deployment.yaml`
#### Service Definition
```yaml
apiVersion: v1
kind: Service
metadata:
name: edpdoc
labels:
run: edpdoc
spec:
type: LoadBalancer
ports:
- name: tcp80
protocol: TCP
port: 80
targetPort: 80
selector:
run: edpdoc
```
- **Type:** LoadBalancer (external access)
- **Port:** 80 (HTTP)
- **Selector:** Routes traffic to pods with label `run: edpdoc`
#### Deployment Configuration
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: edpdoc
spec:
replicas: 1
selector:
matchLabels:
run: edpdoc
template:
metadata:
labels:
run: edpdoc
mexDeployGen: kubernetes-basic
spec:
containers:
- name: edpdoc
image: ###IMAGETAG###
imagePullPolicy: Always
ports:
- containerPort: 80
protocol: TCP
```
- **Replicas:** 1 (single instance)
- **Image:** Injected by deployment pipeline (`###IMAGETAG###` placeholder)
- **Pull policy:** Always (ensures latest version)
### Network Configuration
Outbound connections are configured in `edgeconnectdeployment.yaml`:
```yaml
network:
outboundConnections:
- protocol: "tcp"
portRangeMin: 80
portRangeMax: 80
remoteCIDR: "0.0.0.0/0"
- protocol: "tcp"
portRangeMin: 443
portRangeMax: 443
remoteCIDR: "0.0.0.0/0"
```
- **Port 80:** HTTP outbound
- **Port 443:** HTTPS outbound
- **CIDR:** `0.0.0.0/0` (all destinations)
## Deployment Process
### 1. Container Image Ready
After CI passes:
- Docker image built with `task build:oci-image`
- Tagged with git commit SHA
- Pushed to container registry
### 2. Edge Connect Orchestration
Edge Connect:
1. Pulls container image
2. Reads `edgeconnectdeployment.yaml`
3. Provisions resources on Munich cloudlet
4. Applies Kubernetes manifests
### 3. Kubernetes Deployment
Kubernetes:
1. Creates deployment with 1 replica
2. Pulls container image (`imagePullPolicy: Always`)
3. Starts pod running Nginx + static Hugo site
4. Creates LoadBalancer service
5. Assigns external IP
### 4. Service Available
Documentation is now accessible:
- **Protocol:** HTTP
- **Port:** 80
- **IP:** Assigned by LoadBalancer
## Complete Workflow
{{< likec4-view view="fullWorkflow" project="documentation-platform" >}}
### End-to-End Process
1. **Documentor writes content** (Markdown, LikeC4 models)
2. **Local testing** with `task serve` and `task test`
3. **Commit and push** to Git repository
4. **GitHub Actions triggered** on push to main
5. **CI tests run** (build, markdown, HTML, links)
6. **Container image built** if tests pass
7. **Image pushed** to registry
8. **Edge deployment triggered**
9. **Kubernetes applies** manifests
10. **Service available** on edge cloudlet
## Monitoring Deployment
### Check Deployment Status
```bash
kubectl get deployments -n <namespace>
kubectl get pods -n <namespace>
kubectl get services -n <namespace>
```
### View Logs
```bash
kubectl logs deployment/edpdoc -n <namespace>
```
### Access Documentation
Find the LoadBalancer external IP:
```bash
kubectl get service edpdoc -n <namespace>
```
Access via: `http://<EXTERNAL-IP>`
## Rollback
If issues occur after deployment:
### Option 1: Revert Commit
```bash
git revert <bad-commit>
git push origin main
```
CI will rebuild and redeploy.
### Option 2: Manual Rollback
```bash
kubectl rollout undo deployment/edpdoc -n <namespace>
```
Returns to previous deployment version.
### Option 3: Deploy Specific Version
Update image tag in deployment:
```bash
kubectl set image deployment/edpdoc edpdoc=<registry>/<image>:<tag> -n <namespace>
```
## Scaling
Currently: **1 replica**
To scale for higher traffic:
```yaml
spec:
replicas: 3
```
Then apply:
```bash
kubectl apply -f k8s-deployment.yaml
```
Or scale dynamically:
```bash
kubectl scale deployment/edpdoc --replicas=3 -n <namespace>
```
## Security Considerations
1. **Image scanning** - Scan container images for vulnerabilities
2. **Resource limits** - Set CPU/memory limits in deployment
3. **Network policies** - Restrict pod-to-pod communication
4. **HTTPS** - Consider adding TLS termination (Ingress)
## Performance Optimization
1. **CDN** - Add CDN in front of LoadBalancer
2. **Caching** - Configure Nginx caching headers
3. **Compression** - Enable gzip in Nginx
4. **Image optimization** - Compress images in documentation
## Troubleshooting
### Pod not starting
```bash
kubectl describe pod <pod-name> -n <namespace>
```
Check:
- Image pull errors
- Resource constraints
- Configuration errors
### Service unreachable
```bash
kubectl describe service edpdoc -n <namespace>
```
Check:
- LoadBalancer IP assigned
- Port configuration
- Network policies
### Old content served
Check:
- `imagePullPolicy: Always` in deployment
- Image tag is updated
- Pod has restarted
Force pod restart:
```bash
kubectl rollout restart deployment/edpdoc -n <namespace>
```
## Best Practices
1. **Test before deploying** - Always run `task test` locally
2. **Use feature branches** - Don't deploy directly from local
3. **Monitor after deployment** - Check logs and access
4. **Document changes** - Update RELEASE.md
5. **Version control** - Tag releases in Git
## Future Enhancements
Potential improvements:
- **Blue-green deployment** - Zero-downtime updates
- **Canary releases** - Gradual rollout to subset of users
- **Auto-scaling** - HorizontalPodAutoscaler based on traffic
- **Multi-region** - Deploy to multiple cloudlets
- **HTTPS** - TLS certificates and Ingress controller
## Summary
The deployment process is automated and reliable:
✅ **CI ensures quality** - Tests prevent broken deployments
✅ **Edge infrastructure** - Low-latency access from EU
✅ **Kubernetes orchestration** - Reliable, scalable platform
✅ **Simple rollback** - Easy to recover from issues
As a documentor, focus on content quality. The platform handles deployment automatically! 🚀

275
content/en/docs/documentation/quick-reference.md Normal file
View file

@ -0,0 +1,275 @@
---
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](../)

229
content/en/docs/documentation/testing.md Normal file
View file

@ -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/).