Bikeshed time! For the docs, for admonitions, would you rather: 1️⃣ :

:::note[Custom title]
Contents here
:::

2️⃣

:::note[Custom title]
    Contents tabbed over
:::

3️⃣

<Admonition type="info" title="Custom title">
    Content here
</Admonition>

What technology are you using? MDX? The benefit of 3 is that it can handle >1 "prop". Idk if you have more components than Admonition? For docs.quantum.ibm.com, where we use MDX, we do have a lot of custom components and 1 and 2 wouldn't be general enough

Yes MDX, but specifically Docusaurus which already has the

Admonition

component as well as the built-in

remark

plugin to transform

:::

syntax into admonitions. So technically all 3 are possible, but as far as conventions go I thought we'd bikeshed. FWIW option 3 is the only solution when we want to change the icon or do other more complicated things (since, as you pointed out, it handles extra props)

Yeah, I'd recommend option 3. In my experience working with technical writers at IBM who have never used web frameworks like React, they had no issue with figuring it out. Our markdown guide helped: https://github.com/qiskit/documentation#how-to-write-the-documentation