Skip to content

Add template workflow to check Markdown files for problems #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 15, 2021

Conversation

per1234
Copy link
Contributor

@per1234 per1234 commented Jun 15, 2021

On every push and pull request that affects relevant files, and periodically, check the repository's Markdown files for
problems:

The Arduino tooling Markdown style is defined by the .markdownlint.yml file.

In the event the repository contains externally maintained Markdown files, markdownlint can be configured to ignore them via a .markdownlintignore file:
https://github.com/igorshubovych/markdownlint-cli#ignoring-files

markdown-link-check is configured via the .markdown-link-check.json file:
https://github.com/tcort/markdown-link-check#config-file-format

The workflow is also used for this repository's own CI.


Notes

Failure of the link check CI is expected currently due to:

  • Links based on the final repository location under the arduino organization.
  • Link to a readme for a template workflow that has not yet been added to the repository.

I have always been bothered by the lack of compatibility of our link check task with Windows.

The code used to iterate over the repository's Markdown files is in Bash. Normally this works perfectly well on Windows due to Task using a built-in shell interpreter independent from whatever is in use natively on the machine running the task. However, this particular Bash code is run by npx --call, which uses the native shell of the operating system. This means the Bash code is run in cmd on Windows machines, which doesn't work. I have spent a ton of time trying to find a way to get this working with npx --call on Windows:

  • Attempting to write an equivalent in batch, which would be easy enough in a batch file, but is not at all once you are faced with the odd restrictions imposed by passing the code as an argument to npx in combination with some mangling done by YAML and Task.
  • Looking for a way to configure npx to use another shell, which seems to be impossible.

The solution I settled on is to simply abandon the use of npx on Windows, instead requiring Windows users to have markdown-link-check pre-installed and in PATH. This allows the use of the Bash code directly in the task. Other operating systems continue to use the traditional npx approach. Even though this isn't an ideal solution, it's a great improvement over the previous one where it was impossible for Windows contributors to run the task.

@per1234 per1234 added type: enhancement Proposed improvement topic: code Related to content of the project itself labels Jun 15, 2021
@per1234 per1234 requested review from silvanocerza and rsora June 15, 2021 13:51
On every push and pull request that affects relevant files, and periodically, check the repository's Markdown files for
problems:

- Use markdownlint to check for common problems and formatting.
- Use markdown-link-check to check for broken links.

The Arduino tooling Markdown style is defined by the `.markdownlint.yml` file.

In the event the repository contains externally maintained Markdown files, markdownlint can be configured to ignore them
via a `.markdownlintignore` file:
https://github.com/igorshubovych/markdownlint-cli#ignoring-files

markdown-link-check is configured via the `.markdown-link-check.json` file:
https://github.com/tcort/markdown-link-check#config-file-format

The workflow is also used for this repository's own CI.
@per1234 per1234 merged commit 0522d16 into main Jun 15, 2021
@per1234 per1234 deleted the check-markdown branch June 15, 2021 14:52
@per1234 per1234 self-assigned this Nov 20, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
topic: code Related to content of the project itself type: enhancement Proposed improvement
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants