update for markdown formatting

[ghwood]

This replaces some HTML formatting previously inserted for the benefit of the Wagtail CMS with markdown formatting, which is now supported by Wagtail.

Note: The second level ToC entry anchors work in Github but are not currently working in my tests in Wagtail, but I suggest that working in Github be the primary gate for markdown formatting at this point, with shims applied as needed to adapt to Wagtail functionality.

[nllz]

Hi Greg,

If we're completely switching to Markdown, should we not drop all numbering of sections and simply rely on automatic numbering of sections and subsections through the usage of #, ##, and ### ?
Using both numbering and # seems a bit redundant?

[larseggert]

You could use auto-generated anchors rather than <a> tags, which some Markdown flavors support. See for example https://raw.githubusercontent.com/ietf/id-guidelines/main/README.md.

[larseggert]

There are also still a bunch of other nits in the linter report (mostly overly long lines, etc.)

[ghwood]

Hi Greg,

If we're completely switching to Markdown, should we not drop all numbering of sections and simply rely on automatic numbering of sections and subsections through the usage of #, ##, and ### ? Using both numbering and # seems a bit redundant?

Automatic heading numbering would ideal, but I don't believe just using the #, ##, and ### markdown syntax also produces numbers. I would also be personally OK with just dropping numbering and using heading text for reference, but I believe some folks find the #.#.# heading labels useful for reference.

You could use auto-generated anchors rather than <a> tags, which some Markdown flavors support. See for example https://raw.githubusercontent.com/ietf/id-guidelines/main/README.md.

Unfortunately that feature isn't currently supported in the Wagtail CMS we're using for www.ietf.org.

There are also still a bunch of other nits in the linter report (mostly overly long lines, etc.)

I have fixed the nits in the linter report not related to line lengths. Is line length an issue that needs to be fixed in practice for this type of document?

I've submitted a new(?) PR with further updates.

[richsalz]

There are also still a bunch of other nits in the linter report (mostly overly long lines, etc.)

Looks like you're using the Ruby mdl program. Do you want to add suppressions such as for long line? Here's the one I wrote for OpenSSL, might be worth picking from it: https://github.com/openssl/openssl/blob/master/util/markdownlint.rb

[nllz]

Hi @ghwood - there are still some conflicts here that need to be resolved before I can merge this.

[richsalz]

A previous PR from @ghwood added the "#" (sub-)heading markings. After that, the only thing left in this PR is section numbering and anchors.

I suggest this PR be closed, and that we, er, Greg, look into what wagtail can do.

I'll be done with my content-related PR's within a week, and then we can fine-tune the markdown.

[ghwood]

Per the suggestion @richsalz I think this one is largely OBE so have closed.