2016-02-09 23:59:37 +03:00
|
|
|
|
# Customization
|
|
|
|
|
|
2017-01-03 01:11:32 +03:00
|
|
|
|
## A great starting point
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
Project documentation is as diverse as the projects themselves and the Material
|
2017-01-03 01:11:32 +03:00
|
|
|
|
theme is a good starting point for making it look great. However, as you write
|
2017-03-11 20:36:34 +03:00
|
|
|
|
your documentation, you may reach a point where some small adjustments are
|
|
|
|
|
necessary to preserve the desired style.
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2017-01-03 01:11:32 +03:00
|
|
|
|
## Adding assets
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2017-01-03 01:11:32 +03:00
|
|
|
|
[MkDocs][1] provides several ways to interfere with themes. In order to make a
|
|
|
|
|
few tweaks to an existing theme, you can just add your stylesheets and
|
|
|
|
|
JavaScript files to the `docs` directory.
|
|
|
|
|
|
|
|
|
|
[1]: http://www.mkdocs.org
|
|
|
|
|
|
|
|
|
|
### Additional stylesheets
|
|
|
|
|
|
|
|
|
|
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
|
2017-01-07 22:07:41 +03:00
|
|
|
|
new stylesheet file in your `docs` directory:
|
2017-01-03 01:11:32 +03:00
|
|
|
|
|
|
|
|
|
``` sh
|
|
|
|
|
mkdir docs/stylesheets
|
|
|
|
|
touch docs/stylesheets/extra.css
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Then, add the following line to your `mkdocs.yml`:
|
|
|
|
|
|
|
|
|
|
``` yaml
|
2017-01-09 23:41:30 +03:00
|
|
|
|
extra_css:
|
|
|
|
|
- 'stylesheets/extra.css'
|
2017-01-03 01:11:32 +03:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Spin up the development server with `mkdocs serve` and start typing your
|
|
|
|
|
changes in your additional stylesheet file – you can see them instantly after
|
2017-01-12 22:15:30 +03:00
|
|
|
|
saving, as the MkDocs development server implements live reloading.
|
2017-01-03 01:11:32 +03:00
|
|
|
|
|
|
|
|
|
### Additional JavaScript
|
|
|
|
|
|
|
|
|
|
The same is true for additional JavaScript. If you want to integrate another
|
|
|
|
|
syntax highlighter or add some custom logic to your theme, create a new
|
2017-01-07 22:07:41 +03:00
|
|
|
|
JavaScript file in your `docs` directory:
|
2017-01-03 01:11:32 +03:00
|
|
|
|
|
|
|
|
|
``` sh
|
|
|
|
|
mkdir docs/javascripts
|
|
|
|
|
touch docs/javascripts/extra.js
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Then, add the following line to your `mkdocs.yml`:
|
|
|
|
|
|
|
|
|
|
``` yaml
|
2017-01-09 23:41:30 +03:00
|
|
|
|
extra_javascript:
|
|
|
|
|
- 'javascripts/extra.js'
|
2017-01-03 01:11:32 +03:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Further assistance can be found in the [MkDocs documentation][2].
|
|
|
|
|
|
|
|
|
|
[2]: http://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme
|
|
|
|
|
|
|
|
|
|
## Extending the theme
|
|
|
|
|
|
|
|
|
|
If you want to alter the HTML source (e.g. add or remove some part), you can
|
|
|
|
|
extend the theme. From version 0.16 on MkDocs implements [theme extension][3],
|
|
|
|
|
an easy way to override parts of a theme without forking and changing the
|
|
|
|
|
main theme.
|
|
|
|
|
|
|
|
|
|
[3]: http://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme_dir
|
|
|
|
|
|
|
|
|
|
### Setup and theme structure
|
|
|
|
|
|
|
|
|
|
Reference the Material theme as usual in your `mkdocs.yml`, and create a
|
2017-10-31 21:48:20 +03:00
|
|
|
|
new folder for overrides, e.g. `theme`, which you reference using `custom_dir`:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
2017-10-31 21:48:20 +03:00
|
|
|
|
theme:
|
|
|
|
|
name: 'material'
|
|
|
|
|
custom_dir: 'theme'
|
2017-01-03 01:11:32 +03:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
!!! warning "Theme extension prerequisites"
|
|
|
|
|
|
2017-10-31 21:48:20 +03:00
|
|
|
|
As the `custom_dir` variable is used for the theme extension process, the
|
2017-01-03 01:11:32 +03:00
|
|
|
|
Material theme needs to be installed via `pip` and referenced with the
|
2017-10-31 21:48:20 +03:00
|
|
|
|
`name` parameter in your `mkdocs.yml`.
|
2017-01-03 01:11:32 +03:00
|
|
|
|
|
|
|
|
|
The structure in the theme directory must mirror the directory structure of the
|
|
|
|
|
original theme, as any file in the theme 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 theme directory.
|
|
|
|
|
|
|
|
|
|
The directory layout of the Material theme is as follows:
|
|
|
|
|
|
|
|
|
|
``` sh
|
|
|
|
|
.
|
|
|
|
|
├─ assets/
|
|
|
|
|
│ ├─ images/ # Images and icons
|
|
|
|
|
│ ├─ javascripts/ # JavaScript
|
|
|
|
|
│ └─ stylesheets/ # Stylesheets
|
|
|
|
|
├─ partials/
|
2018-01-22 00:56:54 +03:00
|
|
|
|
│ ├─ integrations/ # 3rd-party integrations
|
2017-10-31 21:48:20 +03:00
|
|
|
|
│ ├─ language/ # Localized languages
|
2017-01-03 01:11:32 +03:00
|
|
|
|
│ ├─ footer.html # Footer bar
|
|
|
|
|
│ ├─ header.html # Header bar
|
2018-01-22 00:56:54 +03:00
|
|
|
|
│ ├─ hero.html # Hero teaser
|
2017-01-13 02:31:37 +03:00
|
|
|
|
│ ├─ language.html # Localized labels
|
2017-01-03 01:11:32 +03:00
|
|
|
|
│ ├─ nav-item.html # Main navigation item
|
|
|
|
|
│ ├─ nav.html # Main navigation
|
|
|
|
|
│ ├─ search.html # Search box
|
2017-01-04 22:16:12 +03:00
|
|
|
|
│ ├─ social.html # Social links
|
2017-01-03 01:11:32 +03:00
|
|
|
|
│ ├─ source.html # Repository information
|
2017-03-11 18:15:23 +03:00
|
|
|
|
│ ├─ tabs-item.html # Tabs navigation item
|
|
|
|
|
│ ├─ tabs.html # Tabs navigation
|
2017-01-03 01:11:32 +03:00
|
|
|
|
│ ├─ toc-item.html # Table of contents item
|
|
|
|
|
│ └─ toc.html # Table of contents
|
|
|
|
|
├─ 404.html # 404 error page
|
|
|
|
|
├─ base.html # Base template
|
|
|
|
|
└─ main.html # Default page
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Overriding partials
|
|
|
|
|
|
|
|
|
|
In order to override the footer, we can replace the `footer.html` partial with
|
|
|
|
|
our own partial. To do this, create the file `partials/footer.html` in the
|
|
|
|
|
theme directory. MkDocs will now use the new partial when rendering the theme.
|
|
|
|
|
This can be done with any file.
|
|
|
|
|
|
|
|
|
|
### Overriding template blocks
|
|
|
|
|
|
|
|
|
|
Besides overriding partials, one can also override so called template blocks,
|
|
|
|
|
which are defined inside the Material theme and wrap specific features. To
|
|
|
|
|
override a template block, create a `main.html` inside the theme directory and
|
|
|
|
|
define the block, e.g.:
|
|
|
|
|
|
|
|
|
|
``` jinja
|
|
|
|
|
{% extends "base.html" %}
|
|
|
|
|
|
|
|
|
|
{% block htmltitle %}
|
|
|
|
|
<title>Lorem ipsum dolor sit amet</title>
|
|
|
|
|
{% endblock %}
|
2016-02-09 23:59:37 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-01-03 01:11:32 +03:00
|
|
|
|
The Material theme provides the following template blocks:
|
|
|
|
|
|
|
|
|
|
| Block name | Wrapped contents |
|
|
|
|
|
| ------------ | ----------------------------------------------- |
|
|
|
|
|
| `analytics` | Wraps the Google Analytics integration |
|
|
|
|
|
| `content` | Wraps the main content |
|
2017-03-11 18:15:23 +03:00
|
|
|
|
| `disqus` | Wraps the disqus integration |
|
2017-01-03 01:11:32 +03:00
|
|
|
|
| `extrahead` | Empty block to define additional meta tags |
|
|
|
|
|
| `fonts` | Wraps the webfont definitions |
|
|
|
|
|
| `footer` | Wraps the footer with navigation and copyright |
|
|
|
|
|
| `header` | Wraps the fixed header bar |
|
2017-11-22 02:13:56 +03:00
|
|
|
|
| `hero` | Wraps the hero teaser |
|
2017-01-03 01:11:32 +03:00
|
|
|
|
| `htmltitle` | Wraps the `<title>` tag |
|
|
|
|
|
| `libs` | Wraps the JavaScript libraries, e.g. Modernizr |
|
|
|
|
|
| `repo` | Wraps the repository link in the header bar |
|
|
|
|
|
| `scripts` | Wraps the JavaScript application logic |
|
2017-03-11 18:15:23 +03:00
|
|
|
|
| `source` | Wraps the linked source files |
|
2017-01-03 01:11:32 +03:00
|
|
|
|
| `search_box` | Wraps the search form in the header bar |
|
|
|
|
|
| `site_meta` | Wraps the meta tags in the document head |
|
|
|
|
|
| `site_name` | Wraps the site name in the header bar |
|
|
|
|
|
| `site_nav` | Wraps the site navigation and table of contents |
|
2017-01-04 22:16:12 +03:00
|
|
|
|
| `social` | Wraps the social links in the footer |
|
2017-01-03 01:11:32 +03:00
|
|
|
|
| `styles` | Wraps the stylesheets (also extra sources) |
|
|
|
|
|
|
|
|
|
|
For more on this topic refer to the [MkDocs documentation][4]
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2017-01-03 01:11:32 +03:00
|
|
|
|
[4]: http://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2017-01-03 01:11:32 +03:00
|
|
|
|
## Theme development
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2017-11-21 23:32:25 +03:00
|
|
|
|
The Material theme uses [Webpack][5] as a build tool to leverage modern web
|
|
|
|
|
technologies like [Babel][6] and [SASS][7]. If you want to make more fundamental
|
|
|
|
|
changes, it may be necessary to make the adjustments directly in the source of
|
|
|
|
|
the Material theme and recompile it. This is fairly easy.
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2017-11-21 23:32:25 +03:00
|
|
|
|
[5]: https://webpack.js.org/
|
2017-01-03 01:11:32 +03:00
|
|
|
|
[6]: https://babeljs.io
|
|
|
|
|
[7]: http://sass-lang.com
|
2016-02-17 20:08:11 +03:00
|
|
|
|
|
2017-01-03 01:11:32 +03:00
|
|
|
|
### Environment setup
|
|
|
|
|
|
|
|
|
|
In order to start development on the Material theme, a [Node.js][8] version of
|
2018-02-21 23:06:11 +03:00
|
|
|
|
at least 8 is required. First, clone the repository:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` sh
|
|
|
|
|
git clone https://github.com/squidfunk/mkdocs-material
|
|
|
|
|
```
|
|
|
|
|
|
2017-01-03 01:11:32 +03:00
|
|
|
|
Next, all dependencies need to be installed, which is done with:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` sh
|
|
|
|
|
cd mkdocs-material
|
2017-01-07 22:07:41 +03:00
|
|
|
|
pip install -r requirements.txt
|
2018-02-21 23:06:11 +03:00
|
|
|
|
npm install
|
2016-02-09 23:59:37 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-01-03 01:11:32 +03:00
|
|
|
|
[8]: https://nodejs.org
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2017-01-03 01:11:32 +03:00
|
|
|
|
### Development mode
|
|
|
|
|
|
2017-11-21 23:32:25 +03:00
|
|
|
|
The development server can be started with:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` sh
|
2018-02-21 23:06:11 +03:00
|
|
|
|
npm run watch
|
2016-02-09 23:59:37 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-01-03 01:11:32 +03:00
|
|
|
|
This will also start the MkDocs development server which will monitor changes
|
|
|
|
|
on assets, templates and documentation. Point your browser to
|
2018-02-21 23:06:11 +03:00
|
|
|
|
[localhost:8000][9] and you should see this documentation in front of you.
|
2017-01-03 01:11:32 +03:00
|
|
|
|
|
|
|
|
|
For example, changing the color palette is as simple as changing the
|
|
|
|
|
`$md-color-primary` and `$md-color-accent` variables in
|
|
|
|
|
`src/assets/stylesheets/_config.scss`:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` css
|
2017-01-03 01:11:32 +03:00
|
|
|
|
$md-color-primary: $clr-red-400;
|
|
|
|
|
$md-color-accent: $clr-teal-a700;
|
2016-02-09 23:59:37 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-01-07 22:07:41 +03:00
|
|
|
|
!!! 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
|
|
|
|
|
overriden when the theme is built.
|
|
|
|
|
|
2018-02-21 23:06:11 +03:00
|
|
|
|
[9]: http://localhost:8000
|
2016-02-10 02:01:17 +03:00
|
|
|
|
|
2017-01-03 01:11:32 +03:00
|
|
|
|
### Build process
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2017-03-11 20:36:34 +03:00
|
|
|
|
When you've finished making your changes, you can build the theme by invoking:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` sh
|
2018-02-21 23:06:11 +03:00
|
|
|
|
npm run build
|
2016-02-09 23:59:37 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-01-03 01:11:32 +03:00
|
|
|
|
This triggers the production-level compilation and minification of all
|
2017-03-11 20:36:34 +03:00
|
|
|
|
stylesheets and JavaScript sources. When the command exits, the final theme is
|
|
|
|
|
located in the `material` directory. Add the `theme_dir` variable pointing to
|
|
|
|
|
the aforementioned directory in your original `mkdocs.yml`.
|
2016-02-17 20:08:11 +03:00
|
|
|
|
|
|
|
|
|
Now you can run `mkdocs build` and you should see your documentation with your
|
|
|
|
|
changes to the original Material theme.
|