97

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:

Improve this question
3

8 Answers 8

Reset to default
79

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.

Improve this answer
Sign up to request clarification or add additional context in comments.

10 Comments

@CodeSherpa they are accessible at https://github.com/[user]/[repo]/wiki/_Sidebar/_edit and https://github.com/[user]/[repo]/wiki/_Footer/_edit
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.
These detailed instructions are pretty poor. What is a [[link]]? Putting a URL in there results in the whole URL showing up.
@Pithikos it's Github Markdown speak. The instructions aren't there to teach you Markdown. They are there to explain sidebars.
@nicerobot and the best way to explain something is by using a concrete example..
|
31

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

Enter image description here

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
Improve this answer

1 Comment

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

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.

Improve this answer

2 Comments

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
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.
10

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?).

Improve this answer

5 Comments

Have you had any luck? This is terribly frustrating having come from Trac where all of these things were easily done.
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.
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 :(
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
GitHub will create a TOC for AsciiDoc wiki pages. github.com/dogweather/github-wiki-toc-demo/wiki
4

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.

Improve this answer

Comments

3

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):

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.

Improve this answer

Comments

1

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]
====

enter image description here

Improve this answer

1 Comment

as the example illustrates, link:./my-file[my title] also works with .md files so while the _Sidebar is asciidoc, everything can still be markdown
-3

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:

enter image description here

Improve this answer

2 Comments

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

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.