Skip to content

FAQ

Function References in YAML

How do I specify function references in YAML if I am using a module like MkDocs?

Pymdown Extensions has a number of extensions that expose customization via options that take function references. If you are using a project like MkDocs, which allows a user to configure Python Markdown extensions via YAML, specifying function references may not be intuitive.

Keep in mind that the following examples specifically reference YAML configurations that are implemented via PyYAML and are configured to allow Python objects.

When specifying a function reference in PyYAML, you must prepend the function with !!python/name:. For instance, to specify Python Markdown's Toc extension to use one of PyMdown Extensions' slugs in MkDocs:

markdown_extensions:
  - markdown.extensions.toc:
      slugify: !!python/name:pymdownx.slugs.uslugify
      permalink: "\ue157"

To specify a particular emoji generator in the Emoji extension:

markdown_extensions:
  - pymdownx.emoji:
      emoji_generator: !!python/name:pymdownx.emoji.to_png

GitHub-ish Configurations

How do I get GitHub Flavored Markdown?

As the GitHub extension is now deprecated, a recommended GitHub configuration is provided below to emulate a setup that gives a GitHub feel.

For GitHub issue, commit, pull request, and mention shorthand syntax, you will also need to specify a provider, user and repo in the MagicLink extension to give relative context for shorthand links (like #1) so that links can properly be generated. In the example below, we will use facelessuser and pymdown-extensions as the user and repository respectively. See MagicLink for more details.

Tip

If you are attempting to configure these options in a YAML based configuration (like in MkDocs), please see the related FAQ question to see how to specify function references in YAML.

extensions = [
    'markdown.extensions.tables',
    'pymdownx.magiclink',
    'pymdownx.betterem',
    'pymdownx.tilde',
    'pymdownx.emoji',
    'pymdownx.tasklist',
    'pymdownx.superfences'
]

extension_config = {
    "pymdownx.magiclink": {
        "repo_url_shortener": True,
        "repo_url_shorthand": True,
        "provider": "github",
        "user": "facelessuser",
        "repo": "pymdown-extensions"
    },
    "pymdownx.tilde": {
        "subscript": False
    },
    "pymdownx.emoji": {
        "emoji_index": pymdownx.emoji.gemoji,
        "emoji_generator": pymdownx.emoji.to_png,
        "alt": "short",
        "options": {
            "attributes": {
                "align": "absmiddle",
                "height": "20px",
                "width": "20px"
            },
            "image_path": "https://assets-cdn.github.com/images/icons/emoji/unicode/",
            "non_standard_image_path": "https://assets-cdn.github.com/images/icons/emoji/"
        }
    }
}