Add markdownlint to CI workflow to lint documentation

[sumitgiri87]

This adds a Markdown linter to the CI workflow to help catch formatting and style issues in our documentation automatically. The goal is to keep our Markdown files clean and consistent without needing manual checks.

Fixes #1785

Yep, the linter runs on every pull request to make sure all Markdown files follow the style rules we've set.

• Does this PR change the input/output behaviour of a cryptographic algorithm (i.e., does it change known answer test values)? (If so, a version bump will be required from x.y.z to x.(y+1).0.)
  No, this PR only adds a Markdown linter to the documentation CI and does not affect any cryptographic algorithms or their outputs.
• Does this PR change the list of algorithms available -- either adding, removing, or renaming? Does this PR otherwise change an API? (If so, PRs in fully supported downstream projects dependent on these, i.e., oqs-provider will also need to be ready for review and merge by the time this is merged.)
  No, this PR does not modify any algorithms or APIs; it only improves documentation quality checks.

[aidenfoxivey]

I'd maybe consider using actions/checkout@v4 instead of actions/checkout@v3 here. I think Github actions is upset for some reason.

[sumitgiri87]

I'd maybe consider using actions/checkout@v4 instead of actions/checkout@v3 here. I think Github actions is upset for some reason.

[aidenfoxivey]

Appears this PR does not also format the Markdown files to the preferred spec. I think it would be ideal to format the Markdown files and add the workflow, since adding the workflow implies we need to then format them.

I think the travis CI failure is just a result of the workflow being killed - there doesn't appear to be anything in the way of issues there.

[dstebila]

Appears this PR does not also format the Markdown files to the preferred spec. I think it would be ideal to format the Markdown files and add the workflow, since adding the workflow implies we need to then format them.

I think we'd want to manually format the Markdown files, rather than having the workflow do it, so that a human actually considers whether any formatting changes introduced bugs. We'd want to document somewhere (or have the failing script output a reminder) how to run the Markdown formatting commands manually.

[baentsch]

Appears this PR does not also format the Markdown files to the preferred spec. I think it would be ideal to format the Markdown files and add the workflow, since adding the workflow implies we need to then format them.

I think we'd want to manually format the Markdown files, rather than having the workflow do it, so that a human actually considers whether any formatting changes introduced bugs. We'd want to document somewhere (or have the failing script output a reminder) how to run the Markdown formatting commands manually.

Conceptually sensible, but this means this PR would either have to get(include the result of this manual review (as the linter fails in PR) or we need to merge with CI failing and do a separate PR to fix the markdown. What's your preference @dstebila @sumitgiri87 how to do it?

[dstebila]

Appears this PR does not also format the Markdown files to the preferred spec. I think it would be ideal to format the Markdown files and add the workflow, since adding the workflow implies we need to then format them.

I think we'd want to manually format the Markdown files, rather than having the workflow do it, so that a human actually considers whether any formatting changes introduced bugs. We'd want to document somewhere (or have the failing script output a reminder) how to run the Markdown formatting commands manually.

Conceptually sensible, but this means this PR would either have to get(include the result of this manual review (as the linter fails in PR) or we need to merge with CI failing and do a separate PR to fix the markdown. What's your preference @dstebila @sumitgiri87 how to do it?

Would separate commits on this PR be sufficient organization? One sequence of commits setting up the tool and checks, noting that the CI will fail on those commits, followed by a distinct commit that fixed the Markdown. One could then read the commit history separately for ease of review, but still end up with a single PR that is green at the end?

[baentsch]

Would separate commits on this PR be sufficient organization? One sequence of commits setting up the tool and checks, noting that the CI will fail on those commits, followed by a distinct commit that fixed the Markdown. One could then read the commit history separately for ease of review, but still end up with a single PR that is green at the end?

I'd say so. Just please make sure to not squash these logically separate commits (as otherwise is usual) during merge such as to be able to separately roll them back if the need may arise.