# How it works

Capable Markdown puts real markdown documents inside Confluence. It ships exactly two Confluence macros. A Markdown document macro that holds one document on a page, and a Markdown reference macro that points at a shared template and always shows its latest version. Plus a page byline entry, a "Capable Markdown" library page (global and per-space) with a catalogue, folders, version history and an AI "Studio", and a Search side panel. Documents are written in a three-mode editor (edit / split / preview) and can come from four places: written in place and stored under the page, a template from t

---

## In this section

[Three-mode markdown editorEdit (source only), Live (split source and preview) and Preview (rendered only), chosen by a toolbar tab switch; default is Live. A fourth internal mode, code-preview, is what the library page's 'Show Code' button turns on. Macros always re](https://help.gocapable.com/markdown/three-mode-markdown-editor.html)[Insert (+) menuGrouped under Image, Diagram and Other. Always present: 'From upload' (image, only when the surface has a page id), 'From web' (a placeholder image URL you then edit) and 'From code' (inserts a \`\`\`mermaid graph TD starter fence). 'From libr](https://help.gocapable.com/markdown/insert-menu.html)[Library images and diagrams by referencePicking from the library writes ordinary markdown image syntax pointing at a Capable reference URL. !\[title\](.../assets/images/assets/<id>) for images, and the same shape with the marker title "capable-diagram" for diagrams. These render li](https://help.gocapable.com/markdown/library-images-and-diagrams-by-reference.html)[Image upload and pasteUploading or pasting an image attaches the file to the page that renders the document (as a draft attachment, retried as current if the page is already published) and inserts !\[filename\](<siteUrl>/wiki/download/attachments/<contentId>/<file](https://help.gocapable.com/markdown/image-upload-and-paste.html)[GitHub-Flavored Markdown renderingRemark-gfm 4 (tables, task lists, strikethrough, autolinks, footnotes), GitHub blockquote alerts, heading slugs with autolinks, and Prism syntax highlighting. Capable adds rehype-sanitize and skipHtml on top.](https://help.gocapable.com/markdown/github-flavored-markdown-rendering.html)[Diagrams from fenced code blocksA fence in any of 27 Kroki languages is rewritten into a rendered SVG image: blockdiag, bpmn, bytefield, seqdiag, actdiag, nwdiag, packetdiag, rackdiag, c4plantuml, d2, dbml, ditaa, erd, excalidraw, graphviz, mermaid, nomnoml, pikchr, plant](https://help.gocapable.com/markdown/diagrams-from-fenced-code-blocks.html)[Markdown library pageA 'Capable Markdown' global page and space page with the catalogue at /conf/page/markdown and create / edit / view routes beneath it. Page title 'Markdown', subtitle 'Embed, share, and edit markdown content'. The edit view shows an Edit pan](https://help.gocapable.com/markdown/markdown-library-page.html)[Catalogue sectionsGetting started (dismissible), Studio (AI), the Create group (Markdown from scratch / from URL / from file, insert mode only), 'Markdown on pages' (My markdown / All markdown), Templates (Space templates / Global templates), Examples (bundl](https://help.gocapable.com/markdown/catalogue-sections.html)[Template librariesTemplates are Confluence custom content stored under a per-space Capable Capable storage (capability markdown, feature 'templates') in either the current space or the global space, and can be created directly inside a catalogue folder. Only](https://help.gocapable.com/markdown/template-libraries.html)[17 bundled starter templatesRead-only examples in three folders. General purpose (Checklist, Blog post, FAQ, Tutorial), Technical documentation and Project Planning (Process flow, Product requirements, Project proposal, User journey, Release notes, Meeting notes). The](https://help.gocapable.com/markdown/17-bundled-starter-templates.html)[Version historyA collapsible 'Version history' panel badged 'N Versions', hidden when there are none. Clicking a version loads that version's title and body into the editor as an unsaved change. It does not restore in place; saving afterwards writes a new](https://help.gocapable.com/markdown/version-history.html)[Remix and Save as template'Remix' duplicates a template (title, description, body, tags, category) into a new draft in the current space. Page-owned markdown viewed from the library shows 'Save as template', which copies it into the library. Page-owned markdown can](https://help.gocapable.com/markdown/remix-and-save-as-template.html)[Details and permissions panelsTitle (placeholder 'Untitled Markdown'), Description, Folder (for library templates not attached to a page), Container/space, Page, Created, Updated and Author. A permissions panel appears only for people who administer the asset's scope.](https://help.gocapable.com/markdown/details-and-permissions-panels.html)[Used on Pages panelLists pages that embed a template, five at a time, found by CQL on the capable\_refs\_markdown\_refs search alias. It counts only pages using the Markdown REFERENCE macro. A plain document macro contributes nothing. And only after the page has](https://help.gocapable.com/markdown/used-on-pages-panel.html)[AI Studio (Suite only)Drafts a markdown document from a prompt (20 suggested prompts; typing /page writes from the current page's content), then runs a second 'Validating diagrams' pass that repairs fenced diagram blocks (mermaid, plantuml/puml, graphviz/dot, d2](https://help.gocapable.com/markdown/ai-studio-suite-only.html)[Sharing a document'Copy URL' produces a deep link to the view page. 'Copy as macro' produces the reference URL .../assets/markdown/templates/<id>, which pastes into a page and auto-converts into the reference macro. Reference URLs are offered only for custom](https://help.gocapable.com/markdown/sharing-a-document.html)

---

## Related

[MacrosThe macros themselves.](https://help.gocapable.com/markdown/macros.html)

[AdministrationWhat an admin controls.](https://help.gocapable.com/markdown/administration.html)

[TroubleshootingWhen it does not.](https://help.gocapable.com/markdown/troubleshooting.html)

---

_How it actually behaves._