LaTeX equations in Confluence.

On this page: What it does · Add an equation · A formula inside a sentence · Examples · Pasting · When something is wrong · On the page · Version history · PDF and Word export · Subscription · Accessibility · Limits · Troubleshooting · Privacy and security · Contact

What it does

Math for Confluence adds two macros to Confluence Cloud pages:

• Math block (LaTeX), for an equation on its own line.
• Math inline (LaTeX), for a formula inside a sentence.

You type LaTeX and see the equation as you type. It is drawn with KaTeX 0.19.

Add an equation

1. A Confluence admin installs Math for Confluence from the Atlassian Marketplace.
2. Edit a Confluence page and type /math. Choose Math block (LaTeX).
3. Type LaTeX in the editor, without $ signs. The preview shows the equation as you type: next to the code in a wide window, under it in a narrow one.
4. Choose the size: Display (full size, on its own line) or Text (the size of body text). Choose Center or Left.
5. Click Insert formula, or press Ctrl+Enter (Cmd+Enter on a Mac).
6. Publish the page.

To change a formula later, edit the page, select the formula and click the pencil. The button then says Save formula.

A formula inside a sentence

Type /math and choose Math inline (LaTeX). The editor is the same. The preview shows the formula inside a sample sentence. On the page it takes only the width of the formula, at text size.

Examples

The editor has one-click examples: Fraction, Quadratic formula, Sum, Integral, Limit, Matrix, Aligned, Cases, Chemistry and Probability. A few to copy:

x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}

A = \begin{pmatrix} a & b \\ c & d \end{pmatrix}, \quad \det A = ad - bc

\begin{aligned}
(a+b)^2 &= (a+b)(a+b) \\
        &= a^2 + 2ab + b^2
\end{aligned}

|x| = \begin{cases} x & \text{if } x \ge 0 \\ -x & \text{if } x < 0 \end{cases}

\ce{CH4 + 2 O2 -> CO2 + 2 H2O}

On the page, the commands KaTeX supports work, apart from a few that are switched off on purpose (see Limits). That includes \tag, \def and \newcommand inside one formula, colours, and chemistry with \ce and \pu. The full list is in KaTeX's supported commands. The Supported commands link in the editor opens it too.

Pasting

A formula pasted with $$ … $$, \[ … \], \( … \) or $ … $ around it is cleaned up. The delimiters are removed and the rest stays as it was.

When something is wrong

The preview says what is wrong in plain words, for example "A { is never closed" or "Unknown command \foo". It says where, for example "Line 3, column 6". It shows the line with a marker under the spot, and gives a hint. The spot is also underlined in the code. While you fix it, the last version that worked stays in the preview, faded.

On the page, it depends on who is looking:

• While the page is being edited, a broken formula shows the same box instead of the formula, so you see what to fix.
• People reading the published page see one short grey line where the formula would be: "This formula has an error. Edit the page to fix it." No LaTeX and no error wording. An inline formula shows "formula error" in the sentence, with that line on hover and for screen readers.
• An empty formula tells readers "No formula yet. Edit the page to add one."

On the page

• Copy LaTeX. Hover over an equation, or tab to it, and click LaTeX to copy its source. Selecting a formula and pressing Ctrl+C (Cmd+C on a Mac) also copies the LaTeX.
• Wide formulas. A formula wider than its column scrolls sideways inside its own box, with a short note under it. The page itself never scrolls sideways. With the keyboard, tab to the formula and use the arrow keys.
• Links in a formula (\href, \url) open in a new tab. Only http and https links become links.
• Light and dark. Formulas follow the Confluence theme, also when it is switched while the page is open.

Version history

Versions in the editor lists the last 20 saved versions of that formula, newest first. A very long formula keeps fewer, because the history of one formula is kept under 64 KB.

Click a version to load it into the editor. Nothing changes on the page until you save.

PDF and Word export

No JavaScript runs in an export. So when you export a page to PDF or Word, Confluence asks the app for a static version of each formula. The app makes it in its own function on Atlassian's Forge platform.

Not yet confirmed. We have not yet checked exported PDF and Word files in Confluence, so we don't promise how formulas look in them. If you rely on export, try it on a test page first.

Subscription

Math for Confluence is a paid app on the Atlassian Marketplace. Atlassian handles the trial, the subscription and the bill. The app only reads whether the subscription on your site is active. A trial counts as active.

Without an active subscription, for example when a trial ended without a subscription:

• Every formula stays on your pages. Readers, and people editing the page, see each formula as before. Your formulas are your content, stored in your pages, and the app never hides them.
• Copy LaTeX keeps working on every formula.
• Editing formulas is paused. Opening the formula editor shows "Editing formulas is paused" and asks you to contact a Confluence admin to renew the subscription. Nothing on the page changes.
• Version history is not written while editing is paused. Saved versions stay.

When the subscription is active again, the editor opens as always. Prices are on the Marketplace listing. To cancel, use the Atlassian Marketplace; refunds follow Atlassian's policy.

Accessibility

