Guides / Markdown

Markdown in Confluence Cloud: write it or show .md files from Git

The Confluence Cloud editor understands a few Markdown shortcuts while you type and converts pasted Markdown once into rich text. After that it is ordinary Confluence content: you cannot edit it as Markdown again, and it does not follow the file in your repository. SourceDocs keeps Markdown as Markdown.

Write Markdown in the page

1. Install SourceDocs for Confluence from the Atlassian Marketplace. A Confluence admin does this once for the site.
2. Edit a page, type /markdown and pick SourceDocs: Markdown.
3. Type or paste Markdown on the left; the preview on the right updates as you type.
4. Press Ctrl+Enter (or click Save) and publish the page.

This is handy for text that is produced as Markdown anyway: release notes from CI, checklists, tables, and answers from AI assistants. Paste them without reformatting, and edit them later as Markdown.

Show a README or .md file from Git

1. Open the file in GitHub, GitLab, Bitbucket Cloud or Azure DevOps and copy the address from the browser bar. For a README, the repository's main page link is enough.
2. In Confluence, type /git, pick SourceDocs: File from Git, paste the link and click Preview.
3. Save. The page follows the branch or tag in the link and picks up changes within 10 minutes; Refresh fetches them immediately.

Private repositories work after an admin stores a read-only token once. More in embedding files from Git.

What is supported

• GitHub-flavoured Markdown: headings, emphasis, nested lists, task lists (- [x]), tables, blockquotes, autolinks and code blocks with syntax highlighting.
• GitHub alerts (> [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]) as coloured callouts.
• ```mermaid, ```plantuml and ```puml blocks drawn as diagrams. See Mermaid and PlantUML.
• The HTML that READMEs use (<p align="center">, <img>, <details>, <kbd>), cleaned of scripts, styles and forms.
• YAML front matter from Jekyll, Hugo, Docusaurus or MkDocs, shown as a small table instead of stray text.
• For files from Git: relative links open the right file in the repository, images from the repository load (private ones too), and heading links jump within the page.

Export

In PDF and Word export, Markdown becomes real Confluence headings, paragraphs, lists, tables and code blocks, and alerts become Confluence panels. Long documents paginate like the rest of the page instead of printing a cut-off screenshot. Diagrams are embedded as vector pictures.

Questions

Can I convert Markdown into normal Confluence content?

SourceDocs does not convert the page; the Markdown stays editable as Markdown. If you want a one-time conversion, paste the Markdown straight into the Confluence editor instead.

Do images on other websites show?

Images from Git providers and common badge services (shields.io, Codecov and others) show directly. Images on other websites appear as a link unless an admin allows images from any website on the SourceDocs admin page.

What does it cost?

Free for Confluence sites with up to 10 users. Above that, from 0.45 USD per user per month, with a 30-day free trial on the Marketplace.

More guides: Mermaid in Confluence · PlantUML in Confluence · Files from GitHub and GitLab in Confluence · OpenAPI in Confluence