---
template: overrides/main.html
---
# 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.
[MkDocs]: https://www.mkdocs.org
### Additional CSS
If you want to tweak some colors or change the spacing of certain elements,
you can do this in a separate stylesheet. The easiest way is by creating a
new stylesheet file in the `docs` directory:
``` sh
.
├─ docs/
│ └─ stylesheets/
│ └─ extra.css
└─ mkdocs.yml
```
Then, add the following lines to `mkdocs.yml`:
``` yaml
extra_css:
- stylesheets/extra.css
```
### Additional JavaScript
If you want to integrate another syntax highlighter or add some custom logic to
your theme, create a new JavaScript file in the `docs` directory:
``` sh
.
├─ docs/
│ └─ javascripts/
│ └─ extra.js
└─ mkdocs.yml
```
Then, add the following lines to `mkdocs.yml`:
``` yaml
extra_javascript:
- javascripts/extra.js
```
## Extending the theme
If you want to alter the HTML source (e.g. add or remove some parts), you can
extend the theme. MkDocs supports [theme extension], an easy way to override
parts of Material for MkDocs without forking from git. This ensures that you
can update to the latest version more easily.
[theme extension]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir
### 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`][custom_dir]
setting:
``` yaml
theme:
name: material
custom_dir: overrides
```
!!! warning "Theme extension prerequisites"
As the [`custom_dir`][custom_dir] setting is used for the theme extension
process, Material for MkDocs needs to be installed via `pip` and referenced
with the [`name`][name] setting in `mkdocs.yml`. It will not work when
cloning from `git`.
The structure in the `overrides` directory must mirror the directory structure
of the original theme, as any file in the `overrides` directory will replace the
file with the same name which is part of the original theme. Besides, further
assets may also be put in the `overrides` directory:
``` sh
.
├─ .icons/ # Bundled icon sets
├─ assets/
│ ├─ images/ # Images and icons
│ ├─ javascripts/ # JavaScript files
│ └─ stylesheets/ # Style sheets
├─ partials/
│ ├─ integrations/ # Third-party integrations
│ │ ├─ analytics/ # Analytics integrations
│ │ └─ analytics.html # Analytics setup
│ ├─ languages/ # Translation languages
│ ├─ content.html # Page content
│ ├─ copyright.html # Copyright and theme information
│ ├─ footer.html # Footer bar
│ ├─ header.html # Header bar
│ ├─ language.html # Translation setup
│ ├─ logo.html # Logo in header and sidebar
│ ├─ nav.html # Main navigation
│ ├─ nav-item.html # Main navigation item
│ ├─ palette.html # Color palette
│ ├─ search.html # Search interface
│ ├─ social.html # Social links
│ ├─ source.html # Repository information
│ ├─ source-file.html # Source file information
│ ├─ tabs.html # Tabs navigation
│ ├─ tabs-item.html # Tabs navigation item
│ ├─ toc.html # Table of contents
│ └─ toc-item.html # Table of contents item
├─ 404.html # 404 error page
├─ base.html # Base template
└─ main.html # Default page
```
[custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
[name]: https://www.mkdocs.org/user-guide/configuration/#name
### Overriding partials
In order to override a partial, we can replace it with a file of the same name
and location in the `overrides` directory. For example, to replace the original
`footer.html` partial, create a new `footer.html` partial in the `overrides`
directory:
``` sh
.
├─ overrides/
│ └─ partials/
│ └─ footer.html
└─ mkdocs.yml
```
MkDocs will now use the new partial when rendering the theme. This can be done
with any file.
### Overriding blocks recommended { #overriding-blocks data-toc-label="Overriding blocks" }
Besides overriding partials, it's also possible to override (and extend)
template blocks, which are defined inside the templates and wrap specific
features. In order to set up block overrides, create a `main.html` file inside
the `overrides` directory:
``` sh
.
├─ overrides/
│ └─ main.html
└─ mkdocs.yml
```
Then, e.g. to override the site title, add the following lines to `main.html`:
``` html
{% extends "base.html" %}
{% block htmltitle %}
Lorem ipsum dolor sit amet
{% endblock %}
```
The following template blocks are provided by the theme:
| Block name | Purpose |
| :---------------- | :---------------------------------------------- |
| `analytics` | Wraps the Google Analytics integration |
| `announce` | Wraps the announcement bar |
| `config` | Wraps the JavaScript application config |
| `content` | Wraps the main content |
| `disqus` | Wraps the Disqus integration |
| `extrahead` | Empty block to add custom meta tags |
| `fonts` | Wraps the font definitions |
| `footer` | Wraps the footer with navigation and copyright |
| `header` | Wraps the fixed header bar |
| `hero` | Wraps the hero teaser (if available) |
| `htmltitle` | Wraps the `` tag |
| `libs` | Wraps the JavaScript libraries (header) |
| `outdated` | Wraps the version warning |
| `scripts` | Wraps the JavaScript application (footer) |
| `site_meta` | Wraps the meta tags in the document head |
| `site_nav` | Wraps the site navigation and table of contents |
| `styles` | Wraps the style sheets (also extra sources) |
| `tabs` | Wraps the tabs navigation (if available) |
## Theme development
Material for MkDocs is built on top of [TypeScript], [RxJS] and [SASS], and
uses a lean, custom build process to put everything together.[^1] If you want
to make more fundamental changes, it may be necessary to make the adjustments
directly in the source of the theme and recompile it.
[^1]:
Prior to :octicons-tag-24: 7.0.0 the build was based on Webpack, resulting
in occasional broken builds due to incompatibilities with loaders and
plugins. Therefore, we decided to swap Webpack for a leaner solution which
is now based on [RxJS] as the application itself. This allowed for the
pruning of more than 500 dependencies (~30% less).
[TypeScript]: https://www.typescriptlang.org/
[RxJS]: https://github.com/ReactiveX/rxjs
[SASS]: https://sass-lang.com
### Environment setup
In order to start development on Material for MkDocs, a [Node.js] version of
at least 14 is required. First, clone the repository:
```
git clone https://github.com/squidfunk/mkdocs-material
```
Next, all dependencies need to be installed, which is done with:
```
cd mkdocs-material
pip install -r requirements.txt
pip install mkdocs-minify-plugin
pip install mkdocs-redirects
npm install
```
[Node.js]: https://nodejs.org
### Development mode
Start the watcher with:
```
npm start
```
Then, in a second terminal window, start the MkDocs live preview server with:
```
mkdocs serve --watch-theme
```
Point your browser to [localhost:8000][live preview] and you should see this
very documentation in front of you.
!!! warning "Automatically generated files"
Never make any changes in the `material` directory, as the contents of this
directory are automatically generated from the `src` directory and will be
overwritten when the theme is built.
[live preview]: http://localhost:8000
### Building the theme
When you're finished making your changes, you can build the theme by invoking:
```
npm run build
```
This triggers the production-level compilation and minification of all style
sheets and JavaScript files. After the command exits, the compiled files are
located in the `material` directory. When running `mkdocs build`, you should
now see your changes to the original theme.