Skip to content

BetterEm

Overview

New in 12.0

BetterEm was rewritten from the ground up. Results are compatible with CommonMark parsing and pass all related tests. Some subtle difference may be observed compared to older versions, but these changes were made to align better with expected nesting conventions in the majority of parsers and to improve performance.

BetterEm is an extension that aims to improve emphasis (bold and italic) handling over the standard Python Markdown handling. In general, parsing behavior should be much closer to other parsers, within the bounds of what Python Markdown is capable of.

BetterEm provides a smart which controls whether emphasis is processed mid-word or not. When smart_enable is enabled, mid-word emphasis is intelligently ignored. This can be applied to asterisk and underscore emphasis, but since it usually only desirable to avoid mid-word emphasis in with underscores, it is only enabled for underscores by default.

With the default behavior, the feel will be very similar to GFM bold and italic, within the bounds of what Python Markdown is capable of.

The BetterEm extension can be included in Python Markdown by using the following:

import markdown
md = markdown.Markdown(extensions=['pymdownx.betterem'])

Reminder

Remember to read the Usage Notes for information that may be relevant when using this extension!

Note

For all examples on this page, underscores are smart and asterisks are not.

BetterEm requires that non-whitespace characters follow the opening token(s) and precede the closing token(s).

Whitespace
This * won't emphasize *

This *will emphasize*

This * won't emphasize *

This will emphasize

BetterEm allows for a more natural nested token feel.

Nested Token
***I'm italic and bold* I am just bold.**

***I'm bold and italic!** I am just italic.*

I'm italic and bold I am just bold.

I'm bold and italic! I am just italic.

BetterEm will try to prioritize the more sane option when nesting bold (**) between italic (*).

Prioritize Best
*I'm italic. **I'm bold and italic.** I'm also just italic.*

**I'm bold. *I'm bold and italic.* I'm also just bold.**

I'm italic. I'm bold and italic. I'm also just italic.

I'm bold. I'm bold and italic. I'm also just bold.

Options

Option Type Default Description
smart_enable string 'underscore' A string that specifies whether smart should be enabled for all, asterisk, underscore, or none.