Skip to content

GitHub Pages Setup

Setup process

  1. Create MkDocs configuration:
  2. Copy assets/mkdocs-template.yml to mkdocs.yml
  3. Update site_name, site_url, repo_url with your project details

  4. Customize navigation structure for your content

  5. Set up GitHub Actions:

  6. Copy assets/github-actions-template.yml to .github/workflows/pages-build-deployment.yml

  7. Configure GitHub Pages:

  8. Go to repository Settings → Pages
  9. Set Source to "GitHub Actions"
  10. Optionally add custom domain in "Custom domain" field

File structure created

project/
├── mkdocs.yml                                    # MkDocs configuration
├── .github/workflows/
│   └── pages-build-deployment.yml              # GitHub Actions deployment
└── mkdocs_temp/                                 # Custom docs directory (auto-created)

Troubleshooting

Common issues and solutions: - Navigation not appearing: Check file paths in mkdocs.yml nav section - Mermaid not rendering: Ensure mermaid2 plugin is installed and configured - Build failures: Check GitHub Actions logs for missing dependencies - Custom domain issues: Verify CNAME file and DNS configuration

  • semantic-commit: For proper commit messages when setting up
  • python-scaffold: If creating Python documentation projects