Skip to content

MkDocs

This is a template to deploy a basic MkDocs documentation site on GitHub Pages.

Deployment

GitHub Pages

To get started, open the repository and follow the steps below:

  1. Click the Use this template button (top-right).

  2. Choose Create a new repository.

  3. Enable GitHub Pages:

    Settings > Pages > Deploy from Branch > gh-pages.

  4. Grant read and write permission:

    Settings > Actions > General > Workflow permission > Read and write permissions.

  5. Commit any file changes to publish the updates.

  6. Visit your published site e.g. https://therepos.github.io/mkdocs

Local Deployment

1.   To deploy it locally: 

git clone https://github.com/therepos/mkdocs.git

2.   Install dependencies:

cd mkdocs  
pip install -r requirements.txt

3.   Preview site locally:

mkdocs serve

4.   Deploy locally:

mkdocs build

5.   Push to gh-pages:

mkdocs gh-deploy

6.   Push to GitHub repo:

git add . 
git commit -m "Updates"
git push

Guides

To understand more about how to use or customise the site, please refer to the official MkDocs Guides.

Structure

mkdocs
├── .github/
├── docs/
│   ├── about/                  # your section
│   │   ├── .pages              # set section title here
│   │   └── index.md            # your document
│   └── blog/posts/
│       └── post.md             # your blog post 
│   ├── css/
│   └── fonts/
├── .gitignore
├── build.py
├── LICENSE
├── mkdocs.yml
├── readme.md
└── requirements.txt

License

This work is licensed under Creative Commons Attribution 4.0 International.
If you find this template useful, please attribute a link to this repository.

Resources