Documentation Maintenance Scripts
Shell scripts for validating and maintaining the documentation structure. For the full content authoring guide, see CONTENT-GUIDE.md.
These scripts run in Git Bash on Windows or any bash-compatible shell on Linux/Mac.
Quick Start
cd App/Static/Documentation/scripts
# Run all validations
./validate-docs.sh # Check structure and YAML
./check-broken-images.sh # Verify all images exist (runs in CI)
./check-local-image-paths.sh # Verify local preview paths work
./find-orphaned-images.sh # Find unused images
# Fix image paths for local preview (VS Code/Typora)
./fix-image-paths-local.sh --dry-run # Preview changes
./fix-image-paths-local.sh # Apply changes
# Clean up GitBook YAML (if needed)
./clean-gitbook-yaml.sh --dry-run # Preview GitBook cleanup
Common options:
| Option | Effect |
|---|---|
--dry-run |
Preview changes without modifying files |
--quiet |
Show only errors and summary (skip OK items) |
Troubleshooting on Windows:
chmod +x *.sh # Fix "Permission denied" (one-time)
# Make sure you're using Git Bash, not CMD or PowerShell
Scripts
validate-docs.sh
Validates documentation structure: checks every subfolder has an index.md and validates YAML front matter (title, order required).
./validate-docs.sh
Exit codes: 0 = passed, 1 = errors found.
check-broken-images.sh
Verifies all image references in markdown point to existing files in App/wwwroot/images/documentation/. Runs in GitHub Actions CI.
./check-broken-images.sh
Reports missing images with suggestions for similar filenames.
check-local-image-paths.sh
Verifies relative image paths resolve correctly for local preview in VS Code or Typora.
./check-local-image-paths.sh # Full output
./check-local-image-paths.sh --quiet # Summary only
fix-image-paths-local.sh
Auto-fixes image paths to correct relative paths for local markdown preview. Calculates the path based on each file's depth:
| File depth | Relative path prefix |
|---|---|
1 (e.g., reliasim-overview/index.md) |
../../../wwwroot/images/documentation/ |
2 (e.g., reliasim-overview/structure/index.md) |
../../../../wwwroot/images/documentation/ |
3 (e.g., reliasim-overview/structure/node-types/buffers.md) |
../../../../../wwwroot/images/documentation/ |
./fix-image-paths-local.sh --dry-run # Preview first
./fix-image-paths-local.sh # Apply changes
clean-gitbook-yaml.sh
Removes unused GitBook-specific YAML fields (e.g., layout: and its nested properties). Keeps title, order, and description.
./clean-gitbook-yaml.sh --dry-run # Preview
./clean-gitbook-yaml.sh # Apply
find-orphaned-images.sh
Lists images in App/wwwroot/images/documentation/ that aren't referenced in any markdown file.
./find-orphaned-images.sh