Block KaTeX

With the katex language ID, you can render mathematical and scientific equations in your content by writing KaTeX markup inside of a codeblock.

By default, when your KaTeX markup is rendered with a codeblock, it’s rendered as a sref<div> element and in display mode. This centers the rendered markup and adds a top and bottom margin to the block.

To use KaTeX for inline markup, see the katex shortcode instead.

Syntax #

Language ID: katex #

With Attributes #

```katex { [.class [.class]] [#id] [as_figure=(true|false)] [display=(true|false)] }
<KaTeX Markup>
```

With Data #

```katex
---
as_figure: false
caption: caption
caption_position: (top|bottom)
class: class
display: true
id: id
---

<KaTeX Markup>
```

Language ID: chem #

With Attributes #

```chem { [.class [.class]] [#id] [as_figure=(true|false)] [display=(true|false)] }
<KaTeX Markup>
```

With Data #

```chem
---
as_figure: false
caption: caption
caption_position: (top|bottom)
class: class
display: true
id: id
---

<KaTeX Markup>
```

Language ID: math #

With Attributes #

```math { [.class [.class]] [#id] [as_figure=(true|false)] [display=(true|false)] }
<KaTeX Markup>
```

With Data #

```math
---
as_figure: false
caption: caption
caption_position: (top|bottom)
class: class
display: true
id: id
---

<KaTeX Markup>
```

Examples #

1. Quadratic Formula #

Markdown Input
```katex
x={\frac {-b\pm {\sqrt {b^{2}-4ac}}}{2a}}
```
HTML Output
<div >
  \[
    x={\frac {-b\pm {\sqrt {b^{2}-4ac}}}{2a}}
  \]
</div>
Rendered Output
\[ x={\frac {-b\pm {\sqrt {b^{2}-4ac}}}{2a}} \]

2. With Classes #

This example uses the class attribute to add classes to the rendered div. Together, these classes change how the KaTeX is displayed after it’s rendered.
Markdown Input
```katex { .example .katex }
x={\frac {-b\pm {\sqrt {b^{2}-4ac}}}{2a}}
```
HTML Output
<div class="example katex">
  \[
    x={\frac {-b\pm {\sqrt {b^{2}-4ac}}}{2a}}
  \]
</div>
Rendered Output
\[ x={\frac {-b\pm {\sqrt {b^{2}-4ac}}}{2a}} \]

3. Inline Mode #

This example uses the display attribute to force the rendered KaTeX to display in inline mode instead of the default display mode.
Markdown Input
```katex { display=false }
x={\frac {-b\pm {\sqrt {b^{2}-4ac}}}{2a}}
```
HTML Output
<div >
  \(
    x={\frac {-b\pm {\sqrt {b^{2}-4ac}}}{2a}}
  \)
</div>
Rendered Output
\( x={\frac {-b\pm {\sqrt {b^{2}-4ac}}}{2a}} \)

4. As Figure with Caption #

This example uses the options syntax to define a caption for the formula. That ensures the KaTeX markup is rendered inside a figure. You could add it as a figure without the caption by setting the as_figure attribute or option to true.
Markdown Input
```katex
---
caption: The Quadratic Formula
---
x={\frac {-b\pm {\sqrt {b^{2}-4ac}}}{2a}}
```
HTML Output
<figure>
  <div >
    \[
      x={\frac {-b\pm {\sqrt {b^{2}-4ac}}}{2a}}
    \]
  </div>
  <figcaption>
    The Quadratic Formula
  </figcaption>
</figure>
Rendered Output
\[ x={\frac {-b\pm {\sqrt {b^{2}-4ac}}}{2a}} \]
The Quadratic Formula

5. Chemistry #

Markdown Input
```chem
\ce{CO2 + C -> 2 CO}
```
HTML Output
<div >
  \[
    \ce{CO2 + C -> 2 CO}
  \]
</div>
Rendered Output
\[ \ce{CO2 + C -> 2 CO} \]

Attributes #

class #

Specify any additional classes to add to the div containing the rendered formula. By default, the div has no classes.

If as_figure is true, the classes are added to both the figure and the div.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

id #

Specify an ID to add to the div as the id attribute. This makes it easier to link directly to a formula. If this value isn’t specified, the div has no ID.

If as_figure is true, the ID is added to the figure instead.

Specify the ID as a bare string without any spaces and with a # prefix, like #my-id

Required: false
Type: String

as_figure #

Specify whether to render the KaTeX inside a <figure> element. When this value is true, the formula is added inside a figure and the id and class both apply to that figure. The class is also inherited on the div for the formula.

Specify true or false without wrapping quotes.

Required: false
Type: Boolean

display #

Specify whether the rendered markup should use display mode. In display mode, the rendered math is centered and the div element displays as a block with a 1em vertical margin. In inline mode, the math is displayed without any additional margin.

By default, the KaTeX is rendered in display mode. Set this value to false to render in inline mode.

Specify true or false without wrapping quotes.

Required: false
Type: Boolean

YAML Options #

as_figure #

Specify whether to render the formula inside a <figure> element. When this value is true, the formula is added inside a figure and the id and class both apply to that figure. The class is also inherited on the div for the formula.

Specify true or false without wrapping quotes.

Required: false
Type: Boolean

caption #

Specify Markdown to use as the caption for the figure element. If this value is set, the formula is rendered inside a figure element even if as_figure isn’t set to true.

The caption’s Markdown is rendered as a block without wrapping <p> tags inside a <figcaption> element. By default, it’s added beneath the formula.

You can use the caption_position option to render the caption above the formula in the figure.

To write a multiline string, specify either | or > after the key. Add a - to trim the final newline. For example:

caption: |
  This is a multiline entry. The line endings are respected,
  meaning this would render as two paragraphs.

  This is the second paragraph. Because there's no `-`,
  This would include a trailing newline.  
caption: |-
 This multiline entry trims the final newline. 
caption: >
  This entry replaces the newlines, except for the
  last one, with spaces. With the `-`, that final
  newline would be trimmed too.

This value is rendered as a block of Markdown. If there’s only one line, that line is wrapped in <p> tags.

RendersMarkdown: true
Required: false
Type: String

caption_position #

Specify either top or bottom to render the figure’s caption above or below the formula. The default value is bottom. This option is ignored if caption isn’t set or is empty.

Required: false
Type: Enum
ValidValues:
- top
- bottom

class #

Specify any additional classes to add to the div containing the rendered formula. By default, the div has no classes.

If as_figure is true or caption is set, the classes are added to both the figure and the div.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

display #

Specify whether the rendered markup should use display mode. In display mode, the rendered math is centered and the div element displays as a block with a 1em vertical margin. In inline mode, the math is displayed without any additional margin.

By default, the KaTeX is rendered in display mode. Set this value to false to render in inline mode.

Specify true or false without wrapping quotes.

Required: false
Type: Boolean

id #

Specify an ID to add to the div as the id attribute. This makes it easier to link directly to an equation. If this value isn’t specified, the div has no ID.

If as_figure is true or caption is set, the ID is added to the figure instead.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

Definition #

Inside the codeblock, you can use any valid KaTeX functions and Platen will render them.

If you use the \ce{...} expression for chemistry equations in a codeblock or give a codeblock the chem language ID, Platen loads the mhchem library for you.

The math and chem language IDs are included for readability and convenience. All three language IDs work the same way.

Edit this page