component-docs icon indicating copy to clipboard operation
component-docs copied to clipboard

Discuss alternatives to `mdbook-alerts` for callout preprocessors

Open mkatychev opened this issue 8 months ago • 0 comments

mdbook-alerts seems "good enough" for both the web and Github display, but IMO this is worth bringing up so that everyone can discuss

Originally posted by @vados-cosmonic in https://github.com/bytecodealliance/component-docs/pull/218#discussion_r2011271456

mdbook-admonish is one alternative to consider for this role:

Pros:

  • In use by popular projects such as Tree-sitter
  • Uses material design (somewhat subjective but it styling feels clearer)
  • handles console outputs as their own element
  • does not need workarounds to play nice with mdbook-linkcheck

Cons:

  • Does not support > quote blocks https://github.com/tommilligan/mdbook-admonish/issues/72
  • non zero amount of effort to move over to an alternative

mkatychev avatar Mar 25 '25 17:03 mkatychev