Integration of White Papers into mainline documentation #2973
Description
We need to properly integrate the White Papers into the mainline documentation.
The first thing here is to do another pass through the existing white papers to see if there is anything that should be surfaced more generally, and therefore needs to get poured into the documentation rather than exist as a separate document.
Next however is adding an info block to the online documentation to point users at white papers that extend the documentation. All the white papers should (in theory) be extensions — deep dives into certain topics — extending the existing documentation. We should therefore insert info blocks at the correct places in the documentation pointing users to that extended docuemntation.
I'm sort of envisioning a new type of admonitions-style block for emphasis called [WHITEPAPER] which might look something like this,
although if we want to do an initial fast pass where we can start by using a standard [INFO] block to get them all integrated more quickly.
My understanding is that we can't add a new admonition-style block, so we'd probably have to add a macro and handle styling in pre-processing. I'd suggest it would look like this,
[whitepaper, title="White Paper Title", subtitle="A subtitle for the white paper", link=https://url.here]
----
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus elementum purus a eros laoreet, a vestibulum risus interdum. Suspendisse bibendum sagittis felis et pulvinar. Fusce purus ante, vestibulum in lacinia a, placerat quis libero. Nunc nibh mauris, finibus vel fermentum vulputate, convallis id neque. In in rhoncus urna. Aliquam sed sapien porta, venenatis massa vitae, aliquam mauris. Nunc ut ante pharetra, faucibus ante convallis, venenatis ligula.
Nullam volutpat, sem quis commodo condimentum, libero ex aliquam urna, in aliquet justo felis mattis libero. Pellentesque vestibulum enim vel augue blandit tempus. Ut a elit non turpis viverra aliquam sed a felis. Etiam ut porta mi. Sed feugiat arcu leo, vulputate placerat ante ullamcorper at. In id metus sit amet massa molestie efficitur. Morbi rutrum scelerisque metus id dignissim.
----
where the title, subtitle and link are automagically inserted into the text in the block. Potentially we can hook into delimited blocks in general, although I like the idea of having the same syntax layout for this block as we do for a [source] block rather than the harder-to-remember macro syntax.