# 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:

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

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

- `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)
  - `de`: German
  - `es`: Spanish
  - `fa`: Persian
  - `fr`: French
  - `id`: Indonesian
  - `it`: Italian
  - `ja`: Japanese
  - `nb`: Norwegian Bokmål
  - `nn`: Norwegian Nynorsk
  - `pt_BR`: Portuguese (Brazil)
  - `ru`: Russian
  - `tr`: Turkish
  - `uk`: Ukrainian
  - `zh_CN`: Chinese (Simplified, China)
  - `zh_TW`: Chinese (Traditional, Taiwan)

  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`: 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)
  - `de`: German
  - `es`: Spanish
  - `fa`: Persian
  - `fr`: French
  - `id`: Indonesian
  - `it`: Italian
  - `ja`: Japanese
  - `pt_BR`: Portuguese (Brazil)
  - `ru`: Russian
  - `tr`: Turkish
  - `uk`: Ukrainian
  - `zh_CN`: Chinese (Simplified, China)
  - `zh_TW`: Chinese (Traditional, Taiwan)

  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.

#### Search

From here you can search these documents. Enter your search terms below.

#### Keyboard Shortcuts

Keys | Action
--- | ---
`?` | Open this help
`n` | Next page
`p` | Previous page
`s` | Search