search

elastic / docs

21 stars 333 forks source link

Add support for categories in the TOC #1284

Open bmorelli25 opened 5 years ago

bmorelli25 commented 5 years ago

This feature request came up in a conversation with @gchaps, @DonNateR, @lcawl, and @nik9000. Please feel free to edit this issue if I missed anything.

The Problem

Nested content is hidden, which can make it more difficult to find. This problem was brought to light when Machine learning docs were nested under the Extend your use case heading:

Screen Shot 2019-10-10 at 12 04 01 PM

Data point: When I created that ^ screenshot, it took me four guesses to figure out which tab the ML content was nested under.

The solution

Allow TOC "categories". The categories could be used to break up the doc nav, without hiding important content.

Here's an example. The categories are: Get started, Explore, analyze, visualize, and Share and collaborate. Indented headings are links to content:

Get started
   Get data into Kibana
   Tutorials to get you up and running
Explore, analyze, visualize
    Discover
    Visualize
    Dashboard
    Graph
    Machine learning
Share and collaborate
    Spaces

A quick mockup as to what this might look like:

Screen Shot 2019-10-10 at 12 19 58 PM

Short-term

A short-term fix has been outlined in https://github.com/elastic/docs/issues/1286

gtback commented 4 years ago

I don't think this is something we'll do before the re-design.

I'd be interested in suggestions on how to annotate this in the Asciidoc so that this information can be automatically determined. Unless we just want to automatically (maybe via a per-book configuration section) make the first level TOC entries "categories".