Add taskfile with md:list and md:fmt targets

[titpetric]

This pull requests contains a draft Taskfile.yml. You'll need some software installed:

• https://taskfile.dev/ - A modern Makefile
• https://github.com/bwplotka/mdox - A markdown toolset providing mdox fmt

The following taskfile targets are available:

task: Available tasks for this project:
* md:fmt:        Run mdox fmt on changed .md files on PR
* md:list:       List changed .md files on PR

A few issues have been filed upstream against mdox, some have work arounds when running task md:fmt:

• Ignore front-matter flag/config Ignore front-matter flag/config bwplotka/mdox#154
• Hugo shortcode indentation Hugo shortcode identation bwplotka/mdox#155
• Before list spacing not added Before list spacing not added bwplotka/mdox#156
• Ability to control unordered list style Ability to controll unordered list style bwplotka/mdox#157

Additionally, md:list also reformats code blocks with a dot prefix (e.g. .js becomes js). This issue is more of a hugo validation issue. For the extremely wrong variants mdox does report issues when scanning.

In order for this to be usable:

• your checkout should have up to date master branch, and the PR branch
• run task md:fmt and it will auto-correct any changes made in the PR

It's absolutely required to keep master in sync with the PR branch on local. If the PR gets rebased, and you don't update your local checkout of the master branch, additional files will be reformatted.

Note: the tool also nicely reformats markdown tables, however more testing is needed to see if some unwanted behaviour occurs for the existing docs. Tested via #4186 ;

To use this for testing on PRs (before any merges are considered), fetch the file inside the root of the repository:

wget https://raw.githubusercontent.com/TykTechnologies/tyk-docs/8fcd9f72cf70ad0b5a771d30457144d2b4b3a15d/Taskfile.yml

This lets you run task md:list to inspect which changes on a PR would be analyzed, and task md:fmt to run the formatters.

[dcs3spp]

Nice!!! Is the usage before running this:

git checkout master
git pull origin master
git checkout pr-branch
git pull origin pr-branch

task md:list
task md:fmt

Could it be used in a client side commit hook using something like pre-commit or lint-staged?

[titpetric]

@dcs3spp pretty much; you need a wget to fetch the taskfile on local, as this isn't merged to the main branch yet.

Running it in client side hooks would be possible, needs testing, and standardizing on something like lefthook.

[saswatamcode]

Thanks for opening the issues on mdox, will take a look :)