feat: add mermaid diagram rendering with interactive zoom overlay to mdbook docs #66

Workflow file for this run

	name: Documentation

	on:
	push:
	branches: [ main ]
	paths:
	- 'docs/**'
	- '.github/workflows/docs.yml'
	pull_request:
	branches: [ main ]
	paths:
	- 'docs/**'
	- '.github/workflows/docs.yml'
	workflow_dispatch:

	# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
	permissions:
	contents: read
	pages: write
	id-token: write
	pull-requests: write

	# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
	# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
	concurrency:
	group: "pages"
	cancel-in-progress: false

	jobs:
	build-docs:
	name: Build Documentation
	runs-on: ubuntu-latest

	steps:
	- name: Checkout code
	uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1

	- name: Setup Rust for mdBook
	uses: dtolnay/rust-toolchain@stable

	- name: Cache mdBook installation
	uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
	with:
	path: ~/.cargo/bin/mdbook
	key: ${{ runner.os }}-mdbook
	restore-keys: \|
	${{ runner.os }}-mdbook

	- name: Install mdBook
	run: \|
	if ! command -v mdbook &> /dev/null; then
	cargo install mdbook --version ^0.4
	fi
	mdbook --version

	- name: Install mdBook plugins
	run: \|
	# Install useful mdBook plugins
	if ! command -v mdbook-linkcheck &> /dev/null; then
	cargo install mdbook-linkcheck --version ^0.7
	fi
	if ! command -v mdbook-mermaid &> /dev/null; then
	cargo install mdbook-mermaid --version ^0.12
	fi

	- name: Check documentation links
	run: \|
	cd docs
	# Check if linkcheck is configured in book.toml, if not skip
	if grep -q "\[output.linkcheck\]" book.toml; then
	mdbook build
	else
	echo "Linkcheck not configured in book.toml, skipping link validation"
	fi

	- name: Build documentation
	run: \|
	cd docs
	echo "Building documentation with mdBook..."
	mdbook build
	echo "Documentation built successfully"

	# Check that key files were generated
	if [ ! -f book/index.html ]; then
	echo "ERROR: index.html not found in build output"
	exit 1
	fi

	echo "Build statistics:"
	echo "Total HTML files: $(find book -name "*.html" \| wc -l)"
	echo "Total size: $(du -sh book \| cut -f1)"

	- name: Validate HTML
	run: \|
	echo "Validating generated HTML..."
	cd docs

	# Basic HTML validation - check for key files and basic structure
	VALIDATE_FILES="book/index.html book/introduction.html book/installation.html book/quick-start.html"

	for file in $VALIDATE_FILES; do
	if [ -f "$file" ]; then
	echo "Checking $file..."
	# Basic checks: ensure file has proper HTML structure
	if grep -q "<html" "$file" && grep -q "</html>" "$file"; then
	echo "✓ $file has valid HTML structure"
	else
	echo "⚠ $file may have HTML structure issues"
	fi
	else
	echo "⚠ $file not found"
	fi
	done

	echo "HTML validation completed"

	- name: Setup Pages
	if: github.event_name == 'push' && github.ref == 'refs/heads/main'
	uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
	with:
	enablement: true
	continue-on-error: true

	- name: Upload Pages artifact
	if: github.event_name == 'push' && github.ref == 'refs/heads/main'
	uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
	with:
	path: docs/book
	continue-on-error: true

	- name: Upload build artifacts (for PRs)
	if: github.event_name == 'pull_request'
	uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
	with:
	name: documentation-preview
	path: docs/book
	retention-days: 7

	deploy-docs:
	name: Deploy Documentation to GitHub Pages
	if: github.event_name == 'push' && github.ref == 'refs/heads/main'
	environment:
	name: github-pages
	url: ${{ steps.deployment.outputs.page_url }}
	runs-on: ubuntu-latest
	needs: build-docs

	steps:
	- name: Deploy to GitHub Pages
	id: deployment
	uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
	continue-on-error: true

	- name: Pages deployment info
	if: failure()
	run: \|
	echo "GitHub Pages deployment failed. This is expected if Pages isn't enabled yet."
	echo ""
	echo "To enable GitHub Pages:"
	echo "1. Go to repository Settings → Pages"
	echo "2. Set Source to 'GitHub Actions'"
	echo "3. Save the settings"
	echo ""
	echo "After enabling Pages, the next push to main will deploy documentation automatically."

	check-docs-health:
	name: Documentation Health Check
	runs-on: ubuntu-latest
	if: github.event_name == 'push' && github.ref == 'refs/heads/main'
	needs: deploy-docs

	steps:
	- name: Checkout code
	uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1

	- name: Wait for deployment
	run: sleep 30

	- name: Check deployed documentation
	run: \|
	echo "Checking deployed documentation health..."

	# Get the repository name for GitHub Pages URL
	REPO_NAME=$(echo ${{ github.repository }} \| cut -d'/' -f2)
	DOCS_URL="https://${{ github.repository_owner }}.github.io/$REPO_NAME"

	echo "Testing documentation at: $DOCS_URL"

	# Check main page loads
	if curl -f -s "$DOCS_URL" > /dev/null; then
	echo "Main documentation page loads successfully"
	else
	echo "ERROR: Main documentation page failed to load"
	exit 1
	fi

	# Check a few key pages
	KEY_PAGES=("introduction.html" "installation.html" "quick-start.html" "api-reference.html")

	for page in "${KEY_PAGES[@]}"; do
	if curl -f -s "$DOCS_URL/$page" > /dev/null; then
	echo "$page loads successfully"
	else
	echo "WARNING: $page failed to load (might not exist)"
	fi
	done

	echo "Documentation deployment health check completed"

	docs-metrics:
	name: Documentation Metrics
	runs-on: ubuntu-latest
	needs: build-docs

	steps:
	- name: Checkout code
	uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1

	- name: Download documentation artifact
	uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
	with:
	name: documentation-preview
	path: docs-built
	if: github.event_name == 'pull_request'

	- name: Calculate documentation metrics
	run: \|
	if [ "${{ github.event_name }}" == "pull_request" ]; then
	DOCS_DIR="docs-built"
	else
	# For push events, build docs again for metrics
	sudo apt-get update
	sudo apt-get install -y cargo
	cargo install mdbook
	cd docs && mdbook build
	cd ..
	DOCS_DIR="docs/book"
	fi

	echo "Documentation Metrics"
	echo "====================="

	if [ -d "$DOCS_DIR" ]; then
	echo "Total HTML files: $(find $DOCS_DIR -name "*.html" \| wc -l)"
	echo "Total files: $(find $DOCS_DIR -type f \| wc -l)"
	echo "Total size: $(du -sh $DOCS_DIR \| cut -f1)"
	echo "Internal links: $(grep -r "href=\"\." $DOCS_DIR --include="*.html" \| wc -l)"
	echo "External links: $(grep -r "href=\"http" $DOCS_DIR --include="*.html" \| wc -l)"

	# Count documentation sections
	echo ""
	echo "Documentation Structure:"
	find docs/src -name "*.md" \| while read file; do
	lines=$(wc -l < "$file")
	echo " - $(basename "$file" .md): $lines lines"
	done

	else
	echo "WARNING: Documentation build directory not found"
	fi

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add mermaid diagram rendering with interactive zoom overlay to mdbook docs #66

Workflow file

feat: add mermaid diagram rendering with interactive zoom overlay to mdbook docs #66

Uh oh!

Workflow file for this run