# Choosing your Theme

Selecting and configuring a theme.

---

MkDocs includes two built-in themes ([mkdocs](#mkdocs) and
[readthedocs](#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.

```yaml
theme:
  name: readthedocs
```

## mkdocs

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

![MkDocs theme in light mode](../img/mkdocs_theme_light_mode.png)

![MkDocs theme in dark mode](../img/mkdocs_theme_dark_mode.png)

In addition to the default [theme configuration options][theme], 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`.

    ![color mode toggle menu](../img/color_mode_toggle_menu.png){ width="315" }

*   **`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, which is bundled with the theme and
    served locally — no external CDN is required, so highlighting works in
    offline, intranet and privacy-sensitive environments. Default: `True`.

    Only the highlight.js assets that the configuration references are copied
    into the built site: the library itself, the styles selected by
    `hljs_style`/`hljs_style_dark`, and the languages listed in
    `hljs_languages`. When this option is set to `False`, no highlight.js
    files are copied at all.

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

    ```yaml
    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)][setup-GA4] or to
    [Upgrade to a Google Analytics 4 property][upgrade-GA4].

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

    ```yaml
    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` (&quest;)

    *   **`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)
    * `de`: German
    * `es`: Spanish
    * `fa`: Persian
    * `fr`: French
    * `id`: Indonesian
    * `it`: Italian
    * `ja`: Japanese
    * `nb`: Norwegian Bokmål
    * `nl`: Dutch
    * `nn`: Norwegian Nynorsk
    * `pl`: Polish
    * `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.

![The readthedocs theme](../img/readthedocs.png)

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

*   **`highlightjs`**: Enables highlighting of source code in code blocks using
    the [highlight.js] JavaScript library, which is bundled with the theme and
    served locally — no external CDN is required. Default: `True`.

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

    ```yaml
    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)][setup-GA4] or to
    [Upgrade to a Google Analytics 4 property][upgrade-GA4].

        ```yaml
        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)
    * `de`: German
    * `es`: Spanish
    * `fa`: Persian
    * `fr`: French
    * `id`: Indonesian
    * `it`: Italian
    * `ja`: Japanese
    * `nl`: Dutch
    * `pl`: Polish
    * `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

### Sumi

[Sumi] is the theme made for MkDocs NG, and the one this documentation site
uses. It bundles its fonts, icons and search, so it works offline, and adds a
command palette search, light and dark modes, landing pages, a blog and a
Markdown copy of every page for coding agents.

```bash
pip install mkdocs-sumi
```

```yaml
theme:
  name: sumi
plugins:
  - search
  - sumi
```

![The Sumi theme](../img/sumi.png)

See the [Sumi documentation][Sumi] for its options and components.

### More themes

A list of third party themes can be found at the [community wiki] page and [the ranked catalog][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.

[third party themes]: #third-party-themes
[theme]: configuration.md#theme
[Bootstrap]: https://getbootstrap.com/
[highlight.js]: https://highlightjs.org/
[styles]: https://highlightjs.org/static/demo/
[setup-GA4]: https://support.google.com/analytics/answer/9304153?hl=en&ref_topic=9303319
[upgrade-GA4]: https://support.google.com/analytics/answer/9744165?hl=en&ref_topic=9303319
[Read the Docs]: https://readthedocs.org/
[community wiki]: https://github.com/mkdocs-ng/mkdocs/wiki/MkDocs-Themes
[catalog]: https://github.com/mkdocs-ng/catalog#-theming
[Sumi]: https://sumi.mkdocs-ng.org/
[localizing your theme]: localizing-your-theme.md