Replace html font tags with HTML headings

[CouldBeThis]

Ran markdownlint on install.md; it is complaining about "MD024/no-duplicate-heading"
However the headings have intentionally been created in a consistent manner
therefor I ignore this.

[MichaIng]

Please see https://github.com/MichaIng/DietPi-Docs/blob/master/.markdownlint.yml#L6-L7 about which markdownlint rules we intentionally ignore or adjust.

Actually, the issue of doubled/numbered element IDs and page anchors to hidden elements is the reason why we switched from headings to font size tags in tabs. In this particular example:

• Introduction exists already in the first Raspberry Pi tab, being a heading there.
• Making it a heading as well in all tabs, means that the page anchor is changed from https://dietpi.com/docs/install/#introduction to https://dietpi.com/docs/install/#introduction_1 + https://dietpi.com/docs/install/#introduction_2 etc, since ID duplicates must not be, which does not look beautiful anymore.
• Furthermore using https://dietpi.com/docs/install/#introduction-2 will scroll somewhere into the opened Raspberry Pi install tab, while it is aimed to point to the VirtualBox install tab, which is hidden, confusing user of this link.

Actually these issues are the reason why MD024 makes perfectly sense, as long as headings are automatically given an element ID (and anchor/link). Since using same child headings below different parent headings is not uncommon, as otherwise you'd need to somehow hack individual key words from the parent heading to the child heading, (see the example with change logs https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md024), the best solution would be to disable element IDs on hidden or doubled headings.

The IDs + links are set by the TOC extension: https://github.com/MichaIng/DietPi-Docs/blob/master/mkdocs.yml#L36-L37
Documentation: https://python-markdown.github.io/extensions/toc/

• A custom ID and TOC label can be set by adding: {: #custom_id data-toc-label="custom_label" }
  This can be used to have non-overlapping IDs while preserving same headings text e.g. in changelog or software docs.
• What I still could not find is a way to exclude a single heading form being processed by the TOC extension or probably a general syntax to disable a Markdown extension for a specific element. That would be required for this PR, to avoid IDs for hidden headings.

---

@StephanStS @fpetru
Linking you here, as probably you have some ideas. I personally never liked the font tag styles in hidden tabs, especially since they look different than actual headers. But more important IMO is to not have links or IDs to hidden elements. The custom IDs solve at least half of the issue, as we could use #introduction-rpi, #introduction-virtualbox, #changes-v7.0, #changes-v7.1 as custom IDs to avoid that _1 _2 numbering.

Before the idea comes up again: Automatically opening tabs when a link refers to an element inside of it is not possible with the currently used extension and not a plan, as it would require extended JavaScript use, which goes beyond of what Markdown extensions are designed for (Markdown => HTML translation). I discussed that with facelessuser already.

[CouldBeThis]

hmmm interesting. I thought probably someone had used some kind of wysiwyg editor along the way. thank you for taking the time to explain to me.

I can't tell if it's because something changed elsewhere in the source but now when I go to the branch where I was working on this it does not display correctly at all, the tabs are weird.

What I was going to do was see if the nonpretty anchors would link properly into the tabs. Because that would be useful to know about if yes. However instead it links to totally the wrong place; probably the whole thing is broken.. so I will have to maybe redo some changes on a fresh branch.

How are these URLs being displayed to the user or to anyone else? It seems to me the only way anyone would see the nonpretty URL would be because they had some utility for it no?

especially since they look different than actual headers

I'm sure that could be addressed with careful CSS. Or instead of using <font> use regular html <h2> (probably wouldn't work). Or create a special `

. Or some other solution; whatever it is, everybody needs to know about how to use it properly. Because there is no way to deduce this from looking at the yml file (which I did do).

[MichaIng]

What I was going to do was see if the nonpretty anchors would link properly into the tabs.

That is not possible, as mentioned above, hence the wrong page scroll you face.

use regular html <h2>

👍 That is so obvious, I wonder why I never through about that instead of manually trying to get headings style 😄. I hope that MkDocs only converts Markdown headings into links and not HTML headings. @StephanStS did you try that?

How are these URLs being displayed to the user or to anyone else? It seems to me the only way anyone would see the nonpretty URL would be because they had some utility for it no?

What do you mean? When hovering a heading, the link appears, clicking on it scrolls to the header and adjusts the browser address bar accordingly. Copy&pasting that somewhere for reference, then other users clock on it and land on a wrong place of the page, as the original user had another tab open than the default one 😉. So for now there must be no heading links inside of subsequent tabs, but only on the first tab that is visible when accessing the page.

[MichaIng]

Let's get this further: While we cannot assign IDs for headings behind tabs, there are two options:

1. Make them headings, but assure that no ID and link is generated. Try to assign an empty ID: {: # } or {: id="" }
   🈴 Both does not work. The ID will be set as empty and the link still created, but invalid as it only points to the page start.
   Setting data-toc-label='' removes the heading from the TOC, but does not remove the permalink.
   Since there is no way to automatically inherit a style from an element or another class in CSS, we need to go with option 2.
2. If that doesn't work, create an h2 class with styles from h2 elements and assign it to headings behind tabs: {: .h2 }
   The problem with this is that we need to manually keep this class updated, aligned with the MkDocs material theme's h2 element style.

[MichaIng]

I'm sorry for this taking ages, but it was really that simple: Using HTML h2/h3 tags in Markdown assures that the style is the same but the headings element ID and link are omitted, just as we want it. Applied the changes to other cases where we used the font tag. Made a test build, looks and works all fine, ready from my end.