Home

Building, Maintaining, and Publishing Documentation with MkDocs & GitHub

---

1. Overview

This document provides internal guidance for creating, updating, and publishing documentation using MkDocs and GitHub. It outlines:

• How the site was originally built
• How the repository is structured
• How to update content using our workflow (working branch: JS_Updates)
• How to publish updated documentation using mkdocs gh-deploy
• General MkDocs notes and best practices

---

2. Initial Site Setup (How the site was built)

2.1 Install MkDocs & Theme

1. Create or activate a Python virtual environment.
2. Install MkDocs and Material theme:

   pip install mkdocs-material

2.2 Create the Project Structure

Run:

mkdocs new <project-name>

This creates:

• mkdocs.yml — main configuration file
• docs/ — folder containing markdown pages

2.3 Develop & Preview the Site

To preview live changes:

mkdocs serve

Site runs locally at:

http://127.0.0.1:8000

2.4 Initialize GitHub Repository

1. Create a new GitHub repo (empty except for a README).
2. From local project root:

   git init
   git add .
   git commit -m "Initial MkDocs project"
   git remote add origin <repo-url>
   git push -u origin main

3. Ensure .gitignore excludes:

   site/
   __pycache__/
   *.pyc
   .DS_Store
   

---

3. Repository Workflow

3.1 Branching Strategy

• Main branch: Production-ready documentation
• Working branch: JS_Updates (used for all edits before PR)

3.2 Creating the Working Branch

If it doesn’t exist locally:

git checkout -b JS_Updates

If it already exists:

git checkout JS_Updates

3.3 Pull the Latest Changes Before Editing

git checkout JS_Updates
git pull origin main

3.4 File Structure

• mkdocs.yml — navigation, theme, colors, plugins
• docs/ — all markdown documentation pages
• overrides/ (optional) — templates or custom HTML/CSS overrides
• assets/ (optional) — images, GIFs, videos

Only edit content inside docs/ and the config in mkdocs.yml. Never modify the auto-generated site/ folder.

---

4. Updating Documentation

4.1 Editing Pages

1. Switch to the working branch:

   git checkout JS_Updates

2. Update or create Markdown files inside docs/.
3. Preview changes during editing:

   mkdocs serve

4.2 Staging and Committing Changes

git add .
git commit -m "Describe what was updated"

4.3 Push Changes to GitHub

git push -u origin JS_Updates

4.4 Create a Pull Request

1. Open the GitHub repository.
2. Click Compare & Pull Request.
3. Review changes.
4. Request review if needed.
5. Merge into main once approved.

---

5. Publishing the Site (Manual Deployment)

We use MkDocs’ built-in deployment command instead of automated GitHub Actions.

5.1 Deploy Command

Once changes are merged into main:

mkdocs gh-deploy

MkDocs will:

• Build the site locally
• Push contents to the gh-pages branch
• Update the live site

5.2 GitHub Pages Settings

Only needs to be set once:

• Go to Settings → Pages
• Branch: gh-pages
• Folder: / (root)

Site will be accessible at:

https://themmrf.github.io/docs-vlab/

---

6. General MkDocs Information

6.1 Editing Navigation

Update the nav: section in mkdocs.yml, for example:

nav:
  - Home: index.md
  - Guides:
      - Setup: setup.md
      - Usage: usage.md

6.2 Adding Images

Place images in docs/assets/:

![Alt text](assets/my-image.png)

6.3 Adding GIFs

Same syntax as images:

![Workflow GIF](assets/demo.gif)

6.4 Custom Colors (Material Theme)

In mkdocs.yml:

theme:
  palette:
    primary: deep purple
    accent: indigo

You can also use custom HEX values if needed.

6.5 Troubleshooting

• Port already in use → kill process on port 8000
• Plugin missing → install with pip install <plugin>
• Site folder appears in GitHub → remove with:

  git rm -r --cached site
  git commit -m "Remove site folder"
  git push

• Cannot find module → installing mkdocs via Homebrew results in many dependency errors. Install via pip instead.

---

7. Future Enhancements (Optional)

These can be added later:

• GitHub Actions for automated deployment
• Search enhancements using plugins
• Custom HTML templates via overrides/
• Versioning using mkdocs-material built-in features

---

8. Summary

This SOP outlines the full lifecycle of our MkDocs documentation process:

• Build locally with MkDocs
• Store source in GitHub
• Update via JS_Updates branch → pull request → merge
• Manually publish using mkdocs gh-deploy

This ensures consistency, team collaboration, and easy maintainability.