mkdocs-material/docs/customization.md

246 lines
8.5 KiB
Markdown
Raw Normal View History

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
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
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
│ ├─ social.html # Social links
2017-01-03 01:11:32 +03:00
│ ├─ source.html # Repository information
│ ├─ 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 |
| `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 |
| `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 |
| `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
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
[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
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
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
```
!!! 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.