# 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](https://help.gocapable.com/git/connect-your-github-account-to-confluence.html).
* 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.

📝

Any Markdown file works the same way, not only READMEs: a `CHANGELOG.md`, a design doc or a runbook kept next to the code.

---

## 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](https://help.gocapable.com/git/pasted-a-link-like-github-com-owner-repo-blob-refs-heads-main-file-md-and-the-macro-is-broken.html).
* The repository still uses `master`: see [Macro cannot find a file in a repository that still uses "master"](https://help.gocapable.com/git/macro-cannot-find-a-file-in-a-repository-that-still-uses-master.html).

---

## Related

### [Github file](https://help.gocapable.com/git/github-file.html)

Every setting and what the macro shows.

### [Embed a GitHub file in Confluence](https://help.gocapable.com/git/embed-a-github-file-in-confluence.html)

Any file, picked or pasted.

### [Show a diagram from GitHub in Confluence](https://help.gocapable.com/git/show-a-diagram-from-github-in-confluence.html)

Draw a diagram file instead.

### [Auto-convert pasted GitHub links](https://help.gocapable.com/git/auto-convert-pasted-github-links.html)

Which links convert, and which do not.

---

_The README, where people actually read._