doc: Use GitHub's "Alert" markdown syntax #28243

GH has introduced new "Alert" syntax for md files (a.k.a "Admonitions" in other languages).

Whilst being wary of changing documentation just for the sake of "shiny" new features, in my opinion this is worthwhile in this case as we can use it to draw user attention to particularly important sections of docs.

The format is relatively backwards-compatible (i.e outside of GH), as the syntax is effectively a multi-block quotation, where the first line includes the alert type. This means the text still renders fine outside of GH, but is improved on GH. Samples below:

GitHub render:

Hackmd render:

See e.g. https://github.com/willcl-ark/bitcoin/blob/2023-08-gh-alerts/doc/managing-wallets.md for a doc containing a few alerts.

Opening as draft for now to see if others would consider such a change worthwhile, not interested in bike-shedding over which alert level is used where, for now :) But for reference GH provides documentation with their recommended usage of alert levels, which I did try to roughly use in this draft.

<!--e57a25ab6845829454e8d69fc972939a-->

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

<!--021abf342d371248e50ceaed478a90ca-->

Reviews

See the guideline for information on the review process. A summary of reviews will appear here.

<!--174a7506f384e20aa4161008e828411d-->

Conflicts

Reviewers, this pull request conflicts with the following ones:

• #27731 (Prevent file descriptor exhaustion from too many RPC calls by fjahr)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

Just one opinion, but I find these alerts/admonitions distract from the text itself both when read on GitHub and also when read in markdown format. They also make reading the source files more difficult, which is how I consume the docs.

It's also preferable to avoid GitHub-specific features and workflows. Greater developer lock-in has been a clear goal for GitHub for years now.

+1 Sooner we’ll move out of Github better we’ll be and we would be rather to prepare for greater disruptions of GH availability (e.g regularly backing up the decade of comments on the repo) than rely more on its features.

Thanks for the feedback, I share the worry with becoming locked in to a single vendor for our development.

IMO adding markdown syntax is not a big threat to this, but something is always more than nothing. FWIW Gitlab also supports alerts via bootstrap (so would require another change if we moved there ever), asciidoc has native admonition support, etc.

They also make reading the source files more difficult, which is how I consume the docs.

I also consume them like this, but it's not the only markdown syntax which I find makes things difficult to read in this mode.

<snip> rather to prepare for greater disruptions of GH availability (e.g regularly backing up the decade of comments on the repo) than rely more on its features.

There is more than one effort underway to do this very thing, e.g.: https://mirror.b10c.me/

I don't have a horse in this race and certainly don't want to waste developer time on it. I thought on balance of probability this change would specifically benefit our users, but if there's no interest in it I will be only too happy to close it down.

this would mess up the rendering in every markdown renderer except on Github, example:

<img width="634" alt="Screenshot 2023-08-10 at 4 07 03 PM" src="https://github.com/bitcoin/bitcoin/assets/23396902/a5e18b4d-9cfb-4a64-b24b-b8300aec4ff0">

this would mess up the rendering in every markdown renderer except on Github, example:

Yes I was aware of this and noted the tradefoff in OP:

The format is relatively backwards-compatible (i.e outside of GH), as the syntax is effectively a multi-block quotation, where the first line includes the alert type. This means the text still renders fine outside of GH, but is improved on GH.

Closing for now due to lack of interest