mdbook Documentation Setup

This guide describes how to set up, build, and deploy the mdbook documentation for gist-cache-rs.

Local Development

Prerequisites

Install mdbook:

cargo install mdbook

Build and Serve Locally

# Build the documentation
mdbook build

# Serve with live reload (recommended for development)
mdbook serve

# The documentation will be available at http://localhost:3000

Directory Structure

gist-cache-rs/
├── book.toml                     # mdbook configuration
├── book/
│   ├── src/                      # Source markdown files
│   │   ├── README.md
│   │   ├── SUMMARY.md            # Table of contents
│   │   ├── user-guide/
│   │   ├── developer-guide/
│   │   └── test-specs/
│   └── book/                     # Generated HTML (gitignored)
└── .github/workflows/
    └── deploy-mdbook.yml         # GitHub Pages deployment

GitHub Pages Deployment

Initial Setup

1. Enable GitHub Pages in Repository Settings

   • Go to your repository on GitHub
   • Navigate to Settings → Pages
   • Under “Source”, select GitHub Actions

2. Push Changes to Main Branch

   • The workflow automatically triggers when changes to documentation files are pushed
   • Monitored paths:
     • book/**
     • book.toml
     • README.md
     • .github/workflows/deploy-mdbook.yml

3. Manual Deployment (Optional)

   • Go to Actions tab in your repository
   • Select Deploy mdbook to GitHub Pages workflow
   • Click Run workflow → Run workflow

Deployment Workflow

The deployment workflow (.github/workflows/deploy-mdbook.yml) performs the following:

1. Build

   • Checks out the repository
   • Sets up mdbook (latest version)
   • Builds the documentation with mdbook build
   • Uploads the generated HTML as a Pages artifact

2. Deploy

   • Deploys the artifact to GitHub Pages
   • The documentation will be available at: https://<username>.github.io/<repository-name>/

Verification

After deployment:

1. Check the Actions tab for workflow status
2. Once completed, visit your GitHub Pages URL:
   • For this repository: https://7rikazhexde.github.io/gist-cache-rs/

Troubleshooting

Workflow fails with “Pages deployment is not enabled”

Solution: Ensure GitHub Pages is enabled in repository settings with source set to “GitHub Actions”

Changes not reflected after deployment

Solution:

• Check that your changes were committed to the main branch
• Wait a few minutes for GitHub Pages cache to update
• Try a hard refresh in your browser (Ctrl+Shift+R)

Build fails with “mdbook not found”

Solution: This should not happen in CI as the workflow installs mdbook automatically. For local development, run cargo install mdbook

Updating Documentation

Editing Content

1. Edit markdown files in book/src/
2. Test locally with mdbook serve
3. Commit and push changes
4. The workflow will automatically rebuild and deploy

Adding New Pages

1. Create a new markdown file in the appropriate directory:

   • User documentation: book/src/user-guide/
   • Developer documentation: book/src/developer-guide/
   • Test specifications: book/src/test-specs/

2. Add the new page to book/src/SUMMARY.md:

   - [New Page Title](path/to/new-page.md)
   

3. Test locally and push changes

Modifying Structure

Edit book/src/SUMMARY.md to reorganize the table of contents. The structure in SUMMARY.md determines the navigation menu.

Configuration

book.toml

Key configurations:

• title: Documentation title
• src: Source directory (book/src)
• build-dir: Output directory (book/book)
• Theme: Rust theme with Navy dark theme
• Features: Search, code folding, edit links

Customization

To customize the appearance:

1. Add custom CSS in book/theme/custom.css
2. Modify book.toml settings
3. See mdbook documentation for all options

CI/CD Integration

The deployment workflow integrates with:

• Trigger: Push to main branch or manual workflow dispatch
• Permissions: Read contents, write to Pages, id-token for deployment
• Concurrency: Only one deployment runs at a time

Additional Resources

• mdbook User Guide
• GitHub Pages Documentation
• GitHub Actions for Pages