Skip to main content

Plugin to extend MkDocs Material theme.

Project description

MkDocs Pymdownx Material Extras

A plugin for MkDocs -- specifically the MkDocs Material Theme.

Adds additional resources that are used in the PyMdown Extensions documentation, and other @facelessuser projects.

While this is not specifically meant for outside consumption, and was originally written for @facelessuser projects, it can be freely used if desired.

Files are copied from the pymdown-extensions project.

Instructions

This is bound to specific versions of MkDocs Material and PyMdown Extensions. It may sometimes be tied to betas.

Installation:

pip install mkdocs_pymdownx_material_extras

Add it to your mkdocs.yml plugins. It is assuming you are using MkDocs Material. When doing so, remember to add back the search plugin as it doesn't append to the plugins, but overrides the plugins:

plugins:
  - search
  - mkdocs_pymdownx_material_extras

Setup your theme as follows:

theme:
  name: material # Must use Material theme
  custom_dir: docs/theme # If you have overrides, specify where to find them
  palette:
    scheme: dracula # This is how to enables the Dracula theme for dark. For light, it will use default Material with some tweaks.
    primary: deep purple # Primary colors
    accent: deep purple # accent color

The following Material primary/accent colors map to actual Dracula colors:

Material Dracula
red red
pink pink
purple purple
deep-purple purple
blue blue
indigo blue
light-blue blue
cyan cyan
teal cyan
green green
light-green green
lime green
yellow yellow
amber yellow
orange orange
deep-orange orange

Sponsor Footer Link

If you'd like to add the sponsor heart in the footer, add your sponsor link under the MkDocs theme options like so.

theme:
  pymdownx:
    sponsor: "https://github.com/sponsors/facelessuser"

Mermaid Support

Mermaid support is baked in. Simply add the Mermaid script to your MkDocs config:

extra_javascript:
  - https://unpkg.com/mermaid@8.8.4/dist/mermaid.min.js

If you do not like our default setup, you are free to modify it. Simply provide a script file before before you include Mermaid with the new config:

extra_javascript:
  - my_mermaid_config.js
  - https://unpkg.com/mermaid@8.8.4/dist/mermaid.min.js

Also, setup your Mermaid diagrams:

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        # Mermaid diagrams
        - name: diagram
          class: diagram
          format: !!python/name:pymdownx.superfences.fence_code_format

Then you can specify your Mermaid diagrams in diagram code blocks:

```diagram
...
```

Mermaid setups are provided per scheme. You can see the setup here. if you are trying to override them.

MathJax/KaTeX

Again, MathJax and KaTeX support is baked in. Simply add the MathJax script(s) to your MkDocs config:

MathJax:

extra_javascript:
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

KaTeX:

extra_javascript:
  - https://cdn.jsdelivr.net/npm/katex@0.13.18/dist/katex.min.js

Lastly, setup Arithmatex:

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true # Must use generic mode
      block_tag: 'pre' # We wrap block math in `<pre>` to avoid issues with MkDocs minify HTML plugin: https://github.com/byrnereese/mkdocs-minify-plugin

If you do not like the default MathJax setup, add your own config before MathJax script:

extra_javascript:
  - my_mathjax_config.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_pymdownx_material_extras-2.3.1.tar.gz (24.6 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page