Code Documentation of the Future — MkDocs-Material Tutorial

Tutorial for Mkdocs with material theme and hosting on github pages

Intro

The current documentation

The other choice is ReadTheDocs.

To be honest I don’t know which one is uglier.

Mkdocs — Material Theme

  1. Awesome layout
  2. Mobile friendly
  3. Amazing text search

All of that comes out of the box

Screw it lets do it

you can create this documentation for any project that you have.

Install

pip install mkdocs mkdocs-material

create a file mkdocs.yml and add to file

site_name: name-of-your-site
theme:
name: 'material'

create a directory docs/

create a file index.md in the docs/ and the following to index.md

# Getting Started

Full code on [github](https://github.com/ahmednafies/sanic_camelcase_middleware).

## Install
pip install sanic_camelcase_middelware

## Dependencies
* [pyhumps](https://pypi.org/project/pyhumps/)
* [sanic](https://pypi.org/project/sanic/)

## Example
from sanic import Sanic
from sanic_camelcase_middleware import Camelize

app = Sanic(__name__)
Camelize(app)

You can add any documentation you need

lets serve the docs, go to the terminal and run

mkdocs serve

open your browser and go to http://localhost:8000

lets add more pages

install.md

# Install## pip
pip install sanic_camelcase_middelware
## pipenv
pip install sanic_camelcase_middelware

example.md

# Full example
from sanic import Sanic
from sanic.response import json
from sanic_camelcase_middleware import Camelize

app = Sanic(__name__)

Camelize(app)


@app.route("/post", methods=["POST"])
async def test(request):
return json("is_camelcase": True, "message": request.json})


if __name__ == "__main__":
app.run(host="0.0.0.0", port=8000)

now we need to add the routes to these files to the mkdocs.yml

site_name: name-of-your-sitenav:
- Getting Started: index.md
- Install: install.md
- Full Example: example.md
theme:
name: 'material'

lets serve the docs again, go to the terminal and run

$ mkdocs serve

Looking amazing right,

lets change the color to green

open mkdocs.yml

site_name: name-of-your-sitenav:
- Getting Started: index.md
- Install: install.md
- Full Example: example.md
theme:
name: 'material'
palette:
primary: 'green'

And you can do much more, to know more how you can customize your theme check here

Deploy to github pages

just make sure that your directory is version by git and connected to a remote repo on github.

go the terminal and run

$ mkdocs gh-deploy

your documentation are deployed on https://{your-github-username}.github.io/{repository-name}

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store