Skip to main content

Local Documentation Testing

This guide shows how to test your documentation locally before deploying to GitHub Pages using containerized environments that don't affect your system.

Quick Start - Containerized Testing​

DocuMCP automatically generates a containerized testing environment that requires only Docker or Podman:

# Run the containerized testing script
./test-docs-local.sh

This script will:

  1. Detect your container runtime (Podman or Docker)
  2. Build a documentation container
  3. Check for broken links in your documentation
  4. Serve the documentation at http://localhost:3001

Prerequisites​

You need either Docker or Podman installed:

Option 1: Podman (rootless, more secure)

# macOS
brew install podman

# Ubuntu/Debian
sudo apt-get install podman

# RHEL/CentOS/Fedora
sudo dnf install podman

Option 2: Docker

# macOS
brew install docker

# Or download from: https://docs.docker.com/get-docker/

Container-Based Testing Methods​

# Simple one-command testing
./test-docs-local.sh

Method 2: Using Docker Compose​

# Build and run with Docker Compose
docker-compose -f docker-compose.docs.yml up --build

# Or with Podman Compose
podman-compose -f docker-compose.docs.yml up --build

Method 3: Manual Container Commands​

# Build the container
docker build -f Dockerfile.docs -t documcp-docs .
# or: podman build -f Dockerfile.docs -t documcp-docs .

# Run the container
docker run --rm -p 3001:3001 documcp-docs
# or: podman run --rm -p 3001:3001 documcp-docs

If you prefer to install dependencies locally (affects your system):

cd docs-site
npm install
npm run build
npm run serve

Verification Checklist​

✅ Content Verification​

  • All pages load without errors
  • Navigation works correctly
  • Links between pages function properly
  • Search functionality works (if enabled)
  • Code blocks render correctly with syntax highlighting
  • Images and assets load properly

✅ Structure Verification​

  • Sidebar navigation reflects your documentation structure
  • Categories and sections are properly organized
  • Page titles and descriptions are accurate
  • Breadcrumb navigation works
  • Footer links are functional

✅ Content Quality​

  • No broken internal links
  • No broken external links
  • Code examples are up-to-date
  • Screenshots are current and clear
  • All content follows Diataxis framework principles

✅ Performance Testing​

  • Pages load quickly (< 3 seconds)
  • Search is responsive
  • No console errors in browser developer tools
  • Mobile responsiveness works correctly

Troubleshooting Common Issues​

Container Build Failures​

Problem: Container build fails

Solutions:

# Clean up any existing containers and images
docker system prune -f
# or: podman system prune -f

# Rebuild from scratch
docker build --no-cache -f Dockerfile.docs -t documcp-docs .
# or: podman build --no-cache -f Dockerfile.docs -t documcp-docs .

# Check for syntax errors in markdown files
find docs -name "*.md" -exec npx markdownlint {} \;

Container Runtime Issues​

Problem: "Neither Podman nor Docker found"

Solutions:

# Check if Docker/Podman is installed and running
docker --version
podman --version

# On macOS, ensure Docker Desktop is running
# On Linux, ensure Docker daemon is started:
sudo systemctl start docker

# For Podman on macOS, start the machine:
podman machine start

Problem: Links between documentation pages don't work

Solutions:

  • Check that file paths in your markdown match actual file locations
  • Ensure relative links use correct syntax: [text](../other-page.md)
  • Verify that sidebars.js references match actual file names

Missing Pages​

Problem: Some documentation pages don't appear in navigation

Solutions:

  • Update docs-site/sidebars.js to include new pages
  • Ensure files are in the correct directory structure
  • Check that frontmatter is properly formatted

Styling Issues​

Problem: Documentation doesn't look right

Solutions:

  • Check docs-site/src/css/custom.css for custom styles
  • Verify Docusaurus theme configuration
  • Clear browser cache and reload

DocuMCP provides built-in link checking:

