oauth_test.go
Getting started
Installation
Installing MkDocs
Before installing MkDocs, you need to make sure you have Python and pip
– the Python package manager – up and running. You can verify if you're already
good to go with the following commands:
python --version
# Python 2.7.13
pip --version
# pip 9.0.1
Installing and verifying MkDocs is as simple as:
pip install mkdocs && mkdocs --version
# mkdocs, version 0.17.1
Material requires MkDocs >= 0.17.1.
Installing Material
using pip
Material can be installed with pip
:
pip install mkdocs-material
using choco
If you're on Windows you can use Chocolatey to install Material:
choco install mkdocs-material
This will install all required dependencies like Python and MkDocs.
cloning from GitHub
Material can also be used without a system-wide installation by cloning the repository into a subfolder of your project's root directory:
git clone https://github.com/squidfunk/mkdocs-material.git
This is especially useful if you want to extend the theme and
override some parts of the theme. The theme will reside in the folder
mkdocs-material/material
.
Troubleshooting
!!! warning "Installation on macOS"
When you're running the pre-installed version of Python on macOS, `pip`
tries to install packages in a folder for which your user might not have
the adequate permissions. There are two possible solutions for this:
1. **Installing in user space** (recommended): Provide the `--user` flag
to the install command and `pip` will install the package in a user-site
location. This is the recommended way.
2. **Switching to a homebrewed Python**: Upgrade your Python installation
to a self-contained solution by installing Python with Homebrew. This
should eliminate a lot of problems you may be having with `pip`.
!!! failure "Error: unrecognized theme 'material'"
If you run into this error, the most common reason is that you installed
MkDocs through some package manager (e.g. Homebrew or `apt-get`) and the
Material theme through `pip`, so both packages end up in different
locations. MkDocs only checks its install location for themes.
Alternative: Using Docker
If you're familiar with Docker, the official Docker image for Material comes with all dependencies pre-installed and ready-to-use with the latest version published on PyPI, packaged in a very small image. Pull it with:
docker pull squidfunk/mkdocs-material
The mkdocs
executable is provided as an entrypoint, serve
is the default
command. Start the development server in your project root with:
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material