MkDocs (GitHub Deploy)

This is a comprehensive guide for setting up an MkDocs project locally, integrating it with GitHub, and automating deployment to GitHub Pages using a GitHub Workflow (GitHub Actions).

1. Local MkDocs Setup and Development

This section guides you through setting up the necessary tools and creating your documentation project.

Prerequisites

Python: MkDocs requires Python to run. Ensure you have Python 3 installed.
pip: Python's package installer, which comes with modern Python installations.
Git: For version control and GitHub integration.

Step 1: Install MkDocs

It's highly recommended to use a virtual environment to keep your project dependencies isolated.

Create and Activate a Virtual Environment (Optional but Recommended):

Linux/macOS:

python3 -m venv venv
source venv/bin/activate

Windows:

python -m venv venv
.\venv\Scripts\activate

Install MkDocs (and the popular Material for MkDocs theme):
```
pip install mkdocs mkdocs-material
```
- Tip: Create a requirements.txt file to list your dependencies:
```
pip freeze > requirements.txt
```

Step 2: Create a New MkDocs Project

Create the project:
```
mkdocs new my-docs-project
cd my-docs-project
```
This creates a basic structure:
- mkdocs.yml: The main configuration file.
- docs/: Directory containing your Markdown files.
  - docs/index.md: The homepage of your documentation.

Configure mkdocs.yml: Open the mkdocs.yml file and customize it. If you installed the Material theme, set it here:

site_name: My Awesome Documentation
site_url: https://<USERNAME>.github.io/<REPOSITORY_NAME>/ # Important for GitHub Pages
repo_url: https://github.com/<USERNAME>/<REPOSITORY_NAME>
repo_name: <REPOSITORY_NAME>
theme:
  name: material
nav:
  - Home: index.md
  # Add more pages here, e.g.,
  # - Guide: guide/guide.md

Step 3: Local Development and Preview

Start the local development server:
```
mkdocs serve
```
This command starts a web server, typically at http://127.0.0.1:8000. Your browser will open the site.
Write Documentation: Edit the Markdown files in the docs/ directory and save them. The server will auto-reload your browser instantly with the changes.

2. GitHub Repository Setup

Next, link your local project to a new GitHub repository.

Step 1: Initialize Git and Commit

Initialize a local Git repository (if not already done):
```
git init
```
Create a .gitignore file: Add the site/ folder (where MkDocs builds the static HTML) to your .gitignore to prevent committing generated files.
```
# .gitignore
venv/
site/
```

Perform the initial commit:

git add .
git commit -m "Initial MkDocs project setup"

Step 2: Create GitHub Repository and Push

Create a new, empty repository on GitHub (do not initialize with a README or license).
Link your local repository to GitHub and push: Follow the instructions provided by GitHub for "pushing an existing repository from the command line." It typically involves:
```
git remote add origin https://github.com/<USERNAME>/<REPOSITORY_NAME>.git
git branch -M main
git push -u origin main
```
Your source files (mkdocs.yml, docs/, etc.) are now on GitHub.

3. Automated Deployment with GitHub Actions

This is the most modern and recommended way to publish MkDocs to GitHub Pages. The workflow will build your site whenever you push changes to your primary branch (e.g., main).

Step 1: Create the GitHub Actions Workflow File

Create the directory structure for workflows:
```
mkdir -p .github/workflows
```

Create a new file named .github/workflows/ci.yml (or similar) and paste the following content. This workflow uses the officially supported GitHub Actions for Pages.

name: Deploy Docs to GitHub Pages

on:
  # Triggers the workflow on push to the 'main' branch
  push:
    branches:
      - main
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets the GITHUB_TOKEN permissions required for Pages deployment
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.x'

      - name: Install dependencies
        # If you used requirements.txt, use 'pip install -r requirements.txt'
        run: pip install mkdocs mkdocs-material

      - name: Build MkDocs site
        run: mkdocs build
        # The built site is in the 'site' directory by default

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Path to the directory containing the static files
          path: './site'

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Step 2: Push the Workflow

Add and commit the new workflow file:

git add .github/workflows/ci.yml
git commit -m "Add GitHub Actions workflow for MkDocs deployment"
git push

This push will trigger the first workflow run.

Step 3: Finalize GitHub Pages Settings

Navigate to your repository on GitHub.
Go to Settings > Pages.
Under the "Build and deployment" section, ensure the Source is set to GitHub Actions.
If the workflow ran successfully, GitHub Pages will automatically set up the deployment and provide the URL.

Your documentation will typically be available at: https://<USERNAME>.github.io/<REPOSITORY_NAME>/

Note: It may take a few minutes for the initial deployment to complete and for the site to become live. You can monitor the progress in the Actions tab of your repository.