mkdocs-material/docs/customization.md

# Customization

## A good starting point

Project documentation is as diverse as the projects themselves and the Material
theme is a good starting point for making it look good. However, as you write
your documentation, you may reach some point where some small adjustments are
necessary to preserve the style.

## Small tweaks

[MkDocs][] provides a simple way for making small adjustments, that is changing
some margins, centering text, etc. Simply put the CSS and Javascript files that
contain your adjustments in the `docs` directory (ideally in subdirectories of
their own) and include them via the `extra_css` and `extra_javascript`
variables in your `mkdocs.yml`:

``` yaml
extra_css: ['/stylesheets/extra.css']
extra_javascript: ['/javascripts/extra.js']
```

Further assistance on including extra CSS and Javascript can be found in the
[MkDocs documentation][].

## Fundamental changes

If you want to make larger adjustments like changing the color palette or
typography, you should check out the repository of the project and compile
the SASS sources with your changes. The project design is very modular, so
most things can be changed by tweaking a few variables.

### Setup

In order to compile the project, you need `node`, `bower` and `gulp` up and
running. It's best to use the most recent versions, but it should also work if
your installations are not too dated. The project itself is hosted on GitHub,
so the next thing you should do is clone the project from GitHub:

``` sh
git clone https://github.com/squidfunk/mkdocs-material
```

Then you change the directory and install all dependencies specified in the
`package.json` and `bower.json`:

``` sh
cd mkdocs-material
npm install && bower install
```

### Development

The asset pipeline is contained in `Gulpfile.js`, which you can start with
`gulp watch`. This will also run `mkdocs serve`, to monitor changes to the
documentation. Point your browser to [localhost:8000](http://localhost:8000)
and you should see this very documentation in front of your eyes.

``` sh
gulp watch
```

For example, changing the color palette is as simple as changing the `$primary`
and `$accent` variables in `src/assets/stylesheets/_palette.scss`:

``` css
$primary: $red-400;
$accent:  $teal-a700;
```

The color variables are defined by the SASS library [quantum-colors][] and
resemble all the colors contained in the material design palette.
[This page][material-colors] offers a really good overview of the palette.

### Building

When you finished making your changes, you can build the theme by invoking:

``` sh
gulp build --production
```

The `production` flag triggers the production-level compilation and
minification of all CSS and Javascript sources. When the command is ready,
the final theme is located in the `material` directory. Add the `theme_dir`
variable pointing to the aforementioned directory in your original
`mkdocs.yml` and you should see your documentation with your changes!

[MkDocs]: http://www.mkdocs.org
[MkDocs documentation]: http://www.mkdocs.org/user-guide/styling-your-docs/#customising-a-theme
[quantum-colors]: https://github.com/nkpfstr/quantum-colors
[material-colors]: http://www.materialui.co/colors