Use Acsiidoc as README format

[bdemers]

To simplify the release process, we can migrate the README to adoc and use variables for things like the project version.

This should simplify release automation in the future.

NOTE: This PR should NOT be merged, but instead should be re-applied after JWE work is complete

Steps:

Install kramdown:

gem which kramdown-asciidoc

Convert README:

kramdoc README.md
rm README.md
git add README.adoc

Add project version variable, and update code blocks:
See b0f106a

NOTE: Code blocks are not filtered/interpolated by default, so the subs="+attributes" directive must be added

TODO:

• Confirm all anchors are present
• Update Note/Warning blocks
• Use adoc Table of Contents
• Visually compare with README.md (side-by-side)

[bdemers]

NOTE: There are other features we can get from adoc too, like automatic generation of the table of contents. That is not part of this PR.
I also didn't verify the results were the same as the markdown version. This PR is mostly a POC to check what is possible.

[lhazlewood]

@bdemers wanna rebase now?

[bdemers]

NOTE: subscript doesn't render correctly, I'll continue to look into that. If you see any other issues let me know

[bdemers]

Rebased, (force pushed)

[lhazlewood]

2 questions:

1. Is this approach 'worth it' to you - i.e. do you feel it provides both a better authoring mechanism as well as reader/viewer experience?
2. Will existing external links to our documentation still work correctly? I just thought if something references https://github.com/jwkt/jjwt/README.md#some-anchor, everything like that would break, no?

[lhazlewood]

Does this mean that the anchor is still valid/retained? I'm not yet familiar with this type of adoc syntax.

[bdemers]

Yes, both the named and generated anchors should be the same

[bdemers]

1. Is this approach 'worth it' to you - i.e. do you feel it provides both a better authoring mechanism as well as reader/viewer experience?

IMHO, it provides a better author experience, and it allows the version to be set with a property [in the header] (and could be automated at release times).

2. Will existing external links to our documentation still work correctly? I just thought if something references https://github.com/jwkt/jjwt/README.md#some-anchor, everything like that would break, no?

Yes, I made a pass through last week, running something like this (browser console), in both GitHub rendered versions (and diffed them):

for (const a of document.anchors) {
    if (a.name.startsWith('user-content-')) {
        console.log(a.name.substring(13, a.name.length))
    }
}

It seems GitHub prefixes the named anchors with user-content- (I assume to avoid conflicts).
However, using the shortened fragment, e.g. README.adoc#some-anchor works too. (likely some JS to handle the URL fragments 🤷),

[lhazlewood]

Ok, thanks for the confirmation! Feel free to merge - I wouldn't want you to have to go through another big merge conflict again in the future. If we miss any small details now, we can always adjust them later.