Markup Studio - user guide

Install and set up

A Confluence administrator installs Markup Studio from the Atlassian Marketplace. There is nothing to configure: after installation anyone who can edit a page can insert the macro, and everyone who can see the page sees the rendered result - including guests and, in public spaces, anonymous visitors.

Add the macro

Type /markdown in the Confluence editor and choose Markdown (diagrams and formulas). The editor opens: write Markdown on the left, see the result on the right, press Save (or Ctrl/Cmd+S). To change it later, edit the page and click the macro's edit (pencil) button.

What you can write

• Standard Markdown: headings, bold, italic, strike, code, links, lists, quotes, tables, fenced code blocks, task lists (- [ ] / - [x]).
• Diagrams: a fenced block with the language mermaid:

  ```mermaid
  flowchart LR
    A[Start] --> B{Decision}
  ```
  

  Every diagram type built into Mermaid is supported (flowchart, sequence, class, state, ER, Gantt, pie, mindmap, timeline, C4, architecture and the others); ZenUML, which Mermaid ships as a separate plugin, is not. Use Expand (hover the diagram) for full screen with zoom. A diagram with a picture shape (A@{ img: "..." }) is not drawn - it says why - because pictures load only from your site; a diagram's own themeCSS, fontFamily and altFontFamily settings are ignored.
