mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
86 lines
2.8 KiB
Markdown
86 lines
2.8 KiB
Markdown
|
# 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;
|
||
|
|
```
|
||
|
|
|
||
|
|
### 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
|