BLACKBELT

Deployment Development

Authored by Corey Ballou

5 Comments

Adding a Table of Contents to your Github Wiki

Did you know that you can add a sidebar to your github wiki pages? Not only that, but you can also add a custom header and footer to your wiki pages. Github wiki pages are created via their own open source git-powered wiki, gollum. The gollum repository contains a detailed README with useful documentation which I’ll cover below.

Sidebar Files

Sidebar files allow for the addition of a simple sidebar to all of your wiki pages. They follow a naming convention of _Sidebar.ext where .ext is your preferred wiki format. Sidebar files affect all pages within a directory as well as any sub-directories not containing their own sidebar file.

How to Add a Sidebar

  1. Checkout your repository wiki via git. To find the URL, navigate to your wiki page in your browser and click the tab for Git Access.
  2. Now that you have pulled down a local copy of your github repo wiki, create a new file in the repo called _Sidebar.md
  3. Within the newly created _Sidebar.md file, you can add appropriate [[link]] markdown syntax.
  4. Add your new file to git via git add _Sidebar.md, commit via git commit _Sidebar.md -m "Adding new sidebar.", and push via git push origin master.

Header Files

Header files allow for the addition of a simple header to all of your wiki pages. They follow a naming convention of _Header.ext where .ext is your preferred wiki format. Header files affect all pages within a directory as well as any sub-directories not containing their own header file.

How to Add a Header

  1. Checkout your repository wiki via git. To find the URL, navigate to your wiki page in your browser and click the tab for Git Access.
  2. Now that you have pulled down a local copy of your github repo wiki, create a new file in the repo called _Header.md
  3. Within the newly created _Header.md file, you can add appropriate wiki syntax to your liking.
  4. Add your new file to git via git add _Header.md, commit via git commit _Header.md -m "Adding new header.", and push via git push origin master.

Footer Files

Footer files allow for the addition of a simple footer to all of your wiki pages. They follow a naming convention of _Footer.ext where .ext is your preferred wiki format. Footer files affect all pages within a directory as well as any sub-directories not containing their own header file.

How to Add a Footer

  1. Checkout your repository wiki via git. To find the URL, navigate to your wiki page in your browser and click the tab for Git Access.
  2. Now that you have pulled down a local copy of your github repo wiki, create a new file in the repo called _Footer.md
  3. Within the newly created _Footer.md file, you can add appropriate wiki syntax to your liking.
  4. Add your new file to git via git add _Header.md, commit via git commit _Footer.md -m "Adding new footer.", and push via git push origin master.

Additional Reading

For more gollum configuration options, settings, and details, I highly recommend you visit the repository.

Author: Corey Ballou

Corey is a seasoned PHP developer specializing in custom web applications development. He is an avid blogger, open source contributor, beer lover, homebrewer, entrepreneur, and Queen City PHP co-organizer. You can follow him on Twitter @cballou or visit his website coreyballou.co.

  • http://www.facebook.com/hanleybrand Peter Hanley

    But how do you add the Table of Contents? The gollum readme says to add [[TOC]] to the .md file, and while that works great locally, when I push the changes back to github I just get a [[TOC]] at the top of my files. Is there maybe a post-process command that can be triggered somehow?

    • Anonymous

      From what I can tell the TOC feature is specific to Gollum, which was the base of the GitHub wiki, but they have drifted substantially since then. Basically, that command doesn’t work.

  • http://blog.exolimpo.com Kuroir

    I developed GitHub Wikifier: A pre-commit Git Hook that will generate all the Table of Contents you will ever need. Just write your content, and let it take over. May be worth a check. https://github.com/kuroir/GitHub-Wikifier

  • Pingback: Checklist for moving a project from Google Code to Github « planetOzh

  • mthguy

    at no point did you explain how to add a table of contents… how would you do that. gollum is written by Github, yet they seem to not use a number of the runtime flags on their wiki. bummer. I would love to have a hands free TOC.