Add "Table of Content" to the Readme tab

[jayoung-lee]

In a recent user study, participants searched within a package's documentation to find a specific feature (e.g., Ctrl+F to search “highlight” within the documentation of “markdown” package). They usually did this when they failed to find useful information after quickly scanning the documentation. They also tried multiple keywords to make sure that they didn't miss any information (e.g., “highlight”, “syntax”, “code”). It showed that search was an easy way to find information from large data, but it could be difficult to find a good keyword.

But when the feature of interest was listed under “Features” section, users didn’t have to search again. It suggests that a standardized Readme format with better navigation UI (e.g., table of contents) might save some time for participants.

We can consider adding table of contents that's similar to the one on Go's package site:

[sigurdm]

We probably want this in a side-bar.

On mobile this could be omitted or dragged in from the side.

[sigurdm]

Github does this as a drop-down menu: We could consider something similar

[wrbl606]

Before it gets (hopefully) implemented into pub itself, here's a Firefox extension that achieves the same thing.