Caret

Overview

New in 12.0

Caret was rewritten from the ground up. 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.

Caret optionally adds two different features which are syntactically built around the ^ character. The first is insert which inserts <ins></ins> tags. The second is superscript which inserts <sup></sup> tags.

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

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

Tip

PyMdown Extensions uses one delimiter processor for emphasis, deletions, insertions, subscripts, superscripts and marks via BetterEm, Tilde, Caret, and Mark. This allows all delimiter to be parsed simultaneously providing the best nesting logic. So for best results, pair Caret with BetterEm.

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

Insert

To wrap content in an insert tag, simply surround the text with double ^. You can also enable smart_insert in the options. Smart behavior of insert models that of BetterEm.

Insert

^^Insert me^^

Insert me

Superscript

To denote a superscript, you can surround the desired content in single ^. It uses Pandoc style logic, so if your superscript needs to have spaces, you must escape the spaces.

Superscript

X^2^ + 4x - 8

text^a\ superscript^

X² + 4x - 8

text^{a superscript}

If desired, the Pandoc requirement of "no spaces", unless they are escaped, can be disabled via the no_space option.

Superscript

X^2^ + 4x - 8

text^a superscript^

text^{a superscript}

New in 12.0

no_space is new in 12.0.

12.2 CommonMark Punctuation Rule Change

12.0 introduced a rewrite of emphasis handling which brought emphasis handling into alignment with CommonMark rules. Caret, being based on the same core logic, inherits the same CommonMark rules.

It was found that specifically the CommonMark punctuation rules were somewhat surprising for some when dealing with superscripts. In 12.2, for backwards compatibility, Caret now disables CommonMark punctuation rules any time superscript is enabled. If superscript is not enabled, insert notations will follow CommonMark punctuation rules.

If it is desired to force CommonMark punctuation rules in superscript, punctuation can be enabled in the options. You will need to escape punctuation any time it conflicts with CommonMark rules.

Options

Option	Type	Default	Description
`smart_insert`	bool	`False`	Use smart logic with insert characters.
`insert`	bool	`True`	Enable insert feature.
`superscript`	bool	`True`	Enable superscript feature.
`no_space`	bool	`True`	Enable Pandoc style requirement of "no unescaped spaces".
`punctuation`	bool	`False`	Enable CommonMark punctuation rules even when subscript tags are enabled".