• Formulas: inline $E = mc^2$ or \( ... \); display $$ ... $$, \[ ... \] or a ```math block. GitHub's $`...`$ works too. Write \$ for a literal dollar sign. Prices stay text: the first $ after an opening one decides - if it is preceded by a space or followed by a digit, it closes nothing. So "It costs $5, and $x^2$ is the area" is a price and a formula, and "$5 or $10" is two prices. A $ inside code is code. \( ... \) and \[ ... \] are math unless they only hold words (\(optional\)), a bare number written tight (\[1\] - a citation) or follow a letter directly (file\(s\)): then they are escaped brackets. So is a single word or letter between \[ and \] in running text (name \[at\] example.com).

Callouts

GitHub alerts become coloured callouts, and Confluence panels in Word export:

> [!NOTE]
> Useful information.

Also [!TIP], [!IMPORTANT], [!WARNING] and [!CAUTION]. Obsidian callouts work as well: their other types ([!info], [!danger], [!bug], ...) take the colour of the nearest of these five and are titled with their own name ("Bug"), a title after the marker is kept (> [!note] Before you start), and folding signs (+, -) are shown open. Text after the marker that reads as a sentence - over 60 characters, or ending in a full stop - is the callout's text under its usual title.

Table of contents

Write [TOC] (or GitLab's [[_TOC_]]) on a line of its own, with a blank line before it (a heading directly above is fine): it becomes a table of contents of the macro's headings, each entry a link to its heading. Directly under a line of text or inside a list it stays as written. One per macro - a second marker stays as written - and at most 1,000 entries. In Word export the table is a plain nested list (Word has no links to these headings). Confluence's own Table of Contents macro cannot see headings inside an app macro; this is the way to get one.

Code blocks

Every code block has a Copy button in its corner (it appears when you point at the block or move to it with Tab) that copies the code exactly as written. Code is shown in one colour: syntax highlighting is not supported yet.

Collapsible sections

The way GitHub READMEs write them:

<details>
<summary>Show the full log</summary>

Markdown here - lists, code, tables.

</details>

The summary may also sit on the <details> line, follow it after a blank line or run over a few lines; sections can be nested, and <details open> starts open. A <details> without its closing line is a section to the end of the list item, quote or document it is in, as on GitHub. Printed pages show every section open; Word and PDF get the summary as a bold line followed by the content. A table-of-contents link to a heading inside a closed section opens it.

Emoji

GitHub's shortcodes for the emoji READMEs use most - :rocket:, :white_check_mark:, :x:, :warning:, :bulb:, :tada:, :+1: - 182 names in all - become the emoji. A name that is not on the list stays as written, and so do times such as 10:30:45. A heading's link target keeps the name, as on GitHub: ## :rocket: Launch is #rocket-launch.

HTML in Markdown

README files mix HTML into Markdown - centred logos, badge rows, tables of contributors. Markup Studio shows the common part of it much as GitHub does, but never runs what was pasted: every tag is read, checked against a fixed list and written anew by the app, and nothing else gets through.

• Understood: headings, paragraphs and <div> with align (left, center, right), <br>, <hr>, lists, quotes, definition lists, <pre>, tables (align, valign, colspan, rowspan, width), <details> with <summary>, links (<a href>), pictures (<img> with alt, width, height, align; <picture> shows its fallback picture), and formatting: <b>, <strong>, <i>, <em>, <var>, <s>, <del>, <strike>, <ins> (underlined), <code>, <tt>, <samp>, <kbd>, <sub>, <sup>, <mark>, <q>. Any other attribute is dropped.
• As on GitHub, <center>, <small>, <u>, <span>, <font>, <figure>, <dfn>, <abbr> and <cite> keep their text and lose their tags, and <svg> drawings are left out.
• What HTML leaves open stays open for what follows - Markdown and blank lines included - until its closing tag or the end of the list item, quote, callout or section it is in: a <div align="center"> centres the Markdown after it, a table's rows may be separated by blank lines, and a cell or a list item written in HTML may hold Markdown. A link or a heading written in HTML ends with its own block.
• Links and pictures follow the same rules as Markdown ones: web links open outside Confluence after confirmation, and a picture that is not on your site or Atlassian's media service is shown as its description (see "Links and images").
• Anchors - <a name="x"></a>, <a id="x">, or an id on a tag - are link targets, and a heading written in HTML gets the same link target as on GitHub, so #x links written for GitHub keep working; it is in the table of contents too.
• In the text of HTML, as on GitHub, web addresses become links, emoji shortcodes become emoji and formulas are typeset (<div align="center">$$ ... $$</div>) - but not inside <code>, <kbd> or <pre>.
• A block of HTML that holds <script>, <style>, <iframe>, a form or the like is shown as its source, in a quiet box that keeps its lines. In running text, a tag that is no HTML element (<username>) stays visible as written, a closing tag with nothing open to close is left out, and crossed formatting (<b><i>x</b>y</i>) is repaired as a browser repairs it.
• Blocks written inside a line of text are drawn as blocks, as on GitHub: a list, a table or a <details> section in a Markdown table's cell (| <ul><li>one</li><li>two</li></ul> |), a table in a paragraph, a heading in a link (<a href="..."><h1 align="center">Title</h1></a>, which also gets its link target and its place in the table of contents). What is still open closes at the end of the line. In Word their text comes in lines: a list item led by its bullet, a row's cells separated by " | ".

Also understood

• Front matter (--- ... --- with key: value lines at the very top) is shown as a quiet YAML block, never as a heading.
• HTML comments (<!-- ... -->) are hidden from readers, as on GitHub, in the page and in the Word export; an unclosed <!-- stays visible. They are still part of the stored text: editors see them, Confluence search finds their words, and a document too large to export with formatting goes to Word as its source, comments included.
• Strikethrough with one or two tildes, as on GitHub: ~old~, ~~old~~. A tilde that means "about" (~5 min) stays a tilde.
• Bare www. addresses become links, as on GitHub; file names such as README.md do not.
• Footnotes are not rendered yet: [^1] and [^1]: ... stay visible as written, nothing is lost.

Links and images

• Web and e-mail links open outside Confluence after Confluence asks you to confirm.
• Links to Confluence pages (/wiki/...) open in Confluence; #heading links jump to a heading of the same macro (headings get GitHub-style ids, so links written for a README keep working).
• Links to files next to the original document (docs/setup.md, ../x.md, /CONTRIBUTING.md) cannot work inside Confluence: they are shown as dotted text, with the address in the tooltip. Paths on your site (/wiki/..., /browse/ABC-1) open in Confluence or Jira.
• Images: pictures are shown when they come from your own Confluence site or Atlassian's media service, with a full https:// address - nothing is loaded from outside Atlassian. Any other picture - including a relative address such as /wiki/download/... - is shown as its description, linked to the picture. Images embedded in the text as PNG, JPEG, GIF or WebP (data:image/png;base64,...) are shown; embedded SVG is not accepted and stays as text.

Export

• PDF: the same content as Word, described below - text, tables, code and callouts, with diagrams and formulas as their source text. Confluence's printing of the live macro cut long documents off and could stall the export of the whole page, so the macro gives the PDF export a finished document instead.
• Word: text, tables, code and callouts are exported (callouts as Confluence panels); diagrams and formulas appear as their source text, images as their description. HTML keeps its structure: tables (header cells, spans, and Markdown written in a cell kept in the cell), lists, quotes, headings, <pre> blocks, formatting and links. Where Word allows no table - inside a list item, a quote or another table's cell - a table written in HTML becomes one line per row, its cells separated by " | ". A document whose formatted export would be larger than about 3 MB - for example a table of thousands of rows of many small cells - is exported as its Markdown source instead; beyond 200,000 characters only the beginning is exported, with a note.
• Pages with many macros: Confluence runs every macro separately during an export, so a page with many Markup Studio macros exports more slowly, and a very large one can hit Atlassian's platform limits; split very large pages.

When the subscription ends

Pages keep their text: readers see the saved Markdown source without formatting (HTML comments included - they are part of that source), the editor opens read-only with a note for the site administrator, and Word export exports the source. Renewing the subscription brings the formatting back; nothing needs to be re-entered.

Limits

• Up to 100,000 characters per macro (the editor counts them and stops Save above that; an emoji counts as two); up to 50 diagrams per macro are drawn and up to 2,000 formulas typeset - the rest show their source. A formula over 20,000 characters, or one whose typeset form would be very large (a big matrix), is shown as TeX with a note, and so are the formulas after the document's typeset formulas reach about 3 MB.
• HTML: at most 100 elements open inside one another; a tag in running text longer than 1,000 characters stays text (a picture's tag may be as long as the macro, for an embedded picture).
• Headings inside the macro are not picked up by Confluence's Table of Contents macro; write [TOC] in the macro instead.
• Diagrams that request the ELK layout are drawn with the standard layout (a note says so).
• HTML in Markdown is shown from a fixed list of elements and attributes and never runs as written (see "HTML in Markdown"); pictures written in HTML follow the same image rule as Markdown ones.

Troubleshooting

• "Diagram error": the message shows the line Mermaid could not parse; the source is shown under it.
• External links ask for confirmation before opening in a new tab (Confluence security).
• "Diagrams could not be loaded" / "Formulas could not be loaded": the page lost its connection or the app was updated while the page was open. Reload the page.
• Cancel with unsaved changes asks before throwing them away.
• The editor closed, or the page reloaded, before you saved? Open the editor again in the same browser tab: your unsaved text was kept there and Restore draft brings it back. Drafts never leave the tab, and closing the tab removes them.
• The editor could not load (for example right after the app was updated)? Press Close and open it again; your saved text is safe.

Support

https://markupstudio.dev/support - Monday to Friday, 09:00-17:00 Kyiv time (UTC+2, UTC+3 in summer); first response within one business day.