Automatic TOC doesn't pick up h3 headings and other issues

[tmihoc]

In the absence of automatic TOCs for juju.is docs, I implemented manual TOCs following a pattern where I have h2 and h3 level headings and a TOC listing h2 headings right beneath the intro para to the doc and mini-TOCs listing h3 headings underneath the intro para of each h2 section that had them. The way I implemented the TOCs made sure that each heading was surfaced in some TOC and also that, by clicking on a heading, people could get a link to it. For example, https://juju.is/docs/juju/manage-clouds , https://juju.is/docs/juju/manage-clouds#heading--add-a-cloud , https://juju.is/docs/juju/manage-clouds#heading--add-a-kubernetes-cloud . Screenshot showing the same:

In light of the recent PR that enabled automatic TOCs for juju.is docs (canonical/juju.is#510 (comment)), I started converting my manually formatted headings to plain Markdown so they could be picked up automatically, but then noticed that:

(Issue 1) h3 headings were not picked up in the automatic TOC (e.g., Add a machine cloud and Add a Kubernetes cloud do not show up in the automatic TOC)
(Issue 2, which makes Issue 1 worse) the only way to get a link to a section was by clicking on it in the TOC

The result is worse than what I had before, so I won't keep it, but you can view it by reverting to revision 58 of the Discourse version of the doc https://discourse.charmhub.io/t/how-to-manage-clouds/1100 . Here is also a screenshot:

I reported the issue on the automatic TOCs PR, but was told the issue was likely with the Discourse module, and that I should file an issue here (canonical/juju.is#510 (comment))

To be clear: I think both Issue 1 and Issue 2 should be addressed, but Issue 1 is a priority -- I will not convert my heading formatting to fit with the automatic TOCs setup until this issue is addressed.

Since I've already put up the screenshots, let me mention another difference that imo negatively affects UX:

(Issue 3) As I've mentioned and as can also been seen in the first screenshot, my manual implementation had in-line TOCs beneath the intro para at every level. The logic there was as follows: Suppose I want to add a cloud. The intro para tells me how to do that depends on whether the cloud is a machine cloud or a Kubernetes cloud. Suppose my cloud is Kubernetes. Then I can just click there and skip ahead. Now, with the automatic TOC we can only access the TOC on the right-hand side of the page. So, running through the same scenario, once I've read the intro para and decided I want to skip to the Kubernetes section, I need to move my attention to the right and find it in the right-hand side TOC before I can jump there.

[ru-fu]

(Issue 2, which makes Issue 1 worse) the only way to get a link to a section was by clicking on it in the TOC

All headings actually have an anchor, so it is possible to link to them.
To get the link, you need to check the source code of the page and find the corresponding anchor. This is of course not very user-friendly and the task for adding a copy icon to the headings is scheduled for the next pulse, but it's not a blocker since it IS possible to link at the moment.

[tmihoc]

Issue 4: On pages with tabbed content, the automatic TOC shows for all tabs. E.g., this TOC was created from the terraform tab but shows up on the juju tab as well.

Switching to manual formatting for now, but you can preview it by switching to revision 64 of the Discourse doc. https://discourse.charmhub.io/t/how-to-manage-models/1155

(Incidentally, also noticed another issue. In https://juju.is/docs/juju/manage-models#heading--terraform-migrate-a-model-to-another-controller, the juju CLI | How to migrate a workload model to another controller link is supposed to link to a section in the juju tab, but when you click on it nothing happens (although in the Discourse doc it correctly helps you jump to that section).