2.8 KiB
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:
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:
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:
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
and you should see this very documentation in front of your eyes.
gulp watch
For example, changing the color palette is as simple as changing the $primary
and $accent variables in src/assets/stylesheets/_palette.scss:
$primary: $red-400;
$accent: $teal-a700;
Building
When you finished making your changes, you can build the theme by invoking:
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!