mkdocs/docs/user-guide/choosing-your-theme.md

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.

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

• color_mode: Set the default color mode for the theme to one of light, dark, or auto. The auto mode will switch to light or dark based on the system configuration of the user's device. Default: light.

• user_color_mode_toggle: Enable a toggle menu in the navigation bar which allows users to select their preferred color_mode (light, dark, auto) from within the browser and save their preference for future page loads. The default selection of the toggle menu on first page load is the value set to color_mode. Default: false.

  

• nav_style: Adjust the visual style of the top navigation bar. Set to one of primary, dark or light. Default: primary. This option is independent of the color_mode option and must be defined separately.

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

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

• hljs_style_dark: Set this to the name of the desired highlight.js style when in dark mode. Default: github_dark.

• 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.

  • 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: mkdocs
      analytics:
        gtag: G-ABC123
    

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

• 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.

• locale{ #mkdocs-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.

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{ #readthedocs-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.

WARNING: Installing an MkDocs theme means installing a Python package and executing any code that the author has put in there. So, exercise the usual caution; there's no attempt at sandboxing.