• MathML. Every formula is also written as MathML. The visual part is hidden from screen readers, so they read the MathML instead.
• Keyboard. All buttons have names, keyboard focus is visible, and a scrolling formula can be reached and scrolled with the keyboard.
• Errors. In the editor, an error is announced to screen readers once you pause typing, not on every key.
• Automated checks. Our tests run axe-core on a formula, an error as a reader and as a writer sees it, the inline macro and the editor, in light and dark. They find no serious or critical issues.

Limits and what is not confirmed yet

• Confluence Cloud only. Not Confluence Data Center or Server.
• 10,000 characters per formula.
• 1,000 command expansions per formula. A \def that uses itself stops with an error. So does a long formula with very many commands.
• 30,000 symbols after expansion. A short \def that repeats another one many times stops with "This formula is too large to draw" instead of freezing the page.
• Sizes are capped. On the page, very large sizes such as \rule{100000em}{…} are capped.
• Switched off on purpose: \includegraphics (it would load an image from anywhere), \htmlClass, \htmlId, \htmlStyle, \htmlData, and links other than http and https. They show as red text.
• One formula at a time. A \def in one formula does not carry over to the next.

Not yet confirmed. We have not tested these in Confluence yet, so we don't promise them:

• PDF and Word export: how formulas look in the exported file.
• Inline formulas: how a formula inside a sentence lines up with the text around it.
• Readers and writers: that Confluence tells the app, on every kind of page, whether the page is being edited. If it doesn't, a broken formula shows the short grey line while editing too. The formula editor always shows the full explanation.
• Include Page, Expand and Tabs: a formula on an included page, or in an Expand or tab that is closed.
• Many formulas: a page with 30 or more formulas.
• The LaTeX button: whether it may write to the clipboard inside Confluence. If not, select the formula and press Ctrl+C.
• Screen readers: how a formula sounds with a screen reader such as VoiceOver or NVDA.
• Browsers: Firefox and Safari.

If you rely on one of these, try it on a test page first, and tell us what you see.

Troubleshooting

You see	What it means
A box with a line and column instead of the formula	The LaTeX has a mistake at that spot. The box says what is wrong and gives a hint. Edit the formula to fix it. See When something is wrong.
"This formula has an error. Edit the page to fix it."	The same mistake, as a reader sees it. Edit the page to see what is wrong.
"This formula is too large to draw"	The formula grows past 30,000 symbols, for example through a \def that repeats another one many times. See Limits.
A command shows as red text	The command is switched off on purpose, or it is a link that is not http or https. See Limits.
"Editing formulas is paused"	The Math for Confluence subscription on your site is not active. Formulas on your pages still show. A Confluence admin can renew it. See Subscription.
The LaTeX button says "Press Ctrl+C"	The browser doesn't let the app write to the clipboard here. Select the formula and press Ctrl+C (Cmd+C on a Mac).
A formula has a scrollbar	It is wider than its column. Scroll inside the box, or put it in a wider column.

Privacy and security

Where is the formula stored? In the page itself, as the macro's settings, like any other Confluence macro. It follows the page's permissions and its version history. The app does not keep a copy of pages.

What is in the version history? Up to 20 saved versions per formula, at most 64 KB: the LaTeX, the size and alignment, and the time each version was saved. It is kept in Forge app storage, Atlassian's own storage for apps, under the macro's ID. It holds no user names, account IDs or page content.

What permissions does the app ask for? One: storage:app, for the version history. The app also allows inline styles in its own frame, because KaTeX places each symbol with them. It asks for no access to your Confluence content: no pages, no users, no spaces.

Where is the formula drawn? In the browser of the person viewing the page, from the app's own files. KaTeX and its fonts are part of the app. Nothing is loaded from a CDN or any other server, and the app has no permission to call outside servers.

What does the app send outside Atlassian? Nothing. There is no Dortus server behind the app, and nothing is sent to Dortus or to any third party. There is no analytics and no tracking.

Is there a part that runs outside the browser? Yes, inside Atlassian. The version history and the PDF and Word export run in the app's functions on Atlassian's Forge platform. For an export, Confluence sends the export function the formula, and the function returns a static version for the export file. It fetches nothing and logs nothing.

What does the app know about the subscription? Only whether it is active, which Atlassian tells the app. The app stores nothing about it.

What happens if I uninstall? The formula text is part of the page, so it follows the page's own retention and deletion. The version history in Forge app storage follows Atlassian's platform rules for app storage.

Third-party software. KaTeX (MIT), MathJax (Apache-2.0, export only), resvg-wasm (MPL-2.0, export only) and CodeMirror (MIT, editor only). All of them are part of the app.

The app is built on Atlassian Forge, for Atlassian's Runs on Atlassian programme. Full policy: Privacy policy, section 3.8. Terms: Terms of service.

Contact

Questions, a bug, or an idea? Email support@dortus.com. The person who builds the app reads every message. Please include your site URL, a link to the page, the LaTeX of the formula, your browser, what you expected and what happened.

See also: How to write LaTeX math in Confluence Cloud and Does Confluence have an equation editor?