Making Table of Contents for GitHub
Reflecting on the Table of Contents for GitHub browser extension.
Even though it was a tiny project, I thought I’d take the time to reflect a bit on making Table of Contents for GitHub while it’s still fresh in my mind. I’ve got to use this blog for something right?
What and Why
In short, I made a browser extension that adds a table of contents to GitHub readmes, wikis, gists and basically any other structured text file on GitHub. As readmes and documentation grow bigger it is supposed to help you quickly find the information you are looking for. I found myself skimming and scrolling all over readmes and wikis when I decided I want this to happen.
You can read more about it in this previous post.
Of course, there’s already some stuff out there.
Most related projects solve the “GitHub table of contents problem” by requiring project maintainers to hard-code tables of contents right into the source files, either manually or semi-automatically. Usually this is done by adding special markup to the file that, in a separate step, is rendered into a table of contents.
This has several drawbacks:
- It requires work: from project maintainers.
- It is not automatic: It requires a separate step to build the table of contents. And it needs to be kept up to date with changes.
- Nobody does it: Well, almost. For you as a user this means that you don’t get to enjoy a table of contents for the vast majority of projects.
- Individual files only: Each file that should have a table of contents needs to be marked as such. But there are many other places on GitHub where a table would be desirable, such as wikis, gists and basically any other text file.
This project has a different premise: Instead of putting the onus on project maintainers, it’s a browser extension that is installed by the user. It lives inside the GitHub website and is fully automatic. Whenever you land on structured text such as a readme, boom there’s your table of contents.
I had a few requirements for what to build. A solution should:
- be a browser extension.
- generate a table of contents fully automatically and require no work.
- provide the table not only for readmes, but for wikis, gists and any text file.
- be simple, easy to use and visually unobtrusive.
- be readily available for most browsers.
I started with making a Google Chrome extension first since Chrome offers the most straightforward and best documented extension API.
Whenever GitHub’s HTML/CSS changes we need to adapt. This is the nature of living inside the website. This has happened a few times already.
The code assumes there is only ever one table of contents on the page. Makes sense: There is only ever one readme, one text file, one wiki displayed at a time. However, I have had users requesting I add a table of contents to any structured text on GitHub, including comments on issues and pull requests. To do that there would have to be a table of contents for each comment on a page of which there can be many. This requires a bit of restructuring. At this point I’m not sure if this exceeds the scope of the project.
There are any number of things that can be changed and added to the project. For one, I would like a search feature that would allow you to filter the table of contents.
Finally, I plan to rework the code so as to lift the restriction of only one table of contents per page.
In the near future though, I don’t have too much time to dedicate to the project. For now, I’m pleased with it and will keep it mostly in maintenance mode.
What I Learned
Again, this was a really small and simple project. Still, I learned a bunch:
- Dipping my toes into JS tooling, specifically npm and gulp.
- Building a product for different targets (browsers).
- Limiting the scope of a project.
- Publishing extensions to Chrome Web Store and Mozilla Add-ons.
- Dealing with feedback and interacting with users.