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:
This will create a new folder at your desired location with the provided project name. This folder will contain following content: -
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: | © 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: -
View Draft:
To check how your website looks, run:
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.
This will create a new folder named as 'Site' which will contain details and contents to build a static pages.
Run the following command to build:
These content can be used anywhere to build your website. -
Deployment
Once mkdocs build command gets complete, add your contents to github repository.
This will create a gh_pages branch and push the content of site to it and run the github workflow for deployment.
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:
After some time, your website will be deployed at the website link which will be provided when you run the mkdocs deploy command.