Define doc hierarchy about docs HOT 2 CLOSED

This is a really good topic, with a few points I had not considered.

First, using markdown in titles could make them form bad URLs but generally the slugger handles it well (by dropping punctuation and hyphenating everything)

# Using the `env` param
content, description

# This & that
info about this

env is rendered as code in the title in the doc, and the URL simply drops the ticks. (.../filename#using-the-env-param) which is readable, but a bit verbose. A worse example is (.../filename#this--that) where the ampersand is dropped but spacing is weird. Is there a way to explicitly define the slug for a header link? This could possibly solve a lot of issues.

Second, regarding the file/folder structure and naming conventions: This would be most robust with a super old-school planning phase of assessing every doc topic that needs to be written, categorizing them, etc... but that doesn't gel with how this project is running. So some kind of convention or guide would be good, but still leaves us with problems if an earlier made decision turns out to not be what we wanted. Lets say we put recommended-products.md in /Specifications/ as it is here, and add some more specs type docs to it. Later we may have a lot more hardware docs, and want a /Hardware/ (at the same level as, or even within /Specifications/). That's... bad.

I can see a convention/guide helping with breadth of topics, depth of structure, naming of folders, etc. But I can't think of good resolutions to the above issue & am not crash hot on versioning unless absolutely necessary.

from docs.

Regarding anchor generation and ID overrides - not in the current renderer. There does appear to be an existing convention in the wild for this: # A very long heading {#custom-id}.

This will partially break things for links that are followed directly on GitHub, however given it will still land a viewer on the correct doc (just not the correct section), and provide a significantly cleaner experience for the rendered site I think this is a pretty valid trade off.

from docs.