robolectric.github.io
robolectric.github.io copied to clipboard
robolectric
Create workflow to lint Markdown files
This PR creates a new workflow to lint Markdown files. This was suggested here: https://github.com/robolectric/robolectric.github.io/pull/255#discussion_r1660106328.
The new workflow uses the DavidAnson/markdownlint-cli2-action action. It uses the rules defined in DavidAnson/markdownlint.
For the moment, I've kept the default configuration (ie. all the rules are enabled), and modified the maximum line length to be 120 characters, instead of 80. A sample output is available here: https://github.com/robolectric/robolectric.github.io/actions/runs/9766776527/job/26960490077?pr=265.
I didn't modify any Markdown file yet, because I think that it's better to agree on the rules first. Once that's done, I'll fix all the Markdown files.
The original suggestion was to only enforce max line length. That's possible with the action I'm using. We just need to agree on the value to use.
@MGaetan89 Can we run lint with https://github.com/DavidAnson/markdownlint manually? We can create our custom lint configuration file and manage it with git. It's easy to setup the environment for npm in GitHub Action, and we also can use it locally to apply potential fixes automatically.
@MGaetan89 Can we run lint with DavidAnson/markdownlint manually? We can create our custom lint configuration file and manage it with git. It's easy to setup the environment for npm in GitHub Action, and we also can use it locally to apply potential fixes automatically.
Good point, I forgot to include that. I'll work more on this PR, to explain how to run the check locally. The idea is to use the provided CLI tool: https://github.com/DavidAnson/markdownlint-cli2
@MGaetan89 Can we run lint with DavidAnson/markdownlint manually? We can create our custom lint configuration file and manage it with git. It's easy to setup the environment for npm in GitHub Action, and we also can use it locally to apply potential fixes automatically.
I've finally added a note to explain how to check the format locally with the command line tool.
@MGaetan89 Can we fix lints automatically with some commands?
Yes, it's the command I added to the Readme in this PR:
markdownlint-cli2 "docs/**/*.md" "#docs/javadoc/**/*.md" --config .markdownlint.jsonc --fix
I can open a new PR which fixes all the warnings (or maybe multiple smaller PRs)
I see that a lot of warnings are about long line length. Often it's because of inlined urls. I'll submit a PR to extract URLs at the bottom of the files first (like in 2021-10-06-sharedTest.md).
This will make reading the Markdown files easier, and hopefully this PR a bit smaller too.
This is now ready for review
@utzcoz I see that Build website is not a required check on PRs. What do you think about making it mandatory? And the same with the new Lint Markdown check.
@MGaetan89 IIRC, it was not enabled because of PRs created by GitHub Action for javadoc?
@MGaetan89 I think disabling some lint rules are fine enough, we can adjust them based on lint library and our requirements.
@MGaetan89 IIRC, it was not enabled because of PRs created by GitHub Action for javadoc?
Right, I think you're right 👍🏻