Write test for bad pattern: .md/#

[HonkingGoose]

Describe the proposed change(s).

Write or adjust a GitHub Action test, that fails if it finds the .md/# pattern in any of our .md files.

Optional: the Action writes an annotation to the bad file. Like this:

The .md/# pattern is bad, remove the / beween the filename and the anchor. Correct: .md#section-name.

Describe why we need/want these change(s).

I'm writing bad links each time, where I use the .md/# pattern to link to another file. I'd like a test that stops me doing this stupid thing. 😄

This is because the VSCode preview accepts the bad pattern, but our published docs get messed up. 🙈

[viceice]

I think we can use a simple jest test to find files with those wrong links and fails if one is found.

[HonkingGoose]

That sounds good to me! 😄

[lmilbaum]

I'd suggest using pre-commit hook - markdown-link-check - https://github.com/tcort/markdown-link-check

[HonkingGoose]

MkDocs v1.5.0 comes with better link validation. ¹ I don't know if that would catch my .md/# style bad links?

One problem remains, the MkDocs build step runs at the end, not at the beginning. Here's what I mean:

1. We update to MkDocs v1.5.0 and enable link validation, and assume it will catch the bad link pattern
2. @HonkingGoose writes bad link pattern
3. Renovate updates the renovatebot/renovate Git submodule on the docs repository
4. Our CI runs the mkdocs build in the strict mode, and it errors out
5. @HonkingGoose fixes bad link in the renovatebot/renovate repository
6. Renovate updates submodule again, with the good link
7. MkDocs build passes
8. Updated site is published

We probably still want some kind of check to find the bad links when I'm writing them... 🙈

Footnotes

1. MkDocs 1.5.0 release notes, expanded validation of links ↩

[HonkingGoose]

Pinging @PeterNitsche so they see the new comments in this issue.

[lmilbaum]

pre-commit can catch mistakes when one tries to commit (before the code changes pushed to github). @HonkingGoose Would that cover your ask?

[HonkingGoose]

I sometimes "cheat" by using the GitHub code editor online, instead waiting for a fresh Codespace to start. So using a pre-commit check only won't catch all my bad stuff. Whatever tests we're going to use/build, we should run automatically. 😄

[lmilbaum]

The same pre-commit process can also invoked in CI. See this example: https://github.com/devopsloft/devopsloft.github.io/blob/main/.github/workflows/pre_commit.yml

[viceice]

pre-commit hooks where removed recently because of slowness, so they aren't an option again

[PeterNitsche]

Funny, the issue remains untouched for 2 weeks with a proposed solution and once the proposal is implemented, other proposals are discussed. 😄

Regarding the discussion: I like the pragmatic solution of using Jest to validate the documentation. It fits into the code concept since there are already other Jest tests validating the documentation.
Adding another library to the stack means also increased complexity, maintenance effort and risk of vulnerabilities in the future. The Jest solution solves exactly the problem described by @HonkingGoose and nothing more.
If @HonkingGoose notices more issues with invalid markdown files, a third-party library can be added in another iteration.

[HonkingGoose]

I'm happy with fixing just my bad links in the first iteration. 🙂

I'm only mentioning the mkdocs update because it might affect how/if the maintainers want to fix this issue. 🙂 And when I wrote the issue, the mkdocs update wasn't out yet... 😇

[lmilbaum]

Funny, the issue remains untouched for 2 weeks with a proposed solution and once the proposal is implemented, other proposals are discussed. 😄

I assume this comment is directed at me. I thank you for the feedback. It is completely valid.
I have good explanations why I haven't been engaged until now but maybe it's not that interesting.
In my honest opinion, in an open source project, one can be involved at any given moment and even after the fact. What to do with the proposals/feedback is up to the maintainers' decision (just for information, I am not one of them).

[PeterNitsche]

@lmilbaum That comment was not meant as direct feedback at all. I am just highlighting the coincidental series of events which amuses me. 🙂