Gollum Markdown Syntax for GitHub Wikis: Links, Macros, and Tips

Gollum markdown is ordinary Markdown plus a layer of double-bracket tags: [[Page]] links, [[image.png]] embeds, [[_TOC_]], and [[include:Page]]. GitHub wikis grew out of Gollum, so the link tags work there too, but the macros don't. This guide shows which tags render where, and how to edit a wiki from a real editor.

Is GitHub Wiki the Same as Gollum?

Not any more. Gollum is an open-source, Git-backed wiki written in Ruby, and GitHub's wiki feature was built on it. Today the Gollum project wiki states plainly that Gollum and GitHub wikis have diverged, with "very significant differences" between the two. The README still says Gollum strives to stay compatible with GitHub and GitLab wikis, so you can clone either and edit it locally.

What that means for you: the link syntax below is shared, the file conventions (Home.md, _Sidebar.md, _Footer.md) are shared, but the macro system is Gollum-only. Self-hosted Gollum renders Markdown with the kramdown gem by default; GitHub.com renders wiki pages with the same Markup library it uses for READMEs. Both accept GFM basics, so keep our GitHub Markdown cheat sheet open for tables, task lists, and code fences. This post covers only the wiki layer on top.

Gollum Markdown Link Syntax

The double-bracket link is the tag you'll type most. Wrap a page name in [[ ]] and Gollum links to that page; add a pipe to change the visible text.

[[Installation]]
[[How to install|Installation]]
[[Getting Started]]

The first renders as a link reading "Installation" that points to Installation.md. The second reads "How to install" and points to the same page. The third links to a page whose file is Getting-Started.md. Gollum maps a space in the link to a dash in the filename, and shows the dash as a space in the title.

Page names are the filenames without the extension, so keep them short. GitHub Docs bans these characters in wiki titles: backslash, slash, colon, asterisk, question mark, quote, angle brackets, and pipe.

Standard Markdown links still work alongside the tags. [Installation](Installation) produces the same result on GitHub.com, and a full URL works everywhere. For the rules behind ordinary links, see our Markdown links guide. One caveat: GitLab wikis also accept [[Home]] and [[Label|slug]], per the GitLab wiki Markdown docs, so this part of the syntax travels well.

To show a tag literally instead of rendering it, Gollum's rule is a leading single quote: '[[Installation]] prints the brackets. On GitHub.com, wrapping the tag in backticks is the safer way to display it.

Gollum Markdown Tags: Images, TOC, Includes, and Macros

Beyond links, the same bracket syntax handles images, a table of contents, and transclusion. The Gollum wiki home page documents these:

[[diagram.png]]
[[diagram.png|alt=Architecture diagram, frame, align=center, width=400px]]
[[_TOC_]]
[[_TOC_|levels = 3]]
[[include:Shared-Footer]]

The image tag takes comma-separated attributes: alt=, frame, align= (left, center, right), float, height=, and width= in px or em. [[_TOC_]] inserts a table of contents built from the page's headings; it's case-sensitive, and the levels option limits depth. [[include:Page]] pastes another page's content in place, which is how you share a boilerplate block across pages.

Gollum also has macros in double angle brackets. The Standard Macros page lists <<AllPages()>>, <<GlobalTOC()>>, <<Navigation()>>, <<Series("prefix")>>, <<Note(string)>>, <<Warn(string)>>, <<Octicon(string)>>, <<Video(/path)>>, and <<Audio(/path)>>. <<Note()>> and <<Warn()>> draw coloured callout boxes, which is the closest Gollum gets to GitHub's alert syntax.

This is where the two platforms split. GitHub's wiki editing docs state that transclusion, definition lists, indentation, and tables of contents are unsupported for security and performance reasons, and nothing there mentions macros. A [[_TOC_]] on GitHub.com is therefore treated like any other bracket link, pointing at a page called _TOC_. Treat everything in this section as self-hosted-only until you've checked it on your platform. For a GitHub.com wiki, our table of contents guide shows the manual list that works everywhere.

Special Pages: Home, _Sidebar, and _Footer

Three filenames have fixed meanings. Home.md is the landing page. Per GitHub Docs on footers and sidebars, a file named _Sidebar.md fills the sidebar and _Footer.md fills the footer of every page. The web UI offers "Add a custom sidebar" and "Add a custom footer" buttons that create exactly those files.

