Skip to content

Themes

By default, plugin assumes material theme usage, but you can use any other theme if you want.

Changing theme

To apply a new theme you'll need:

  • Add theme package
  • Apply new theme in mkdocs.yml
  • (optional) Remove material-related configurations in mkdocs.yml

For example, lets configure ivory theme.

First, we need to declare it's package in build.gradle:

python.pip 'mkdocs-ivory:0.4.6'

Note

Additional optional packages may be required for theme (e.g. like for material theme). Just add all required packages:

python.pip 'mkdocs-ivory:0.4.6', 
           'some-additional-package:1.0'

Then changing theme in mkdocs.yml:

theme:
  name: 'ivory'

Default mkdocs.yml (generated by plugin) contains special configurations related to material theme, which may be removed (in case of other theme used):

theme:
  name: 'material'
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode
  features:
    - navigation.tracking
    - navigation.top

extra:
  #  palette:
  #    primary: 'indigo'
  #    accent: 'indigo'

  version:
    provider: mike

  social:
    - icon: fontawesome/brands/github
      link: https://github.com/xvik
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/vyarus

# Google Analytics
#  analytics:
#    provider: google
#    property: UA-XXXXXXXX-X

plugins:
  - search
  - markdownextradata

markdown_extensions:
  # Python Markdown
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - meta
  - md_in_html
  - toc:
      permalink: true

  # Python Markdown Extensions
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - pymdownx.highlight
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

nav:
  - Home: index.md
  - Getting started: getting-started.md
  - User guide:
      - Configuration: guide/configuration.md
      - Pip: guide/pip.md
      - Variables: guide/vars.md
      - Multi-version: guide/multi-version.md
      - Publication: guide/publication.md
      - Tasks: guide/tasks.md
      - Themes: guide/theme.md
  - About:
      - Release notes: about/history.md
      - Migration notes: about/migration.md
      - License: about/license.md

Note

I don't know if markdown_extensions would work with your theme. You can experiment if you need these extra features (see material theme guide for extensions usage examples).