# Check all links
npm run docs:check-links

# Check only external links
npm run docs:check-links:external

# Check only internal links
npm run docs:check-links:internal

Use markdown-link-check for comprehensive link validation:

# Install globally
npm install -g markdown-link-check

# Check specific file
markdown-link-check docs/index.md

# Check all markdown files
find docs -name "*.md" -exec markdown-link-check {} \;

Container Configuration Testing​

Verify Container Configuration​

# Test container health
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
# or: podman ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Check container logs
docker logs documcp-docs-test
# or: podman logs documcp-docs-test

# Execute commands inside running container
docker exec -it documcp-docs-test sh
# or: podman exec -it documcp-docs-test sh

Test Different Container Environments​

# Test production build in container
docker run --rm -e NODE_ENV=production -p 3001:3001 documcp-docs

# Interactive debugging mode
docker run --rm -it --entrypoint sh documcp-docs
# Inside container: cd docs-site && npm run build --verbose

Deployment Preview​

Before deploying to GitHub Pages, test with production settings:

# Build with production configuration
npm run build

# Serve the production build locally
npm run serve

This simulates exactly what GitHub Pages will serve.

Integration with Development Workflow​

Pre-commit Testing​

Add documentation testing to your git hooks:

# .husky/pre-commit
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# Run documentation tests
./test-docs-local.sh --build-only

# Run your regular tests
npm test

CI/CD Integration​

Add documentation testing to your GitHub Actions:

# .github/workflows/docs-test.yml
name: Documentation Tests

on:
  pull_request:
    paths:
      - "docs/**"
      - "docs-site/**"

jobs:
  test-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
          cache-dependency-path: "docs-site/package-lock.json"

      - name: Test documentation build
        run: ./test-docs-local.sh --build-only

Advanced Testing​

Performance Testing​

# Install lighthouse CLI
npm install -g lighthouse

# Test performance of local documentation
lighthouse http://localhost:3001 --output=json --output-path=./lighthouse-report.json

# Check specific performance metrics
lighthouse http://localhost:3001 --only-categories=performance

Accessibility Testing​

# Test accessibility
lighthouse http://localhost:3001 --only-categories=accessibility

# Use axe for detailed accessibility testing
npm install -g axe-cli
axe http://localhost:3001

SEO Testing​

# Test SEO optimization
lighthouse http://localhost:3001 --only-categories=seo

# Check meta tags and structure
curl -s http://localhost:3001 | grep -E "<title>|<meta"

Automated Testing Script​

Create a comprehensive test script:

#!/bin/bash
# comprehensive-docs-test.sh

echo "🧪 Running comprehensive documentation tests..."

# Build test
echo "📦 Testing build..."
cd docs-site && npm run build

# Link checking
echo "🔗 Checking links..."
cd .. && npm run docs:check-links:all

# Performance test (if lighthouse is available)
if command -v lighthouse &> /dev/null; then
    echo "⚡ Testing performance..."
    cd docs-site && npm run serve &
    SERVER_PID=$!
    sleep 5
    lighthouse http://localhost:3001 --quiet --only-categories=performance
    kill $SERVER_PID
fi

echo "✅ All tests completed!"

Best Practices​

1. Test Early and Often​

  • Test after every significant documentation change
  • Include documentation testing in your regular development workflow
  • Set up automated testing in CI/CD pipelines

2. Test Different Scenarios​

  • Test with different screen sizes and devices
  • Test with JavaScript disabled
  • Test with slow internet connections

3. Monitor Performance​

  • Keep an eye on build times
  • Monitor page load speeds
  • Check for large images or files that slow down the site

4. Validate Content Quality​

  • Use spell checkers and grammar tools
  • Ensure code examples work and are current
  • Verify that external links are still valid

By following this guide, you can ensure your documentation works perfectly before deploying to GitHub Pages, providing a better experience for your users and avoiding broken deployments.