Migrate # -> ## in doc headers.

[steveklabnik]

I busted out some git grep | xargs sed and fixed this. I've reviewed the diff, and it should be good. Please double check me, though!

Fixes #15499

[lilyball]

I think it's better to tweak the Rustdoc CSS to make <h1> look however we want, then to try and use ## everywhere. It's odd to use ## if we never use #. Also I think /// # Examples looks better when reading the comments than /// ## Examples.

[chris-morgan]

We should be at liberty to declare that here, # is h2, ## h3, &c. I know that you can do the equivalent in reStructuredText (just specify the starting level for headings), and I will declare that you should be able to do the same with Markdown (whether you can or not).

[brson]

If this is just changing all headers in rustdocs to '##', leaving no '#', then I prefer to change rustdoc to make this work as expected. Old rustdoc actually silently converted '#' to '##' before translating to markdown if I recall.

[steveklabnik]

I'm not a fan of changing Markdown's semantics just because.

[steveklabnik]

Also, these are never top-level headers. They're secondary headers. It doesn't make sense to mark up secondary headings as primary headings and then render them as secondary headings.

[brson]

@steveklabnik The reasoning for using # there is that in the local context of the item documentation, it is the only header level. The way the docs are structured locally doesn't determine the final rendering which could put those headings at any level (i.e. whose to say that these headings should always be level 2 headings in the output. one version of rustdoc at least had multiple output modes that put these headers at different levels).

[steveklabnik]

Gotcha. Then we're not really doing markdown, we're doing our own kinda-markdown format. Which is a decision we can make, but it should be made explicitly.

[lilyball]

Well, we already are using a bunch of markdown extensions (appears to be equivalent to GitHub-flavored Markdown + superscripts), so we've already diverged from straight markdown anyway.

[steveklabnik]

Extensions are one thing, and GH flavored markdown is basically markdown, since Gruber's governance of markdown is terrible. Changing the way headings work is a pretty significant divergence.

[Gankra]

Longterm, do we plan to stick to Hoedown, or would we like to migrate to a pure Rust solution for markdown handling? Hoedown doesn't strike me as particularly configurable outside of the ~10 flags they offer (hardcoded special characters as inline string literals is a notable pattern in their source). Maybe they offer some nice plugin utilities, but their documentation is very weak.

And of course C-bindings are always a higher security risk that native Rust.

[steveklabnik]

This PR is super out of date, so I'm just going to close it.