Browser extension that adds a navigation menu to any readme or Markdown file on GitHub.com
JavaScript CSS
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Markdown Menu for GitHub

Browser extension that adds a navigation menu to any readme or Markdown file on GitHub.

GitHub readmes and Markdown documents don't always include a table of contents. Well-documented repos have longer documents that can be difficult to navigate. This extension will automagically generate and add navigation menu with a table of contents.

Click on the three-bar icon at the top of any Markdown file to view the menu. Click on a link to scroll to that section of the document. That's it!

README example:

Markdown view example:

Install

Chrome WebStore

For Developers

You can also setup the dev version:

Supported Browsers

Current:

  • Chrome

Planned:

  • Firefox
  • Safari
  • Opera

I have experience developing Chrome extensions, so that was easiest to start with. I plan to add support for Firefox and then Safari and Opera.

Help, Issues and Support

Ask questions, post issues, and share suggestions using Waffle. Waffle is a kanban board backed by GitHub Issues. You can also tweet me @WillsLab.

Permissions

In Chrome, this extension requests the following permissions:

  • Read and change your data on github.com

This extension is scoped and enabled only when accessing https://github.com/\*. This extension looks for Markdown headers, generates a navigation menu and adds it to Markdown views on GitHub.

  • Read your browsing history

For this extension to work across page navigations within github.com, permissions are necessary to use chrome.webNavigation.onHistoryStateUpdated. This lets the extension hook into page navigations and trigger without full page refreshes.

More on Permissions

Over the years I've found that certain Chrome APIs required more permissions over time. I've also seen a lot of negative reviews for Chrome extensions wondering why more permissions are being requested. This is understandable; it certainly seems intrusive to ask for more permissions.

I've listed the specific reasons for each permission to explain why they are needed. Between that, and the full source code made available under the MIT license, I hope that alleviates any concerns.

Contribute

On-going development & open issues are tracked using Waffle: Stories in Ready

Let me know what you're hacking @WillsLab. I'll happily work with you to make your efforts successful!

Guidelines

  • in the chrome directory, run npm install
  • run grunt debug to run tests
  • setup EditorConfig in your preferred editor to maintain file consistency
  • make sure there are no JSHint warnings or errors

Dependencies

The Chrome extension was generated using Yeoman and the Chrome Extension generator. Grunt is used for building and packaging the extension. There are no runtime dependencies.

About

I work with several well-documented repos, with 500+ line READMEs. I'm thankful for the documentation, but it's hard to parse and find what I'm looking for. I built Markdown Menu to scratch this itch; I hope it might help others too.

License

MIT © Will Klein