{tocify} $title={Table of Contents}
Documentation that simply works
Write your documentation in Markdown and create a professional static site in minutes – searchable, customizable, for all devices.
Getting started
Material for MkDocs is a theme for MkDocs, a static site generator geared towards (technical) project documentation. If you're familiar with Python, you can install Material for MkDocs with pip, the Python package manager. If not, we recommend using docker.
Installation
Material for MkDocs is published as a Python package and can be installed with pip, ideally by using a virtual environment. Open up a terminal and install Material for MkDocs with:
pip install mkdocs-material
This will automatically install compatible versions of all dependencies: MkDocs, Markdown, Pygments and Python Markdown Extensions. Material for MkDocs always strives to support the latest versions, so there's no need to install those packages separately.
Creating your site
After you've installed Material for MkDocs, you can bootstrap your project documentation using the mkdocs executable. Go to the directory where you want your project to be located and enter:
mkdocs new .
This will create the following structure:
.
├─ docs/
│ └─ index.md
└─ mkdocs.yml
Configuration
Minimal configuration
Simply add the following lines to mkdocs.yml to enable the theme:
theme:
name: material
Advanced configuration
Material for MkDocs comes with many configuration options. The setup section explains in great detail how to configure and customize colors, fonts, icons and much more:
- Changing the colors
- Changing the fonts
- Changing the language
- Changing the logo and icons
- Ensuring data privacy
- Setting up navigation
- Setting up site search
- Setting up site analytics
- Setting up social cards
- Setting up a blog
- Setting up tags
- Setting up versioning
- Setting up the header
- Setting up the footer
- Adding a git repository
- Adding a comment system
- Building for offline usage
Furthermore, see the list of supported Markdown extensions that are natively integrated with Material for MkDocs, delivering an unprecedented low-effort technical writing experience.
Previewing as you write
MkDocs includes a live preview server, so you can preview your changes as you write your documentation. The server will automatically rebuild the site upon saving. Start it with:
mkdocs serve
Point your browser to localhost:8000 and you should see:
Your Site with Material theme will look like below
Building your site
When you're finished editing, you can build a static site from your Markdown files with:
mkdocs build
Publishing your site
The great thing about hosting project documentation in a git repository is the ability to deploy it automatically when new changes are pushed. MkDocs makes this ridiculously simple.
GitHub Pages
If you're already hosting your code on GitHub, GitHub Pages is certainly the most convenient way to publish your project documentation. It's free of charge and pretty easy to set up.
with GitHub Actions
Using GitHub Actions you can automate the deployment of your project documentation. At the root of your repository, create a new GitHub Actions workflow, e.g. .github/workflows/ci.yml, and copy and paste the following contents:
name: cion:push:branches:- master- mainpermissions:contents: writejobs:deploy:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v3- uses: actions/setup-python@v4with:python-version: 3.x- run: pip install mkdocs-material- run: mkdocs gh-deploy --force
Now, when a new commit is pushed to either the master or main branches, the static site is automatically built and deployed. Push your changes to see the workflow in action.
If the GitHub Page doesn't show up after a few minutes, go to the settings of your repository and ensure that the publishing source branch for your GitHub Page is set to gh-pages.
Your documentation should shortly appear at <username>.github.io/<repository>.
with MkDocs
If you prefer to deploy your project documentation manually, you can just invoke the following command from the directory containing the mkdocs.yml file:
mkdocs gh-deploy --force
GitLab Pages
If you're hosting your code on GitLab, deploying to GitLab Pages can be done by using the GitLab CI task runner. At the root of your repository, create a task definition named .gitlab-ci.yml and copy and paste the following contents:
image: python:latest
pages:
stage: deploy
script:
- pip install mkdocs-material
- mkdocs build --site-dir public
artifacts:
paths:
- public
rules:
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
Now, when a new commit is pushed to master, the static site is automatically built and deployed. Commit and push the file to your repository to see the workflow in action.
Your documentation should shortly appear at <username>.gitlab.io/<repository>.
Customization
Project documentation is as diverse as the projects themselves and Material for MkDocs is a great starting point for making it look beautiful. However, as you write your documentation, you may reach a point where small adjustments are necessary to preserve your brand's style.
Adding assets
MkDocs provides several ways to customize a theme. In order to make a few small tweaks to Material for MkDocs, you can just add CSS and JavaScript files to the docs directory.
Additional CSS
If you want to tweak some colors or change the spacing of certain elements, you can do this in a separate style sheet. The easiest way is by creating a new style sheet file in the docs directory:
.├─ docs/│ └─ stylesheets/│ └─ extra.css└─ mkdocs.yml
Then, add the following lines to mkdocs.yml:
extra_css:- stylesheets/extra.css
Setup and theme structure
Enable Material for MkDocs as usual in mkdocs.yml, and create a new folder for overrides which you then reference using the custom_dir setting:
theme:name: materialcustom_dir: overrides
Updated Content:
Add files as Markdown files inside the docs folder like below image:
Reference:
Thanks ✌👌