toc for longer articles/guides

[wikimatze]

It's hard to navigate long pages, so I created a branch for it: https://github.com/padrino/padrino-web-new/tree/toc.

@angeloashmore I'm not sure how the styling and collapse works. Would be nice that you can say, it will work or not. The plugin used for this is called https://github.com/atarukodaka/middleman-page-toc

[angeloashmore]

I'll take a look at this tomorrow. I agree, the guide pages are quite long and can be hard to navigate.

Ideally the TOC floats while scrolling so it is always available on the side. There will need to be some kind of balance between the guide links and the TOC.

[wikimatze]

Perfect, something like position fixed would be fine in my eyes. Take your time and would love to see your results.

[angeloashmore]

Sorry it took me so long to work on this.

I made some quick changes to the CSS and JavaScript and came up with this: padrino-web-new/tree/fixed-sidebar. It basically changes the sidebar element to position: fixed when it gets to a certain scroll position.

There are a couple of issues with this approach:

• Scroll threshold is a static px value that does not take into account different responsive layout sizes (e.g. mobile, tablet).
• Changing the sidebar, or the sidebar's parent (.page__sidebar), to fixed causes layout width issues; position: fixed does not reference the parent's dimensions. You should see the sidebar overlap the content on smaller window widths.
• Setting scroll: auto allows the sidebar to scroll when needed, but my browser (Safari, OS X) was having difficulty determining whether to scroll the page or the sidebar, even when hovering the sidebar. Not sure why.

Alternative solution

Rather than discussing issues with the proposed solution, let's discuss problems with the current implementation.

1. Guides are very long with many sections.
2. Content width is somewhat narrow, especially for the font size.
3. Guides are listed all together rather than by type or logical progression.

These are fairly easy problems to solve:

1. Separate guides into smaller sub-guides. Content would be the same, but broken into multiple pages. See Lotus's docs for an example.
2. Increase overall maximum page width. Since the CSS is set using Susy and percentages, everything should scale nicely automatically.
3. Add sub-headers to the guides and break them into logical categories. Again, see Lotus's docs for an example.

These structural solutions should, in theory, make a TOC unnecessary. I feel this is a better solution, but I'd like to hear others' opinions.

[angeloashmore]

Implemented split docs. See at http://padrinorb.com/guides/.

[nesquena]

Looks great!

[wikimatze]

Perfect, looks very nice, reminds me a little bit of the old implementation.