ToC or Sidebar in GitHub Wiki

Question

How do I create a ToC or a sidebar menu in a GitHub Wiki?

I saw some mentions of it and gollum the backend seems to support it, but how do I do it in a current GitHub project?

It should best be based on the headers I have in the page automatically.

These links all mention it, but do not show how to do it:

• https://gist.github.com/379469 - some JavaScript hack

• https://github.com/blog/774-git-powered-wikis-improved - GitHub mentioning it:

  "GitHub Wikis have a little-documented ability for footers and sidebars, something which some of our git-based Wiki authors are familiar with. The new Wiki editor gives you limited web-based editing of the footers and sidebars you have on your site. "

Basilica

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. github.com/kuroir/GitHub-Wikifier – Informality

On Isaacs: github.com/isaacs/github/issues/504 – Vitrescent

@Informality 's code moved to github.com/hybridgroup/GitHub-Wikifier – Mouthful

Answer 1

Okay. Let me see if I understand this correctly:

1. Clone your GitHub wiki. (There’s a Git section in the wiki. You can checkout your wiki-like code.)
2. Create _Sidebar.md
3. In normal wiki pages, use [[link]] for the sidebar
4. Commit and push back to GitHub

This process is a pain in the ass. I’m surprised this “gollum” wiki has any acceptance.

Also: _Sidebar.md is therefore global for all pages. I would have to organize my wiki into folders, so I can define different sidebars for different pages.

Basilica

According to the docs, you can add different sidebars for different folders: "Sidebars affect all pages in their directory and any subdirectories that do not have a sidebar file of their own." see: github.com/github/gollum – Lydon

Re: "According to the docs, you can add different sidebars for different folders." Has anyone been able to get that to work reliably? I find that in doing this you forgo the ability to edit the sidebars via the UI. Which specific sidebar you end up editing seems flaky and unreliable. I could live without the UI for editing (git/edit directly). However, then I find that it does not work reliably. Sometimes a subfolder's sidebar is used/displayed but sometimes the root sidebar "bleeds through." Just doesn't seem to work right. – Flare

Answer 2

While your solution works, there's an easier way to do it using GitHub's web interface. You can simply create a page named _Sidebar and/or _Footer.

See detailed instructions in Github Wiki sidebar menu builder with multi-level.

Edit The original article is gone and I can't find it in the cache so I've updated the link.

Aspectual

I followed this post a few months back. Works well. But, now I want to remove the sidebar and can't figure it out. Any equally brilliant suggestions? – Tillotson

@CodeSherpa they are accessible at https://github.com/[user]/[repo]/wiki/_Sidebar/_edit and https://github.com/[user]/[repo]/wiki/_Footer/_edit – Aspectual

@HerbCaudill The link was fine. The site was apparently down for a short time. – Aspectual

The article was great but gives incorrect (or out of date) information about how to get the URL of the wiki. In case you are as lost as I was, you have to use the URL https://github.com/<username>/<projectname>.wiki.git or SSH [email protected]:<username>/<projectname>.wiki.git. – Jonme

@Jonme Notice the third comment above, mine, that mentions the structure of the wiki URL. – Aspectual

Yes, but absolutely useless if you need to organize the sidebars into directories because you happen to have more than one group of pages. For that, you need to check out the repo, the GUI simply isn't capable. – Jonme

These detailed instructions are pretty poor. What is a [[link]]? Putting a URL in there results in the whole URL showing up. – Torso

@Torso it's Github Markdown speak. The instructions aren't there to teach you Markdown. They are there to explain sidebars. – Aspectual

@Aspectual and the best way to explain something is by using a concrete example.. – Torso

@pithikos if I had written them instead if just linking to someone's, I might have done it differently. You might want to complain to the author of the linked article in its comments section instead of here. There's nothing I can do about it. I simply provided one possible solution to the question posted. – Aspectual

Answer 3

When you are in the wiki of your project, there is a link Add a custom sidebar. Click that.

Now you have a page that you edit as you would edit any other Markdown page. To make a table of contents you have to do it manually though. There is no automated method (as of August 2014). So for example:

