Skip to content

Choosing your Theme

Selecting and configuring a theme.

MkDocs includes two built-in themes (mkdocs and readthedocs), as documented below. However, many third party themes are available to choose from as well.

To choose a theme, set the theme configuration option in your mkdocs.yml config file.

theme:
  name: readthedocs

mkdocs

The default theme, which was built as a custom Bootstrap theme, supports almost every feature of MkDocs.

mkdocs

In addition to the default theme configuration options, the mkdocs theme supports the following options:

  • highlightjs: Enables highlighting of source code in code blocks using the highlight.js JavaScript library. Default: True.

  • hljs_style: The highlight.js library provides 79 different styles (color variations) for highlighting source code in code blocks. Set this to the name of the desired style. Default: github.

  • hljs_languages: By default, highlight.js only supports 23 common languages. List additional languages here to include support for them.

    theme:
  name: mkdocs
  highlightjs: true
  hljs_languages:
    - yaml
    - rust

  • analytics: Defines configuration options for an analytics service. Currently, only Google Analytics v4 is supported via the gtag option.

  • shortcuts: Defines keyboard shortcut keys.

    theme:
  name: mkdocs
  shortcuts:
    help: 191    # ?
    next: 78     # n
    previous: 80 # p
    search: 83   # s

    All values must be numeric key codes. It is best to use keys that are available on all keyboards. You may use https://keycode.info/ to determine the key code for a given key.

    • help: Display a help modal that lists the keyboard shortcuts. Default: 191 (?)

    • next: Navigate to the "next" page. Default: 78 (n)

    • previous: Navigate to the "previous" page. Default: 80 (p)

    • search: Display the search modal. Default: 83 (s)

  • navigation_depth: The maximum depth of the navigation tree in the sidebar. Default: 2.

  • nav_style: This adjusts the visual style for the top navigation bar; by default, this is set to primary (the default), but it can also be set to dark or light.

    theme:
  name: mkdocs
  nav_style: dark

  • locale: The locale (language/location) used to build the theme. If your locale is not yet supported, it will fall back to the default.

    The following locales are supported by this theme:

    • en: English (default)
    • (see the list of existing directories mkdocs/themes/mkdocs/locales/*/)

    See the guide on localizing your theme for more information.

readthedocs

A clone of the default theme used by the Read the Docs service, which offers the same restricted feature set as its parent theme. Like its parent theme, only two levels of navigation are supported.

ReadTheDocs

In addition to the default theme configuration options, the readthedocs theme supports the following options:

  • highlightjs: Enables highlighting of source code in code blocks using the highlight.js JavaScript library. Default: True.

  • hljs_languages: By default, highlight.js only supports 23 common languages. List additional languages here to include support for them.

    theme:
  name: readthedocs
  highlightjs: true
  hljs_languages:
    - yaml
    - rust

  • analytics: Defines configuration options for an analytics service.

    • gtag: To enable Google Analytics, set to a Google Analytics v4 tracking ID, which uses the G- format. See Google's documentation to Set up Analytics for a website and/or app (GA4) or to Upgrade to a Google Analytics 4 property.

      theme:
  name: readthedocs
  analytics:
    gtag: G-ABC123

      When set to the default (null) Google Analytics is disabled for the

    • anonymize_ip: To enable anonymous IP address for Google Analytics, set this to True. Default: False.

  • include_homepage_in_sidebar: Lists the homepage in the sidebar menu. As MkDocs requires that the homepage be listed in the nav configuration option, this setting allows the homepage to be included or excluded from the sidebar. Note that the site name/logo always links to the homepage. Default: True.

  • prev_next_buttons_location: One of bottom, top, both , or none. Displays the “Next” and “Previous” buttons accordingly. Default: bottom.

  • navigation_depth: The maximum depth of the navigation tree in the sidebar. Default: 4.

  • collapse_navigation: Only include the page section headers in the sidebar for the current page. Default: True.

  • titles_only: Only include page titles in the sidebar, excluding all section headers for all pages. Default: False.

  • sticky_navigation: If True, causes the sidebar to scroll with the main page content as you scroll the page. Default: True.

  • locale: The locale (language/location) used to build the theme. If your locale is not yet supported, it will fall back to the default.

    The following locales are supported by this theme:

    • en: English (default)
    • (see the list of existing directories mkdocs/themes/readthedocs/locales/*/)

    See the guide on localizing your theme for more information.

  • logo: To set a logo on your project instead of the plain text site_name, set this variable to be the location of your image. Default: null.

Third Party Themes

A list of third party themes can be found at the community wiki page and the ranked catalog. If you have created your own, please add them there.