A typical sidebar is a short link list, and it's a good place for the wiki-link syntax:

**Docs**

- [[Home]]
- [[Installation]]
- [[Configuration]]
- [[FAQ]]

Self-hosted Gollum reads the same filenames, so a sidebar written for GitHub.com works after a clone. If you're deciding between a README and a wiki at all, the rule we use is simple. The README answers "what is this and how do I run it" in one page. The wiki holds everything that would make the README scroll. Our README guide covers the first half.

Try Gollum Markdown in the Editor

The demo below mixes standard GFM with wiki tags. Everything in plain Markdown renders in the preview; the [[ ]] tags stay as brackets, which is exactly what a non-wiki renderer does with them, and _TOC_ even comes out italicised because a plain Markdown parser reads the underscores as emphasis. That makes our editor a quick way to check which parts of a page are portable before you commit it.

The limitation is obvious: no online editor can resolve [[Configuration]] to a page, because the page lives in your wiki repository. To preview the links themselves, run Gollum locally against the clone, as the next section shows.

How Do I Edit a GitHub Wiki Locally?

Every GitHub wiki is its own Git repository. GitHub Docs gives the clone URL form once the wiki has at least one page created on the site:

git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.wiki.git
cd YOUR-REPOSITORY.wiki

Then the workflow is the same as any repo. Create or edit .md files, commit, and push:

echo "# Configuration" > Configuration.md
git add Configuration.md
git commit -m "Add configuration page"
git push

The filename becomes the page title and the extension picks the renderer, so Configuration.md renders as Markdown and Configuration.textile as Textile. To see the wiki links resolve before you push, install the gem and serve the clone:

gem install gollum
gollum .

Gollum serves the wiki at http://localhost:4567, per the Gollum README. There, [[Page]] links resolve to real pages. We prefer this over the web editor for anything longer than a paragraph, because you get your own editor, search, and a diff before every commit. GitLab wikis clone the same way; their docs describe them as Git repositories you can edit like any other.

Which Gollum Tags Does GitHub.com Render?

This is the table nobody publishes. It combines the GitHub Docs statements above with the Gollum wiki and the GitLab wiki docs; where a platform's docs are silent, the cell says so.

Syntax	Self-hosted Gollum	GitHub.com wiki	GitLab wiki
[[Page]], [[Label|Page]]	Yes	Yes	Yes
[[image.png|frame]]	Yes	Use standard image syntax	Use standard image syntax
[[_TOC_]]	Yes	No (unsupported per GitHub Docs)	Yes, and [TOC]
[[include:Page]]	Yes	No	No
<<Note()>> and other macros	Yes	No	No
_Sidebar.md, _Footer.md	Yes	Yes	_sidebar page (lowercase)
Math and Mermaid	With the right renderer	Yes, per GitHub Docs	Yes
GitHub alerts (> [!NOTE])	No	Not documented for wikis	No

Two rows deserve a note. GitHub's editing docs say you can add rendered math expressions and diagrams to a wiki with Markdown. A Mermaid fence in a wiki page therefore renders like one in a README. And GitHub.com's docs describe the [[...]] form under MediaWiki syntax while pointing Markdown users at [Link Text](URL). The bracket form still works in Markdown pages, but it's undocumented there. That's one reason to keep a standard link as a fallback for anything important.

The renderer matters as much as the tags. Self-hosted Gollum with kramdown accepts kramdown extras such as definition lists and attribute lists, which GitHub.com's renderer prints as plain text. If a page has to render in both places, write it in GFM and use the bracket links only.

Three mistakes account for most broken wiki pages. Writing [[Getting started]] when the file is Getting-Started.md works, but [[getting-started]] fails on case-sensitive setups, so match the filename's case. Pasting a [[_TOC_]] from a GitLab wiki into a GitHub one produces a dead link. And naming a page with a slash to fake folders creates a file some operating systems can't check out; use a dash instead.

Gollum Markdown Wiki FAQ

Once you know which tags are shared and which are Gollum-only, gollum markdown stops being mysterious. Bracket links and the special pages work on GitHub, GitLab, and a local Gollum, while macros and includes need the gem. Draft the standard parts in the editor, then push from a clone so your wiki gets real commits and a real diff.