Skip to content

Deploying a Static Site with MkDocs and GitHub Pages

Prerequisites

  • Python installed on your machine.
  • A GitHub account with a repository for your project.

Steps

  1. Install MkDocs:
pip install mkdocs
pip install mkdocs-material
pip install pymdown-extensions
pip install mkdocs mkdocs-gitbook
pip install mkdocs-minify-plugin
pip install mkdocs-git-revision-date-localized-plugin
  1. Initialize MkDocs Project:
mkdocs new my-project
cd my-project
  1. Organize Markdown Files:

  2. Place all markdown files in the docs directory.

  3. Configure Navigation:

  4. Edit mkdocs.yml to define the site's navigation.

  5. Build and Serve Locally:

mkdocs build
mkdocs serve
  1. Deploy to GitHub Pages:

mkdocs gh-deploy
7. github settup alt text In the setting of the project, click page section, you will see visit pages

Additional Tips

  • Ensure your GitHub repository is set up to use GitHub Pages.
  • Check the gh-pages branch for the deployed site content.