Show a GitHub README in Confluence

To show a GitHub README in Confluence, add the Github file (Capable) macro and choose the repository's README.md, or paste the README's github.com link into the editor. The macro renders the Markdown as formatted text, with headings, tables, code blocks and images, and reads it fresh from GitHub every time the page is viewed.

#Before you start

• You can edit the Confluence page.

• For a private repository, you have a connected GitHub account that can read it. See Connect your GitHub account to Confluence.

• For a public repository, readers need no GitHub account at all, logged-out readers included.

#Steps

1. Open the repository on github.com, open README.md and copy the address from the browser bar.

2. Edit the Confluence page and paste the link on an empty line. It turns into the Github file (Capable) macro.

3. If the link stays a link, type /Github, choose Github file (Capable), select Select File, paste the link into Search repositories or paste URL... and press Enter.

4. Check the preview, select Add to page if you used the picker, then publish the page.

#What happens next

The README appears as formatted text, not as source. Images and links that use relative paths, such as docs/diagram.png, load from the same repository and branch. Mermaid and other diagram code blocks inside the Markdown are drawn as diagrams.

When someone changes the README on GitHub, the page shows the new version the next time it is viewed. To see a change straight away, select Refresh content on the macro header.

#If it does not work

• The link pointed at /blob/refs/heads/main/README.md and the macro is broken: use the short /blob/main/README.md form. See this troubleshooting page.

• The repository still uses master: see Macro cannot find a file in a repository that still uses "master".

#Related

The README, where people actually read.