Code Snippets from GitHub Gists

A Confluence app. Not made or endorsed by GitHub.

Embed public GitHub gists in Confluence pages with syntax highlighting. Show one file or every file as tabs, show only a range of lines, and highlight the lines that matter.

A Forge app with a UI Kit macro. It reads gists from GitHub's public REST API (api.github.com). That is its only external connection, and it is declared in the manifest.

Features

Paste any gist link

The macro takes these forms.

https://gist.github.com/<user>/<id>, https://gist.github.com/<id>, or the bare ID
links that pin a revision, such as /<user>/<id>/<sha>, gist.github.com/<id>/<sha> or <id>/<sha>
the script-embed form …/<id>.js?file=<name>, and the whole <script src="…"></script> tag from the gist page's Embed box (the app uses the link inside it)
raw links, both the gist page's Raw button (https://gist.github.com/<user>/<id>/raw/[<sha>/]<file>) and https://gist.githubusercontent.com/<user>/<id>/raw/[<sha>/]<file>. The file name in the link picks the file, and the gist is still read through the API. The Raw button's SHA is a gist revision, so that link pins the revision. The raw_url links that GitHub's API hands out carry the SHA of one file version instead, which GitHub doesn't know as a revision. For those the app shows the latest version of the gist, with a note.
API links https://api.github.com/gists/<id>[/<sha>]

Links to a gist's revisions, forks or stargazers page are refused, with a message that says so.

Pick a file, a range and the lines to highlight

Leave File empty to show every file as tabs (up to 20). Or name one file. Names match exactly first, then without regard to case. A link with a #file-… anchor or ?file= picks that file by itself.

Lines takes 10-25, 12, or 40- (from line 40 to the end). A link copied with GitHub's line anchor (#file-app-js-L10-L25) sets the range by itself, also when File names the same file. The Lines setting wins over the anchor. If File names a different file, the anchor's lines aren't used.

Highlight lines takes 12, 15-17. These are the file's own line numbers, as GitHub shows them, even when only a range is shown. Line numbers past the end of the file are left out, and a note says so.

Highlighting and display

Syntax highlighting covers about 70 languages (74 CodeBlock language values, counting aliases such as bash/zsh and plain text). The language comes from GitHub's own detection, with the file extension as a fallback. Unknown languages show as plain text.

Line numbers can be on or off. Long lines scroll sideways or wrap. A pinned revision shows a "revision abc1234" label and never changes.

Fast and gentle on GitHub's limits

Each gist is cached in Forge storage for 1 hour. A pinned revision is cached for 24 hours.
After that, the app asks GitHub "has it changed?" (If-None-Match). GitHub answers that question with a 304 and no body when nothing changed.
If GitHub is down or its rate limit is used up, the last copy (kept up to 24 hours) is shown with a short note.
When the limit is used up, the app stops calling GitHub until GitHub's reset time.

A GitHub token is optional, but we recommend one

Confluence admins can add it under Settings → Code Snippets from GitHub Gists. It raises GitHub's limit from 60 to 5,000 requests an hour. Without a token, requests come from Forge's cloud addresses, which may be shared with other apps. GitHub counts its 60 anonymous requests an hour per address, so that limit may already be used up. We haven't measured this yet.

The token is checked with GitHub before it's saved, kept in Forge secret storage, sent only to api.github.com, and never shown again. If it later expires or is revoked, gists keep loading anonymously. The token is tried again after an hour, and the settings page shows a warning until an admin replaces or removes it.

Using the macro

In the editor, type /Code snippet from GitHub Gist and insert the macro.
Open its settings and paste the gist URL or ID. Optionally fill in File, Lines and Highlight lines, and choose Line numbers and Long lines.
Publish. Readers see the code with a link to the gist on GitHub.

These are the messages you may see.

Message	Meaning
Check the macro settings	The link, file name, range or highlight could not be read. The message says why.
File not found in this gist	Lists the gist's files, so you can copy the right name.
Lines out of range	The range starts after the last line of the file.
Gist not found	GitHub has no such gist. It was deleted, or the ID is wrong. A revision link with a SHA that GitHub doesn't know shows this too, and names the revision. The app remembers a missing gist for 5 minutes and an unknown revision for 1 hour.
GitHub limit reached	GitHub's hourly limit (or its short-term "secondary" limit) is used up, and there is no saved copy. It gives the reset time. An admin can add a token.
Showing a copy saved … ago	GitHub could not be asked just now, so the last saved copy is shown.

When File is empty, Lines and Highlight are ignored, and a note says so. A range only makes sense for one file.

Limits

It shows public gists only. That includes secret (unlisted) gists, which anyone with the link can open. Private repositories and GitHub Enterprise aren't supported.
Each file shows at most 2,000 lines and 200 KB at once. Use Lines to show another part (when files show as tabs, set File to that file first). A single line longer than that is cut short.
Each macro shows at most 20 files as tabs and 600 KB of code in total. Later files show a short note instead (also a file whose first line no longer fits in what is left).
GitHub's gist API returns at most 1 MB of each file and lists at most 300 files. A cut-off file shows a note.
The cache keeps at most 2 MB of text per gist. Text with many quotes, backslashes or control characters takes more room in storage, so less of it may be kept. Files beyond that show "not loaded" with a link to GitHub. The gist itself is always cached.

What gets shown has a few more rules.

Binary files aren't shown. That covers files GitHub sends base64-encoded, files with an image, audio, video, font, PDF, ZIP or octet-stream type, and text with NUL bytes.
UI Kit's code block always numbers lines from 1. So when a range starts after line 1, its own numbers are hidden and a caption shows the real ones ("Lines 10-25 of 80").
Changes to a gist appear within about an hour. Pin a revision to freeze what is shown.

Data and privacy

The gist ID, and the revision when one is pinned, go to api.github.com. So does the admin's token, if one is set. Nothing from your Confluence pages or users is sent.

The app stores public gist data only. That means the owner's login, the description, file names, languages and contents. It's kept in Forge storage for up to 24 hours (48 hours for pinned revisions), plus the optional token. No avatars or other profile data are stored.

Because it contacts GitHub, the app doesn't qualify for the Runs on Atlassian badge. See PRIVACY.md.

Support Zovo

Zovo builds and maintains this app. If it saves you time, you can support the work on GitHub Sponsors. Sponsorship is optional, and the tool works the same without it.

Zovo is made by theluckystrike on GitHub.

More tools by Zovo

CodeBlock+. Adds code blocks with titles, line numbers and highlighted lines to Confluence.
Markdown + Mermaid. Renders Markdown and Mermaid diagrams in Confluence pages.
AskSpace. Lets people ask and answer questions inside Confluence.
Bulk Page Operations. Moves, copies, labels and archives up to 500 Confluence pages in one job, after a dry run.

License

MIT. See LICENSE. GitHub and Gist are trademarks of GitHub, Inc. They are used here only to say which service the app works with. This app is not made or endorsed by GitHub.

Support this work

If this app saves you time, you can support the work on GitHub Sponsors. Monthly tiers start at $5, and one-time tiers start at $15. Sponsorship is optional, and the tool works the same without it.

Zovo on GitHub