Doc: Fix list and nested list rendering issues in spec webpages + other Markdown format cleanup

[bact]

Background

Apart from minor incompatibility in Markdown-flavours, GitHub Markdown rendering engine tends to be more robust/error forgiving (can render things that are not a “well-formed” Markdown) but mkdocs (a tool that we use to generate HTML for the spec website) is not so. So some spec description that looks good on GitHub may looks not as good on our spec website.

Compare

• GitHub: https://github.com/spdx/spdx-3-model/blob/main/model/Software/Properties/copyrightText.md and
• Spec website: https://spdx.github.io/spdx-spec/v3.0/model/Software/Properties/copyrightText/

You can see that the list in NOASSERTION paragraph is rendered badly on the spec website.

This is because the .md file does not have a blank line between the list and the paragraph before the list. GitHub can tolerate this, but mkdocs cannot.

This PR is trying to avoid the issue (and any issue in the future) by formatting our Markdown files to be well-formed as much as possible.

Changes

Cleanup Markdown formatting to fix document rendering issues on https://spdx.github.io/spdx-spec/v3.0/ , especially on lists and nested lists.

• Keep one blank line before and after list (markdownlint MD032)
  • This fixes an issue of the list is not rendering as list (but shown as plain text, like "* ... * ...") in:
    • https://spdx.github.io/spdx-spec/v3.0/model/Licensing/Licensing/
      • Reported in In page https://spdx.github.io/spdx-spec/v3.0/model/Licensing/Licensing/ the lists are not displayed correctly. #720
    • https://spdx.github.io/spdx-spec/v3.0/model/Software/Properties/copyrightText/
• Only use - for list item (removing the mix of * and - in one file) (MD004)
  • - is preferred, as * is also used by emphasis (*emphasis*) and in cardinality (1..*)
• Keep list indentation spaces as expected (MD007)
  • This fixes nested list rendering issue in https://spdx.github.io/spdx-spec/v3.0/model/Extension/Classes/Extension/
    • Currently the nested list one level under Point 3 is displayed as Point 4, 5, 6, 7, which is wrong. See source.
  • In case of Markdown incompatibility (between GitHub and mkdocs), avoid nested list by using blank lines and subheadings
• Add language code to code block
  • For example, "yaml" in configSourceEntrypoint.md
• Keep one blank line before and after fenced code blocks (MD031)
• Keep one blank line before and after section headers (MD022)
• Remove trailing white spaces at the end of line (MD009)
• Remove multiple consecutive blank lines and keep one and only one blank line at the end of file (MD012)
• Few other changes:
  • Put quotation marks ".." around Track* to avoid Markdown emphasis syntax confusion in SsvcDecisionType.md
  • Remove an extra ` after hasOptionalComponent in RelationshipType.md
    • Thix fixes wrong rendering of "to" in https://spdx.github.io/spdx-spec/v3.0/model/Core/Vocabularies/RelationshipType/
  • Remove an extra "m" before "Metadata" section in configSourceUri.md
• I take this opportunity to cleanup Markdown formatting in non-website files as well. For example, in Contributing.md

This will fix #720

[kestewart]

Thank you very much for figuring this out, and helping us to standarize this. Awesome work.

[goneall]

Reviewed all the changes and it looks good

My only concern is if any of the formatting changes trip up the spec parser, but since it passed the CI - it looks like this should work.

[goneall]

@kestewart @zvr We should probably merge this in soon since it touches soo many files - we don't want to end up with a lot of merge conflicts.

If you could review, then we can merge it in.

[kestewart]

All the changes look good and make sense to me.

Detailed review spotted: model/Core/Vocabularies/_vocab.md still has a TODO in it, that should be sorted out in another request, but that should not block this one from being merged. Agree, sooner rather than later is better here.

We should probably come up with some rules/checks on commits, so this sort of pass isn't required in the future.

[bact]

We should probably come up with some rules/checks on commits, so this sort of pass isn't required in the future.

There's a GitHub action for a that: https://github.com/marketplace/actions/markdownlint-cli2-action

[bact]

Is there anything I should change more from the reviews?

The number of following PRs are stacking up and there's a risk of conflicts soon.

[zvr]

Most of them are cosmetic, but some of them are not.

For example, do not change in the model

Convert headings like Syntax to ### Syntax (MD036)

We don't have headings, we don't have Markdown. We have a specialized input language that looks like Markdown and is processed by spec-parser. Please do not change any structure in the files.

In general, since we do not write Markdown, I see little point in doing checks for well-written Markdown. But of course I won't object to any PR that simply changes the content (but not the structure).

[zvr]

I did not mark all instances of Constraints and Syntax but these should not be made into new sections

[bact]

We don't have headings, we don't have Markdown. We have a specialized input language that looks like Markdown and is processed by spec-parser. Please do not change any structure in the files.

In general, since we do not write Markdown, I see little point in doing checks for well-written Markdown. But of course I won't object to any PR that simply changes the content (but not the structure).

Thank you.

I think that is generally true. It's not a mix of Markdown with something else, not exactly Markdown.

But the list rendering issues do come from the Markdown incompatibility issue, since spec-parser transforms some part of the files in spdx-3-model and copies as-is the other parts.

And those other parts (that went untransformed by spec-parser) can cause incompatibility issue, when they later being consumed by MkDocs.

It's better to go strict as long as it's not a burden of the human editors. A lot of these once merged and having some linter in place will no longer be touched again.

It can be cosmetics, but also machine compatibility and human (editors+readers) readability.

I will fix those suggested.

Btw, thanks for a clear and detailed explanation. It's good to have this discussion since this can be more or less a partial documentation of what spec-parser will consume and will emit. i.e. which parts that we shouldn't touch and leave it as-is in the *.md because it has a specific semantic to the spec-parser. We can copy part of this and put it somewhere in the spdx-spec and spdx-3-model repos so the future editors can be transparently aware of these.

[bact]

I did not mark all instances of Constraints and Syntax but these should not be made into new sections

Will check all the instances related to that.
Thanks for the heads up.

[bact]

@zvr I have revert subsections back as you have suggested. Thanks again for pointing out.

[zvr]

Thanks, @bact .

I'll merge this, since it touches a large number of files and we want to work from this state on.

If any issues arise, they can be fixed in new PRs.