docs: Update docs tooling and checks

[lornajane]

What/Why/How?

Following the upgrade on our docs platform, this pull request assembles some updates that were waiting for this change!

Provisional list:

• fix broken Vale checks on PR (the annotations aren't working due to token permissions)
• refresh Vale rules and centralise configuration
• remove outdated jobs, including sync
• use markdownlint to match destination website repo
• run prettier on docs folder (as requested in Run prettier for markdown files #1111 )
• revisit link checker
• add support for running the Redocly CLI docs standalone
• update Contributing file so that all contributors can use the docs with confidence
• move Contributing file to top level of repo

Reference

Testing

Screenshots (optional)

Check yourself

• Code is linted
• Tested with redoc/reference-docs/workflows (internal)
• All new/updated code is covered with tests

Security

• Security impact of change has been considered
• Code follows company security practices and guidelines

[changeset-bot]

🦋 Changeset detected

Latest commit: f753c86

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@redocly/cli	Patch
@redocly/openapi-core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Command	Mean [s]	Min [s]	Max [s]	Relative
redocly lint packages/core/src/benchmark/benches/rebilly.yaml	1.005 ± 0.030	0.982	1.088	1.00
redocly-next lint packages/core/src/benchmark/benches/rebilly.yaml	1.016 ± 0.017	0.990	1.043	1.01 ± 0.03

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟡	Statements	76.12%	4057/5330
🟡	Branches	65.94%	2151/3262
🟡	Functions	68.3%	657/962
🟡	Lines	76.31%	3805/4986

Test suite run success

646 tests passing in 93 suites.

Report generated by 🧪jest coverage report action from f753c86

[tatomyr]

I wonder if it also makes sense to move our contribution guide to the root folder in the scope of this task. I'm not sure why it happens to reside in the .github folder in the first place 🙂

[lornajane]

Good idea, I think I will do that. I really prefer to easily find it at the root of the project.

[lornajane]

Summarising a discussion with @tatomyr : the website repo that the docs/ folder publishes to uses markdownlint and the exact same rules are used here. This project also uses prettier, which does a lot of the same things. That's fine for now, but if both tools are adopted in the main website in the future, we could try to limit the overlap.

[HCloward]

Wow, very nice! Thanks for doing all of this work.