A sample for publishing documentation sites using the mkdocs
tool. The source of documentation is Markdown.
- Python 3
- pipenv
After cloning this repository, start a new Python environemnt for this project and install its dependencies:
# Spawn a shell in a virtual environment to isolate the development
$ pipenv shell
# Install project dependencies
# This will install dependencies from `Pipfile.lock`
$ pipenv install
- Edit or add any new Markdown files to the
docs
folder. - To make changes to the navigation, edit the
nav
section inmkdocs.yml
.
After Markdown file edits (*.md
files) or changes to the project settings in mkdocs.yml
, run the build command to generate updated documentation:
$ cd docs
$ mkdocs build
Run this command to generate and run a local server with publish HTML documentation:
$ mkdocs serve
Go to http://127.0.0.1:8000 to see the published HTML on your browser.
Use--dev
argument to install dependencies used for development only: pipenv install pytest --dev
. If you need to install just the dev packages, run pipenv install --dev
.
This test using the following mkdocs-material theme.