Skip to content

Custom Styling

Theme Customization

A lot can be found on the main website
itself.

The color table to choose the main and accent colors can be found on the Getting Started page.

Themes

Custom Theme

Note

If you are looking for third party themes, they are listed in the MkDocs
community wiki.

It is possible to add extra customization via a Custom Theme option.

  • create custom_theme and custom_theme/css directories parallel to the docs directory
  • inside the custom_theme/css directory create extra.less file with your styles
  • use any LESS compiler to compile the extra.less file to the minified extra.min.css and its map extra.min.css.map
  • add the following lines to mkdoc.yml under the theme variable:
1
2
3
4
theme
  theme_dir: custom_theme
  extra_css:
  - css/extra.min.css
  • now when you build and serve the website, you should see the custom styling in action

Similarly, it is possible to add extra JavaScript inside the custom_theme/js directory. You add the corresponding setting to the mkdocs.yml file:

1
2
3
4
theme
  theme_dir: custom_theme
  extra_javascript:
  - js/your-js-file.min.js

The 10 Tips for Writing JavaScript without jQuery article is a good read to write custom JavaScript without using jQuery.

Extensions

Admonition

Admonition extension for the MkDocs Markdown provides for a way to draw attention of the reader. In order to use this extension

Syntax

1
2
!!! special_word "some text within double quotes"
    Any number of lines aligned with the special_word
  1. 3 exclamation marks ( !!! ) at the beginning of the line
  2. 1 space
  3. 1 special word (see below)
  4. 1 space
  5. (optional) some text within double quotes
  6. (optional) 1 empty line
  7. (optional) any number of lines beginning at pos. 4 (aligned with the special word after the exclamation marks)

Special words

These special words result in a colored adminition blocks. It is nice to experiment with them.

  • note, seealso - light blue
  • important, hint, tip - green
  • warning, caution, attention - beige/brown
  • danger, error - pink/red

Note

The special word can be also any other word. In that case, the color will always be light blue.

Examples

A custom text message on the first line…
1
2
3
4
!!! note "Explicit title within double quotes"

    Any number of other indented markdown elements.
    And this is the second paragraph.

…replaces the 1st word:

Explicit title within double quotes

Any number of other indented markdown elements.
And this is the second paragraph.

Any single word on the first line…
1
2
3
!!! hint

    You should note that the title will be automatically capitalized.

…will be capitalized:

Hint

You should note that the title will be automatically capitalized.

The empty custom title…
1
2
3
!!! warning ""

    This is an admonition box without a title.

…results in no title:

This is an admonition box without a title.

The word “danger” plus custom title…
1
2
3
!!! danger "Don't try this at home"

    Or you will regret it for the rest of your life!

…results in the red background:

Don’t try this at home

Or you will regret it for the rest of your life!

SmartyPants

Adding

1
2
- smarty:
    smart_angled_quotes: true

to markdown_extentions gives you the possibility to print out nicely looking ASCII dashes, quotes and ellipes:

you write you get
'single quotes' ‘single quotes’
"double qoutes" “double qoutes”
<<angled quotes>> «angled quotes»
... ellipsis … ellipsis
-- ndash – ndash
--- mdash — mdash

nl2br extension

Adding

1
- nl2br

to markdown_extentions creates a newline within fences when you make a newline in Markdown. You type:

1
2
line 1
line 2

Without nl2br you see this:

1
line 1 line 2

With nl2br you see this:

1
2
line 1
line 2

Lato Font

This font is one of the free Google fonts: Lato Google Font. In order to use it, the following line should be added to the /spreadsheets/extra.css file:

1
@import url('https://fonts.googleapis.com/css?family=Lato');