# My menu
* [Home][home]
* [Technical documentation][techdocs]
* [User manual][usermanual]

[home]: https://github.com/myproject/wiki/Home
[techdocs]: https://github.com/myproject/wiki/Technical-documentation
[usermanual]: https://github.com/myproject/wiki/User-manual

Torso

This is not available anymore, at least in the non-enterprise editions – Biotic

Answer 4

Note that the original question was about creating a side bar (easy, solved in the answers) or an actual table of contents (not answered).

One thing I can say is that the gollum 2.1 wiki syntax allows for a [[_TOC_]] tag, but a GitHub wiki won't recognise that (yet?).

Skilled

Have you had any luck? This is terribly frustrating having come from Trac where all of these things were easily done. – Magritte

I think that a better answer to the the original question on how to make a table of contents "based on the headers I have in the page automatically" is that is currently impossible with GitHub Wiki. – Upshaw

This is currently an open issue (too lazy to look up the number) that hundreds of people have commented on. No word back from GitHub yet :( – Sansone

The main GitHub issues that reference this as of 2017-01-19 are: 1. Markdown - Table of Contents 2. Insert automatically generated table of contents TOC on rendered markdown files like README.md – Heres

GitHub will create a TOC for AsciiDoc wiki pages. github.com/dogweather/github-wiki-toc-demo/wiki – Templia

Answer 5

I think this is described in the Gollum README. (See the header and sidebar sections.)

Essentially, you make a _footer.ext and _sidebar.ext in the directory containing the page content.

Hectometer

Answer 6

I have implemented the npm module github-wiki-sidebar to help github users to easily create and maintain the sidebar menu.

Source and Result: https://raw.githubusercontent.com/wiki/adriantanasa/github-wiki-sidebar/images/github-wiki-sidebar-generator.png

Source pages (as displayed in Wiki admin):

Home
Installation
Roadmap
Usage
Usage: Command line modifiers
Usage: Init Mode

Result (with customised order):

• Home
• Installation
• Usage
  • Init mode
  • Command line modifiers
• Roadmap

Pre-requirements:

• clone your github wiki repository locally (displayed on the bottom-right of the Wiki UI)

• install the github-wiki-sidebar

  git clone <https://github.com/<username>/<my-project-name>.wiki.git
  npm install -g github-wiki-sidebar
  

Create/update your wiki menu:

• create new pages / rename pages on your github.com wiki admin

• execute locally the github-wiki-sidebar script in your wiki repository folder

  cd /path/to/<my-project-name>.wiki
  # this fetches latest changes, generates sidebar file (_Sidebar.md) and pushes changes to github
  github-wiki-sidebar --git-push
  

The module allows customisation of the markdown output including ordering of items, the category separator, the template for the menu, the format of links and others.

Makeup

Answer 7

If you'd like to use expandable menus (aka. Dropdown Menus), then go for _Sidebar.asciidoc, and use the AsciiDoc markup syntax [%collapsible].

You can still refer to plain Markdown in the links :)
Remember to omit the suffix in the relative links as GitHub has it's own way to resolve what page to use.

Also GitHub Wikis seems to use a flat name space when parsing non wiki links. Although you might be using folders for your files, the path doesn't seem to count.

.Main 1
[%collapsible]
====
. link:./subitem1[Subitem 1]
. link:./subitem2[Subitem 2]
====
.Main 2
[%collapsible]
====
. link:./subitem3[Subitem 3]
. link:./subitem4[Subitem 4]
====

Conflux

Answer 8

GitHub will auto-generate a document table of contents in AsciiDoc pages but not Markdown. It's easy to do, though. Also easy to convert Markdown to AsciiDoc — they're very similar.

1. Make the doc type AsciiDoc instead of Markdown.
2. Insert :toc: at the start of the document.

I made a demo repo demonstrating an auto-generated TOC embedded in a Wiki page, not the sidebar. Here's the result:

Templia

this does not work. – Malathion

@StevenDake I made this demo repo demonstrating how to do it: github.com/dogweather/github-wiki-toc-demo/wiki – Templia