Avoid platform-specific code in markdown:check-links task

[per1234]

The markdown:check-links task uses the markdown-link-check. This tool does not have a capability for discovering Markdown files so it is necessary to use the find command to discover the files, then pass their paths to the markdown-link-check tool.

Since it is managed as a project dependency using npm, the markdown-link-check tool is invoked using npx. Since the find command must be ran in combination with markdown-link-check, it is necessary to use the --call flag of npx. Even though Windows contributors are required to use a POSIX-compliant shell such as Git Bash when working with the assets, the commands ran via the --call flag are executed using the native shell, which means the Windows command interpreter on a Windows machine even if the task was invoked via a different shell. This causes commands completely valid for use on a Linux or macOS machine to fail to run on a Windows machine due to the significant differences in the Windows command interpreter syntax.

During the original development of the task, a reasonably maintainable cross-platform command could not be found. Lacking a better option, the hacky approach was taken of using a conditional to run a different command depending on whether the task was running on Windows or not, and not using npx for the Windows command. This resulted in a degraded experience for Windows contributors because they were forced to manually manage the markdown-link-check tool dependency and make it available in the system path. It also resulted in duplication of the fairly complex code contained in the task.

Following the elimination of unnecessary complexity in the task code, it became possible to use a single command on all platforms.

The Windows command interpreter syntax still posed a difficulty even for the simplified command: A beneficial practice, used throughout the assets, is to break commands into multiple lines to make them and the diffs of their development easier to read. With a POSIX-compliant shell this is accomplished by escaping the introduced newlines with a backslash. However, the Windows command interpreter does not recognize this syntax, making the commands formatted in that manner invalid when the task was ran on a Windows machine. The identified solution was to define the command via a Taskfile variable. The YAML syntax was carefully chosen to support the use of the familiar backslash escaping syntax, while also producing in a string that did not contain this non-portable escaping syntax after passing through the YAML parser.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.05%. Comparing base (51b3eac) to head (a7443f8).
Report is 7 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #784   +/-   ##
=======================================
  Coverage   90.05%   90.05%           
=======================================
  Files          44       44           
  Lines        6800     6800           
=======================================
  Hits         6124     6124           
  Misses        553      553           
  Partials      123      123           

Flag	Coverage Δ
unit	90.05% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.