Add table of contents to the integrations pages

[axilleas]

Proposed change

This use the https://github.com/toshimaru/jekyll-toc gem to add
a table of contents (ToC) in the integration pages
for quick content scanning. The ToC is enabled by default for all
integrations pages. If you need to disable it, no_toc: true needs to be
added in the YAML frontmatter.

Here's how it looks. It's pretty barebones, but we can change the CSS if needed.

Type of change

Jekyll related.

Checklist

• This PR uses the correct branch, based on one of the following:
  • I made a change to the existing documentation and used the current branch.
  • I made a change that is related to an upcoming version of Home Assistant and used the next branch.
• The documentation follows the Home Assistant documentation standards.

[probot-home-assistant]

It seems that this PR is targeted against an incorrect branch. Documentation updates which apply to our current stable release should target the current branch. Please change the target branch of this PR to current and rebase if needed. If this is documentation for a new feature, please add a link to that PR in your description.
_{^{(message by DocsTargetBranch)}}

[frenck]

In general, I like the idea. However, with longer titles, it becomes really messy in the sidebar really quickly.

Also I think implementing this for just one specific integration, doesn't make sense?

[axilleas]

In general, I like the idea. However, with longer titles, it becomes really messy in the sidebar really quickly.

@frenck Yeah, you're right, but we can maybe fix this with some CSS. Also, I think the benefits outweigh this stylistic issue :)

Also I think implementing this for just one specific integration, doesn't make sense?

Yep, we'll need to add this to all integrations. As I wrote in the PR description:

This PR enables the ToC to the ZHA integration page as an example. If you
accept it, I can work on adding the entries to the rest of the integrations and
also send a follow-up PR describing this new addition in
https://github.com/home-assistant/developers.home-assistant/blob/master/docs/documenting/create-page.md.

[frenck]

That is not how we should enable it for all integrations... set it as a default in the Jekyll configuration.

[frenck]

yeah so let's see what we can do about styling:

It can be more compact, e.g., the indenting space between list levels can be reduced a lot to make it work in more cases I guess?

Also the first level can be moved more to the left as well, to align with the text above it.

[axilleas]

That is not how we should enable it for all integrations... set it as a default in the Jekyll configuration.

I'll need to figure how to do that. I'll get back to you if I find something.

[frenck]

I think we can add it to all pages: https://github.com/home-assistant/home-assistant.io/blob/next/_config.yml#L115

We should however add the TOC to other asides as well in that case.

[axilleas]

I think we can add it to all pages: https://github.com/home-assistant/home-assistant.io/blob/next/_config.yml#L115

I actually tried that but it didn't work. There's a limitation of this plugin, and it only works with posts https://github.com/toshimaru/jekyll-toc#2-advanced-usage.

I'll keep digging.

[frenck]

Well, it states it works on collections, since most stuff is a collection in our setup, it should work on almost everything.

[axilleas]

Well, it states it works on collections, since most stuff is a collection in our setup, it should work on almost everything.

@frenck you're right, not sure why this is not working 🤔 I submitted an issue with a question upstream toshimaru/jekyll-toc#116.

[frenck]

Sorry for the late response, all the styling can be found in the sass folder in the root of the project.

[zsarnett]

I feel like the TOC should only be like 2-3 levels. This would reduce the indent and crazy styling as well. We shouldn't need to get that granular

[axilleas]

👋 I'll get back to the PR soon!

[axilleas]

@zsarnett I got the max level to be 3.

@frenck I tried a few CSS files from the sass dir, but I couldn't find the correct one it seems. Not sure where to look.

[Gamester17]

Any progress on this?

[frenck]

@Gamester17 As you can see, it is not. Why you ask?

[axilleas]

Yeah, don't know much about frontend, sorry...

[zsarnett]

@axilleas just add your css to the _paulus.scss file

[axilleas]

@axilleas just add your css to the _paulus.scss file

Ah, I'll try that, thanks!

[axilleas]

@zsarnett thanks to your pointer, I was able to make this work!

@frenck can you give this another look?

[frenck]

Adjust styling a tiny bit.

I think a good extension on this, would be making the nav sticky (if you scroll down, it is still available). However, could not get that to work.

I think this is a good first step and ready to rock.

Thanks, @axilleas 👍

[axilleas]

I think a good extension on this, would be making the nav sticky (if you scroll down, it is still available). However, could not get that to work.

@frenck agreed! Thanks for merging 🚀