ToC or Sidebar in GitHub Wiki
GithubWikiGithub Flavored-MarkdownGithub Problem Overview
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. "
Github Solutions
Solution 1 - Github
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.
Solution 2 - Github
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
Solution 3 - Github
Okay. Let me see if I understand this correctly:
- Clone your GitHub wiki. (There’s a Git section in the wiki. You can checkout your wiki-like code.)
- Create
_Sidebar.md
- In normal wiki pages, use
[[link]]
for the sidebar - 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.
Solution 4 - Github
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?).
Solution 5 - Github
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.
Solution 6 - Github
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.
Solution 7 - Github
GitHub will auto-generate a document table of contents:
- Make the doc type AsciiDoc instead of Markdown.
- Insert
:toc:
at the start of the document.