name: Deploy Documentation to GitHub Pages
on:
workflow_run:
workflows: ["Docker Build, Publish & Test"]
types: [completed]
workflow_dispatch: # Allow manual trigger
# Sets permissions to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment
concurrency:
group: "pages-${{ github.event_name }}-${{ github.event.workflow_run.head_branch || github.ref }}"
cancel-in-progress: false
env:
NODE_VERSION: '24.12.0'
jobs:
build:
name: Build Documentation
runs-on: ubuntu-latest
timeout-minutes: 10
if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
env:
REPO_NAME: ${{ github.event.repository.name }}
steps:
# Step 1: Get the code
- name: 📥 Checkout code
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
with:
ref: ${{ github.event.workflow_run.head_sha || github.sha }}
# Step 2: Set up Node.js (for building any JS-based doc tools)
- name: 🔧 Set up Node.js
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
with:
node-version: ${{ env.NODE_VERSION }}
# Step 3: Create a beautiful docs site structure
- name: 📝 Build documentation site
run: |
# Create output directory
mkdir -p _site
# Copy all markdown files
cp README.md _site/
cp -r docs _site/
# Create a simple HTML index that looks nice
cat > _site/index.html << 'EOF'
Charon - Documentation
👋 Welcome!
This documentation will help you get started with Charon.
Whether you're a complete beginner or an experienced developer, we've got you covered!
📚 Getting Started
🏠 Getting Started Guide Start Here
Your first setup in just 5 minutes! We'll walk you through everything step by step.
Read the Guide →
📖 README Essential
Learn what the app does, how to install it, and see examples of what you can build.
Read More →
📥 Import Guide
Already using Caddy? Learn how to bring your existing configuration into the app.
Import Your Configs →
🔧 Developer Documentation
🔌 API Reference Advanced
Complete REST API documentation with examples in JavaScript and Python.
View API Docs →
💾 Database Schema Advanced
Understand how data is stored, relationships, and backup strategies.
View Schema →
✨ Contributing Guide
Want to help make this better? Learn how to contribute code, docs, or ideas.
Start Contributing →
📋 All Documentation
📚 Documentation Index
Browse all available documentation organized by topic and skill level.
View Full Index →
🆘 Need Help?
Get Support
Stuck? Have questions? We're here to help!
EOF
# Convert markdown files to HTML using a simple converter
npm install -g marked
# Convert each markdown file
for file in _site/docs/*.md; do
if [ -f "$file" ]; then
filename=$(basename "$file" .md)
marked "$file" -o "_site/docs/${filename}.html" --gfm
fi
done
# Convert README and CONTRIBUTING
marked _site/README.md -o _site/README.html --gfm
if [ -f "CONTRIBUTING.md" ]; then
cp CONTRIBUTING.md _site/
marked _site/CONTRIBUTING.md -o _site/CONTRIBUTING.html --gfm
fi
# Add simple styling to all HTML files
for html_file in _site/*.html _site/docs/*.html; do
if [ -f "$html_file" ] && [ "$html_file" != "_site/index.html" ]; then
# Add a header with navigation to each page
temp_file="${html_file}.tmp"
cat > "$temp_file" << 'HEADER'
Charon - Documentation
HEADER
# Append original content
cat "$html_file" >> "$temp_file"
# Add footer
cat >> "$temp_file" << 'FOOTER'
FOOTER
mv "$temp_file" "$html_file"
fi
done
# --- 🚀 ROBUST DYNAMIC PATH FIX ---
echo "🔧 Calculating paths..."
# 1. Determine BASE_PATH
if [[ "${REPO_NAME}" == *".github.io" ]]; then
echo " - Mode: Root domain (e.g. user.github.io)"
BASE_PATH="/"
else
echo " - Mode: Sub-path (e.g. user.github.io/repo)"
BASE_PATH="/${REPO_NAME}/"
fi
# 2. Define standard repo variables
FULL_REPO="${{ github.repository }}"
REPO_URL="https://github.com/${FULL_REPO}"
echo " - Repo: ${FULL_REPO}"
echo " - URL: ${REPO_URL}"
echo " - Base: ${BASE_PATH}"
# 3. Fix paths in all HTML files
find _site -name "*.html" -exec sed -i \
-e "s|/charon/|${BASE_PATH}|g" \
-e "s|https://github.com/Wikid82/charon|${REPO_URL}|g" \
-e "s|Wikid82/charon|${FULL_REPO}|g" \
{} +
echo "✅ Paths fixed successfully!"
echo "✅ Documentation site built successfully!"
# Step 4: Upload the built site
- name: 📤 Upload artifact
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
with:
path: '_site'
deploy:
name: Deploy to GitHub Pages
if: >-
(github.event_name == 'workflow_run' && github.event.workflow_run.head_branch == 'main') ||
(github.event_name != 'workflow_run' && github.ref == 'refs/heads/main')
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
timeout-minutes: 5
needs: build
steps:
# Deploy to GitHub Pages
- name: 🚀 Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5
# Create a summary
- name: 📋 Create deployment summary
run: |
{
echo "## 🎉 Documentation Deployed!"
echo ""
echo "Your documentation is now live at:"
echo "🔗 ${{ steps.deployment.outputs.page_url }}"
echo ""
echo "### 📚 What's Included"
echo "- Getting Started Guide"
echo "- Complete README"
echo "- API Documentation"
echo "- Database Schema"
echo "- Import Guide"
echo "- Contributing Guidelines"
} >> "$GITHUB_STEP_SUMMARY"