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. Branch names containing a slash (release/2.0, feature/login) work as well.

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.

Your own Git server

SourceDocs also reads files from GitLab and GitHub Enterprise running on your company's own server: GitLab self-managed and GitLab Dedicated, GitHub Enterprise Server and GitHub Enterprise Cloud with data residency (ghe.com). Bitbucket Data Center and Azure DevOps Server are not supported yet; write to [email protected] if you need them.

1. On the admin page (Confluence Settings → Apps → SourceDocs), under Your own Git servers, choose the type and enter the server's address, for example https://git.example.com.
2. Click Add server. Atlassian shows its own dialog naming the server; an Atlassian administrator approves it. Forge then lets SourceDocs reach that server and nothing else new. The approval can be reviewed or withdrawn in Atlassian administration under the app's data management, or by removing the server on the admin page.
3. If the repositories are private, add a token for the server under Add or replace a credential (the same token types as GitLab.com and GitHub), then click Test with a file link from the server.

The server must be reachable from Atlassian's cloud over HTTPS with a publicly trusted certificate. If it is behind a firewall, allow Atlassian's outgoing IP addresses (the Forge platform uses them). Servers installed under a path (https://example.com/gitlab) are not supported yet. Up to 10 servers per site.

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.
• PlantUML !include: the C4-PlantUML library (!include <C4/C4_Container> or its raw GitHub URL), any Git file link SourceDocs understands, and paths relative to the file being shown (!include common/styles.puml). Included files are fetched through the app like any other file, with the stored credential for private repositories. Other PlantUML standard libraries (AWS, Azure icons) are not available yet.
• 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.
• GitHub alerts: > [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] and [!CAUTION] blockquotes appear as coloured callouts.
• YAML front matter (Jekyll, Hugo, Docusaurus, MkDocs) at the top of a file is shown as a small table instead of stray text.
• 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

SourceDocs exports as real Confluence content, so PDF and Word files paginate like the rest of the page instead of printing a screenshot of the macro:

• Markdown and READMEs become native headings, paragraphs, lists, tables and code blocks; GitHub alerts become Confluence panels; images from the repository are embedded. Text flows across pages and is never cut through a line.
• OpenAPI becomes a printable API reference: one section per operation with parameter, request-body and response tables, example JSON and a schema section.
• Diagrams are embedded as sharp vector pictures in the light theme. SourceDocs keeps the picture of each diagram a reader has seen, so a page that was opened after its last edit exports instantly. A diagram nobody has viewed yet is printed from the live macro instead.
• Code becomes a Confluence code block with syntax highlighting (the first 4,000 lines of very long files).
• Each exported Git file starts with a small "Source" line linking to the file and the date it was fetched.

Badges and images hosted outside GitHub and GitLab appear in exports as links with their alt text.

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, and up to 10 of your own GitLab or GitHub Enterprise servers added on the admin page. Bitbucket Data Center and Azure DevOps Server are not supported yet.

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 [email protected] and we will help plan the switch.

Release notes