Skip to content

Static Pages using MKDOCS and Github (Github Pages)

Prerequisite

  • Programming Language - Python
  • Python Libraries - mkdocs and its dependencies

MKDOCS Library

Make sure to install the following using pip:

- mkdocs                     1.5.3
- mkdocs-autorefs            1.0.1
- mkdocs-material            9.5.14
- mkdocs-material-extensions 1.3.1
- mkdocstrings               0.24.1
- mkdocstrings-python        1.9.0

Steps

  • Navigate to your desired location and run the following command in powershell/commandline:

    mkdocs new <project name>
    
    This will create a new folder at your desired location with the provided project name. This folder will contain following content:
    - <Project Name>
        - mkdocs.yml
        - docs
            - index.md
    

  • Modify mkdocs.yml file by adding the following contents:

    site_name: <site name>
    theme:
      name: material
      features:
        - navigation.tabs
        - navigation.sections
        - toc.integrate
        - navigation.top
        - search.suggest
        - search.highlight
        - content.tabs.link
        - content.code.annotation
        - content.code.copy
      language: en
      palette:
        - scheme: default
          toggle:
            icon: material/toggle-switch-off-outline 
            name: Switch to dark mode
          primary: black
          accent: white 
        - scheme: slate 
          toggle:
            icon: material/toggle-switch
            name: Switch to light mode    
          primary: black
          accent: white
    
    plugins:
      - mkdocstrings
    
    nav:
      - Home: index.md 
    
    extra:
      social:
        - icon: fontawesome/brands/github-alt
          link: <github userid link>
    
    markdown_extensions:
      - pymdownx.highlight:
          anchor_linenums: true
      - pymdownx.inlinehilite
      - pymdownx.snippets
      - admonition
      - pymdownx.arithmatex:
          generic: true
      - footnotes
      - pymdownx.details
      - pymdownx.superfences
      - pymdownx.mark
      - attr_list
      - pymdownx.emoji:
          emoji_index: !!python/name:material.extensions.emoji.twemoji
          emoji_generator: !!python/name:materialx.emoji.to_svg
    
    copyright: |
      &copy; 2024 <a href="<github userid link>"  target="_blank" rel="noopener"><Name></a>
    

  • Create New Page:

    All pages should be in markdown language and formatting.
    For Markdown guidelines, visit: Markdown Guide
    Create a new file under docs folder with a 'md' extension.
    These files can be nested and grouped under folders.
    Once file is created, you can add the link of this file in docs/index.md using [Name](new_page.md)
    This file can be added in mkdocs.yml under nav to display in navigation bar in website with following structure:

    Name: new_page.md
    

  • View Draft:

    To check how your website looks, run:

    mkdocs serve
    
    This will render your website in runtime, so any changes you do in your pages will get reflect here.
    This will help in modify/add contents to your website.

  • Build your website:

    Once you are satisfied on how your website looks, its time to build the website.
    Run the following command to build:

    mkdocs build
    
    This will create a new folder named as 'Site' which will contain details and contents to build a static pages.
    These content can be used anywhere to build your website.

  • Deployment

    Once mkdocs build command gets complete, add your contents to github repository.
    Initialize a git repository within the project folder.
    Create a gitignore file and add site folder in it. This will avoid having duplicate content in github repository.
    Now, add all the contents in git and commit it.
    Create a github repository with the same project name and push your folder contents to it.
    Now its time to deploy your website using github pages.
    Run the following command:

    mkdocs gh-deploy
    
    This will create a gh_pages branch and push the content of site to it and run the github workflow for deployment.
    After some time, your website will be deployed at the website link which will be provided when you run the mkdocs deploy command.