Generate table of contents for docs at http://doc.crates.io

[smaximov]

It would be nice to have TOCs for documentation articles. TOC gives a summary of topics an article addresses and allows to quickly navigate between sections.

How it can be implemented

• Place some marker (e.g. %TOC%) in a Mardown file:

  % Cargo Guide
  
  Welcome to the Cargo guide. This guide will give you all that you need to know
  about how to use Cargo to develop Rust projects.
  
  %TOC%
  
  # Why Cargo exists
  ...

• Use some tool (first hit in google, actually works) to generate TOC.

• Replace the marker with the generated TOC.

Mockups

Simple TOC:

Fixed ("sticky") sidebar TOC:

[alexcrichton]

cc @steveklabnik, @carols10cents

[steveklabnik]

I like this idea a lot. I think I like the second version better.

[carols10cents]

YES love it!! Just to be clear, in the 2nd mockup, the TOC would be position: fixed or position: sticky and remain visible as you scroll, correct? That would be awesome.

[smaximov]

Just to be clear, in the 2nd mockup, the TOC would be position: fixedor position: sticky and remain visible as you scroll, correct?

Yes, that's exactly what I meant (position: fixed, to be precise). I believe it will be much more usable that way than with just absolute positioning.

[istankovic]

When it comes to cargo docs, I'd vote for this to have the highest priority. The current cargo docs layout has serious usability issues and having a TOC would help a lot. In fact, I'd much rather see cargo docs mimic https://doc.rust-lang.org/book, which makes it much easier (still not ideal, but definitely miles ahead compared to what we have here) to get around and get to the necessary bits.

[carols10cents]

In fact, I'd much rather see cargo docs mimic https://doc.rust-lang.org/book

Good news! That's exactly the plan, it's just that there's only so much time and not very many people contributing towards this goal at the moment.

[istankovic]

That is indeed good news, thanks for the info.

[carols10cents]

Related: #4040

[dwijnand]

This think this can be closed now. The cargo docs now use mdbook, and thus have a sidebar TOC.

[alexcrichton]

Indeed!