Getting Started

This guide will help you set up and customize this documentation template for your project.

1. Prerequisites

Ensure you have the following installed before proceeding:

Python 3.9 or later → Download from python.org
Git → Install from git-scm.com
MkDocs Material → Installed via pip (explained below)

To check your Python version, run:

python --version

If your Python version is below 3.9, update it before proceeding.

2. Clone or Fork the Template

You can either clone this repository for a standalone copy or fork it to keep it synced with the original.

To Clone:

git clone https://github.com/your-org/template-repo.git
cd template-repo

To Fork:
Navigate to the repository on GitHub.
Click the Fork button.

Clone your fork:

git clone https://github.com/your-username/template-repo.git

3. Set Up a Local Python Environment

To develop and preview the documentation locally, create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

4. Using MkDocs Commands

After setting up the environment, use the following commands:

mkdocs serve  # Run a local development server (http://127.0.0.1:8000/)
mkdocs build  # Generate the static site
mkdocs gh-deploy  # Deploy to GitHub Pages

5. Changing the Git Remote Origin

If you're using this template for a new project, update the remote repository:

git remote remove origin
git remote add origin https://github.com/your-org/new-repo.git
git push -u origin main

6. Setting Up GitHub Actions for Automatic Deployment

This template includes a GitHub Actions workflow to automatically build and deploy your documentation whenever you push changes to the repository.

Steps to Enable GitHub Actions for Deployment

Enable GitHub Pages:
Go to your repository on GitHub.
Navigate to Settings → Pages.
Under "Build and Deployment," select GitHub Actions as the deployment source.
Set Up a Personal Access Token (if needed):
In GitHub, go to Settings → Developer Settings → Personal Access Tokens.
Generate a new token with repo and workflow permissions.
Add the token as a GitHub secret in your repository under Settings → Secrets → Actions as GH_TOKEN.
GitHub Actions Workflow File (.github/workflows/deploy.yml)

Ensure your repository has the following workflow file:

name: Deploy MkDocs

on:
  push:
    branches:
      - main  # Change if using a different branch

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

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.9"

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install mkdocs mkdocs-material

      - name: Deploy to GitHub Pages
        run: mkdocs gh-deploy --force

Commit and Push Changes
Make sure .github/workflows/deploy.yml is committed to your repository.

Push your changes:

git add .
git commit -m "Added GitHub Actions deployment workflow"
git push origin main

Verify Deployment
After pushing changes, navigate to the Actions tab on GitHub to check the deployment workflow.

Your documentation should be live at:

https://your-username.github.io/your-repository/

Once this setup is complete, any change to your documentation (.md files) will automatically trigger a rebuild and deploy to GitHub Pages! 🚀