Github file

Updated
View as text
Open in Confluence
Open in ChatGPT Open in Claude

The Github file (Capable) macro displays one file from a GitHub repository on your page. It reads the file from GitHub each time the page is viewed, so the page never drifts from the repository. This page lists what it shows, its controls, its settings and every message it can display.

#Adding it

1
Insert
2
Pick the file
3
Publish

In the editor, type /Github and choose Github file (Capable). Or paste a github.com /blob/ link or a raw.githubusercontent.com link on its own line and the macro is created for you, already pointing at that file. See Auto-convert pasted GitHub links.

✓
Insert
2
Pick the file
3
Publish

Select Select File on the macro. The Browse Git Repositories window opens. Connect GitHub if asked, search or paste a link in Search repositories or paste URL..., browse to the file and select it to preview it. Filters for account, organisation and visibility sit above the list, and Manage Connections adds more accounts.

✓
Insert
✓
Pick the file
3
Publish

Select Add to page and publish. Step by step: Embed a GitHub file in Confluence.

#What it shows

File type

How it appears

Markdown (.md)

Formatted text. Relative images and links load from the same repository and branch, and diagram code blocks are drawn.

Diagram files (.mmd, .puml, .drawio, .excalidraw, .bpmn, .dot, .d2 and more)

The drawn diagram, with zoom, full-size and dark-mode controls. See Show a diagram from GitHub in Confluence.

Code, config, markup, data and text

A code viewer with syntax highlighting and line numbers, up to 600 pixels tall with its own scroll bar.

Images

The image, inline.

Anything else, such as PDF or zip

Not offered. The picker says This file type cannot be rendered.

#Header controls

Control

What it does

owner/repo/path and the ref in brackets

Shows where the file comes from. The ref only shows when it is not main. Select the path to open the file on GitHub.

Open on GitHub

Opens the file on github.com. Offered to every reader, logged-out readers included.

Refresh content

Fetches the file again. Signed-in readers only. See Refresh a GitHub file on a Confluence page.

#Settings

Setting

What it changes

Owner/repo

The repository the file is read from. Together with the file path, it decides whether the macro shows anything. If either is missing, the macro shows a "Select File" invitation instead of content.

Path inside the repository

The file to display. It also decides the file type and language, and where relative images in a Markdown file are loaded from.

Any branch, tag or commit ref

The branch, tag or commit the file is read at. It shows in brackets in the macro header only when it is not 'main'. The picker always uses the default branch; to choose another ref, paste a link that names it. See Show a GitHub file from a branch, tag or commit in Confluence.

Title

Typed in the picker before Add to page. It is not shown on the page; it labels the file in the page byline's list instead of the path.

Description

Stored with the macro but not shown anywhere, and there is no field to type one. See this troubleshooting page.

Show Border

Draws a border only around the macro's non-content states: the "Select File" invitation, and the anonymous, not-connected and error cards. A file that loads successfully is never bordered, so turning this off changes nothing on a working macro.

Show Line Numbers

On by default. Code currently always shows line numbers, whatever this says. See this troubleshooting page.

#Messages the macro can show

Message

What happened

Click the button below to select a file from GitHub

No file has been chosen yet. Select Select File. Logged-out readers see "No file has been selected for this macro" instead.

Connect a GitHub account with access to this repository to view this file

The file is private and none of your connected accounts can read it. Select Connect GitHub, or Open on GitHub.

A short notice with Open on GitHub only

A logged-out reader opened a private file. It never names the repository.

A red error with Retry and Configure

GitHub could not return the file: it moved, the branch is gone, or GitHub is unavailable. See Macro shows an error.

This file is empty

The file exists but has no content on that ref.

#A few things that catch people out

  • Editing the macro opens the Browse GitHub picker, not a settings form, and picking a different file resets the other settings to their defaults.

  • A pasted /blob/refs/heads/main/... link creates a broken macro. Use /blob/main/....

  • Line ranges such as #L10-L20 are ignored. The whole file shows.

  • Each view reads from GitHub, so very busy pages can hit GitHub's rate limits. See Limits.

One macro, documented properly.