Skip to content

MkDocs | Material for MkDocs

Installation

There are many possible ways to install the tool and its dependencies, see the getting started guide of material-mkdocs. The description below illustrates the conda environemnt way to go.

# Create conda environment and activate it
conda create --name myenv
conda activate myenv
# Install latest Python 3.9.x
conda install python=3.9
# Install material-mkdocs and its dependencies, see output
pip install mkdocs-material

Info

The above also install MkDocs and the python markdown extension (pymdown-extensions)

Setup a project

Now its time to fire up a new projecct using `mkdocs:

mkdir myproject
cd myproject
# It's probably wise to version it
git init
echo "site/" > .gitignore
# Do more git stuff here or later
#
# Now initialize a mkdocs project
# and add the files to the git index
mkdocs new .
git add .
git ci -m "Initial empty mkdocs project"

The journey just started, best to continue the getting started guide of the material-mkdocs website.

The reference guide of material-mkdocs is a superb place to get an overview of possible style elements like admonitions, lists, formatting etc. and how to achieve them. Also look into the cheatsheet with all stuff in aciton.

To publish the generated static pages, either deploy manually or setup a github action. This is on page Publish your site.

Further Reading


Last update: 2022-09-26