Everything else

Start from what you are seeing rather than from what you think is broken. Each page below names the symptom, explains why it happens, and says what to do about it.

Several of these are the product working as designed, which is worth knowing before anybody raises a ticket.

#At a glance

Symptom	Usually because
Typed a title on my markdown macro and nothing changed on the page	Two reasons. First, the title strip only shows when 'Show Border' is on. With the border off there is nowhere to show it. Second, the title you type is saved with the document itself.
Filled in 'Markdown description' in the macro config, was warned about unsaved changes, saved, and the description did not appear	Saving does not carry the description through. The unsaved-changes warning still counts a description edit as a change, so you are prompted to save anyway.
Logged-out reader on a public page sees 'Sign in to view this markdown' instead of the document	The document is loaded from an external URL. URL markdown is fetched through Capable, which needs the reader to be signed in, and anonymous readers are not.
Diagram code blocks show as plain code instead of pictures for some readers	Drawing a diagram needs a Capable sign-in, which logged-out readers do not have. This is deliberate, not an error.
Images inside a markdown document show only alt text with a 'Sign in to view this image' tooltip	The image has to come through Capable and the reader is not signed in. Only images from Confluence itself, the Capable library, Unsplash and your approved domains load without a sign-in.
Image inside the document eventually turns into '[Image load timed out: …]'	The image did not load within 15 seconds.
Wrote HTML in my markdown and it disappeared entirely	Raw HTML is never shown. Both the editor preview and the published page remove anything outside the safe set of GitHub-style elements, with no warning.
LaTeX maths ($…$ or $$…$$) renders as literal dollar signs	Markdown here does not support LaTeX maths.
Mermaid diagram works in mermaid.js elsewhere but fails or looks different here	Diagrams are drawn by Capable's diagram service, not by the mermaid.js library in your browser, so syntax that only newer mermaid.js supports can fail.
We configured a self-hosted diagram renderer but markdown diagrams still go through Capable	The self-hosted renderer option is currently switched off.
Big document renders inside a small scrolling box with a '⚠️ Large content detected' banner	The document is over 500,000 characters, so it shows in a fixed-height scrolling box that draws only the part you can see.
Editor is replaced by 'Invalid markdown provided' naming some other language	Capable could not display the text, and it did not recognise it as markdown, HTML or Lua. A very code-heavy document can cause this.
Saving a macro fails with 'Unable to save changes as the loaded markdown is not associated with the	The stored document belongs to a different page from the one you are editing. This typically happens after you copy a page that carries the macro, before the copy has been sorted out.
Freshly inserted macro sits on a placeholder for a long time before showing content	The document has not been indexed yet, so the macro keeps checking every 15 seconds, for about two and a half minutes.

#In this section

Typed a title on my markdown macro and nothing changed on the pageI typed a title on my markdown macro and nothing changed on the page.Filled in 'Markdown description' in the macro config, was warned about unsaved changes, saved, and tI filled in 'Markdown description' in the macro config, was warned about unsaved changes, saved, and the description was gone.Logged-out reader on a public page sees 'Sign in to view this markdown' instead of the documentA logged-out reader on a public page sees 'Sign in to view this markdown' instead of the document.Diagram code blocks show as plain code instead of pictures for some readersDiagram code blocks show as plain code instead of pictures for some readers.Images inside a markdown document show only alt text with a 'Sign in to view this image' tooltipImages inside a markdown document show only alt text with a 'Sign in to view this image' tooltip.Image inside the document eventually turns into '[Image load timed out: …]'An image inside the document eventually turns into '[Image load timed out: …]'.Wrote HTML in my markdown and it disappeared entirelyI wrote HTML in my markdown and it disappeared entirely.LaTeX maths ($…$ or $$…$$) renders as literal dollar signsMy LaTeX maths ($…$ or $$…$$) renders as literal dollar signs.Mermaid diagram works in mermaid.js elsewhere but fails or looks different hereA mermaid diagram works in mermaid.js elsewhere but fails or looks different here.We configured a self-hosted diagram renderer but markdown diagrams still go through CapableConfigured a self-hosted diagram renderer but markdown diagrams still go through Capable.Big document renders inside a small scrolling box with a '⚠️ Large content detected' bannerA big document renders inside a small scrolling box with a '⚠️ Large content detected' banner.Editor is replaced by 'Invalid markdown provided' naming some other languageThe editor is replaced by 'Invalid markdown provided' naming some other language.Saving a macro fails with 'Unable to save changes as the loaded markdown is not associated with theSaving a macro fails with 'Unable to save changes as the loaded markdown is not associated with the current page'.Freshly inserted macro sits on a placeholder for a long time before showing contentA freshly inserted macro sits on a placeholder for a long time before showing content.

Troubleshooting

Every symptom.

Reference

Limits and gaps.

How it works

The behaviour.

Most of these are expected behaviour.