Handle mkdocs/GitHub admonition conversions

[nan-yu]

GitHub doesn't natively render mkdocs admonitions, making the markdown docs hard to read in the repo.

The pure GitHub markdown loses styling consistency provided by mkdocs admonitions.

This PR adds a script that allows us to maintain a "GitHub-first" source while deploying a "Mkdocs-working" site by introducing the convert_docs script.

[jacobsimionato]

This looks awesome to me! Would love @zeroasterisk to take a look seeing as he understand the mkdocs deployment pipleine.

[zeroasterisk]

Hmmm... pretty cool solution. I'm good with it.

I may add a README to the /docs/scripts/ folder explaining what the supported conversions are.... but no reason to block this PR to make that happen.

Thanks @nan-yu for the contribution! ❤️

[zeroasterisk]

Actually one more thing before I merge.... This is currently bi-directional. Shouldn't it instead be uni-directional?

From github markdown to mkdocs markdown?

We don't need the return trip for any reason, unless we are going to add CI/CD linting to throw errors on PR review and enforce github markdown format.

@nan-yu I'm going to merge, but if you're feeling generous and want to make a 2nd pass, I'd rather have a smaller uni-directional transform potentially with PR linting enforcement vs bi-directional transformer.

[nan-yu]

Actually one more thing before I merge.... This is currently bi-directional. Shouldn't it instead be uni-directional?

From github markdown to mkdocs markdown?

We don't need the return trip for any reason, unless we are going to add CI/CD linting to throw errors on PR review and enforce github markdown format.

@nan-yu I'm going to merge, but if you're feeling generous and want to make a 2nd pass, I'd rather have a smaller uni-directional transform potentially with PR linting enforcement vs bi-directional transformer.

Thanks for the merge! The bi-directional support was initially there to covert the *.md files from mkdocs admonitions to GitHub markdowns. Now that the conversion is done, I agree that a uni-directional flow is much cleaner.

I'll follow up with a PR to simplify the transformer.

[nan-yu]

Actually one more thing before I merge.... This is currently bi-directional. Shouldn't it instead be uni-directional?

From github markdown to mkdocs markdown?

We don't need the return trip for any reason, unless we are going to add CI/CD linting to throw errors on PR review and enforce github markdown format.

@nan-yu I'm going to merge, but if you're feeling generous and want to make a 2nd pass, I'd rather have a smaller uni-directional transform potentially with PR linting enforcement vs bi-directional transformer.

done in #564, which also adds a README file in the scripts directory.