Documentation

Everything you need to go from "the docs are in the repo" to "the docs are on the page". Ten minutes, no server, no OAuth.

Getting started

1. Install SourceDocs from the Atlassian Marketplace (a Confluence admin does this once).
2. Open a page, type /sourcedocs and pick one of the three macros: File from Git, Diagram, Markdown.
3. For public repositories you are done. For private ones, an admin adds a read-only token under Settings → Apps → SourceDocs (see private repositories).

File from Git

Open the file in your Git provider's web UI and copy the address from the browser bar. Paste it into the macro. SourceDocs recognises these shapes:

The branch, tag or commit in the link is what gets shown. Point at main for "always current", at a tag for a frozen version.

The file type decides the rendering:

• .md, .markdown, .mdx: Markdown
• .mmd, .mermaid: Mermaid diagram
• .puml, .plantuml, .iuml, .wsd, or any text file starting with @startuml: PlantUML
• .yaml, .yml, .json containing an openapi or swagger field: API reference
• Anything else: syntax-highlighted source (40+ languages)

Use Preview in the dialog to check the file before saving. On the page, the bar above the content shows the provider, path, branch and the time of the last fetch; Refresh fetches the latest version immediately (otherwise SourceDocs re-fetches at most every 10 minutes).

Private repositories

A Confluence administrator stores one read-only token per provider on the admin page: Confluence Settings → Apps → SourceDocs. Every macro on the site then uses it; page authors and readers do not need their own Git access. Readers see whatever the author embedded, so embed with the same care as pasting.

After saving, click Test. Without a file link the test asks the provider who the token belongs to; with a file link from a private repository it fetches that file. Tokens are never shown again and never leave Atlassian; see the security page.

Diagram macro

Choose Mermaid or PlantUML, type on the left, watch the preview on the right. Insert example gives you a starting point for each diagram type. Ctrl+Enter saves.

• Mermaid 12: flowcharts, sequence, class, state, ER, Gantt, pie, mind maps, timelines, C4, architecture and the rest. Add a front-matter block to use the ELK layout engine for large flowcharts:

  ---
  config:
    layout: elk
  ---
  flowchart TB
    A --> B

  Raw HTML tags in labels are stripped so they do not cause syntax errors; <br> is kept.
• PlantUML 2026: sequence, class, component, deployment, use case, activity, state, mind map, WBS, Gantt, JSON/YAML, Salt wireframes and more, rendered entirely in the browser.
• Theme: "Match Confluence" follows the reader's light or dark mode; or pin one of Mermaid's themes.

On the page, hover a diagram for the toolbar: zoom out/in, reset, full screen, download SVG or PNG, copy source. "Fit diagrams to page width" shrinks wide diagrams to fit without clipping and never blows small ones up; turn it off to keep natural size with scrolling.

Markdown macro

Markdown written in the page with the same split editor. Useful for release notes, tables and checklists written by engineers who prefer text, and for pasting Markdown produced by AI assistants or CI without reformatting.

What Markdown is supported

• GitHub-flavoured Markdown: headings, emphasis, lists, nested lists, task lists (- [x]), tables, blockquotes, horizontal rules, autolinks, inline and fenced code with highlighting.
• Fenced mermaid, plantuml and puml blocks render as diagrams.
• Raw HTML commonly found in READMEs (<p align="center">, <img>, <details>, <kbd>) is rendered after sanitisation; scripts, styles and forms are removed.
• Relative links ([guide](./docs/guide.md)) open the file in the provider's web UI in a new tab. Anchor links (#section) scroll within the page; heading ids follow GitHub's slug rules.
• Relative images (![](./img/a.png)) are fetched from the repository with the stored token, so images in private repos work. Absolute image URLs are loaded directly by the browser from GitHub, GitLab, Bitbucket, Azure DevOps and common badge services (shields.io, badgen, Codecov, Coveralls, SonarCloud and others); images on other hosts appear as a link.

OpenAPI and Swagger

Point the File from Git macro at an OpenAPI 3.0 or 3.1 document (YAML or JSON) or a Swagger 2.0 document. SourceDocs shows a three-column API reference: navigation by tag and operation, descriptions and parameters, request and response samples with schema details. Search is built in. There is deliberately no "Try it out": nothing is sent anywhere from the page.

PDF export

Confluence's PDF export renders SourceDocs macros the way the page shows them: diagrams, Markdown and code appear in the PDF. For very long OpenAPI references the export shows the first part of the reference; link to the Confluence page for the full document.

Troubleshooting

Limits

• Files up to 2 MB; images up to 1 MB; files above 200 KB are not cached and are fetched on every view.
• Cache: 10 minutes per file, per site. Refresh bypasses it.
• Supported hosts: github.com, gitlab.com, bitbucket.org, dev.azure.com. Self-hosted GitHub Enterprise and GitLab are planned once Forge's customer-defined egress is generally available.

Migrating from other apps

Pages using other Markdown, Mermaid or PlantUML macros keep working; add SourceDocs macros alongside and remove the old ones when ready. Diagram sources are plain text in both: copy from the old macro's editor into the SourceDocs editor. If you have many pages, write to support@sourcedocs.dev and we will help plan the switch.

Release notes