GitHub and MkDocs

This HTML documentation was built using GitHub and its Pages feature in addition to Python enriched with mkdocs and mkdocs-material modules.

Create and publish your web site using MkDocs and MkDocs material

Notes

• for MkDocs documentation visit mkdocs.org.

• for MkDocs Material documentation visit squidfunk.github.io/mkdocs-material

• you will need two GitHub repositories

  • one private to create and build
  • one public to publish in HTML with GitHub Pages feature

1. Install GitHub Desktop client

2. Install Python 3.12+

3. Ensure Python version is 3.12+ and pip version is 20+

   C:\Users\janaf\GitHub\career>python --version
   Python 3.12.4
   
   C:\Users\janaf\GitHub\career>pip --version
   pip 24.0 from C:\Users\janaf\Python312\Lib\site-packages\pip (python 3.12)
   

4. Install mkdocs Python's module

   pip install mkdocs
   

5. Install mkdocs-material Python's module

   pip install mkdocs-material
   

   1. setup your GitHub private repository

6. Setup your GitHub public repository using GitHub Pages web site

7. Create your web site using MkDocs and MkDocs Material on your private repository

8. Test your web site on your private repository

   cd [path to private github repository on local laptop]
   mkdocs serve
   

9. Build it

   cd [path to private github repository on local laptop]
   mkdocs build
   

10. Copy your generated public web site (on your local laptop) from your private repository 'site' folder under your public GitHub repository (on your local laptop)

11. Publish your public web site using GitHub Desktop