What's the best way for admonition (callout) boxes?

[Andre601]

I'm in the process of adding custom admonition (aka callout) boxes to some docs I want to contribute towards...

Since I don't have any general experience with 11ty and stuff like tags, etc did I stick with normal HTML and CSS stuff...
It works and currently looks something like this:

Tho, this one is a pain to work with, especially given that I dislike the fact you have to insert HTML tags in markdown files to make it render.

I now saw that the 11ty docs use some callout boxes of their own and I consider to try and create some myself. Tho, as mentioned do I have no experience with templates and alike (At most some very basic liquid knowledge using jinja2), so I have no idea where to get started...

I pretty much want to have what I show in the example above, but as a {% <name> <option> %}...{% end<name> %} tag or what it is called.

Also, preferably would I like to have it as njk file since those are the ones used by the docs I contribute towards.

So... What would be the best way to achieve such stuff?
(Also, if you have any CSS tips, let me know. Not too happy with the current design, especially the icon placement...)

[pdehaan]

I think you pretty much got it. I'd use a paired shortcode, like https://www.11ty.dev/docs/languages/nunjucks/#paired-shortcode

So it would look something like your example:

{% callout "info" %}
This could be some HTML or Markdown content.

<p>This would be incompatible with using the apex <code>example.com</code> for other purposes, e.g. for the <i>Personal/Organization</i> example discussed before.</p>
{% endcallout %}

And maybe your callout shortcode wraps the content in an <aside> tag and displays the "Info" label/icon based on the level that you pass to the shortcode. Or some extra error checking to throw errors if you pass an invalid level/severity (like "warn" instead of "warning", etc).

Here's the code that the 11ty-website used [prior to the webc conversion]:
https://github.com/11ty/11ty-website/blob/58aa80203fb765d5c1edca8a3697f1d794482324/config/markdownPlugin.js#L67-L85

But that's probably easier than trying to figure out how to shim something like https://www.npmjs.com/package/markdown-it-admonition into your project and make it work w/ Nunjucks instead of just Markdown.

[Andre601]

Thanks... Found it myself right before you gave your answer and created this.

  eleventyConfig.addPairedShortcode("admonition", function(content, type, title) {
    let titleStr = "";
    if(title) {
      titleStr = title;
    } else if(type) {
      titleStr = type.substring(0, 1).toUpperCase() + type.substring(1).toLowerCase();
    } else {
      titleStr = "Info";
    }
    
    let typeStr = "";
    if(type) {
      typeStr = type.toLowerCase();
    }else{
      typeStr = "info";
    }
    
    return `<div class="admonition ${typeStr}">
      <p class="admonition-title">${titleStr}</p>
      <div class="admonition-content">${content}</div>
    </div>`
  })

My main issue is just the CSS now as it causes me some headaches... But it's not really your problem to help with. 😅

[Andre601]

Tho, looking at the example you gave, I now wonder if there is any significant difference between mdIt.renderInline(content) and mdIt.render(content)

The docs I work on use Markdown, but may also have HTML included (i.e. <picture> for images), so idk if there is much of a difference or if I can choose one or the other.
The blocks would - to my knowledge - only be used in page content itself and would be on their own lines (So no side-by-side view or smth).

[pdehaan]

I'd have to look up the exact details of .render() vs .renderInline(), I'm vaguely recalling one wraps with a <p> tag and maybe the other doesn't.

---

MarkdownIt.render():

Render markdown string into html. It does all magic for you.
env can be used to inject additional metadata ({} by default). But you will not need it with high probability. See also comment in MarkdownIt.parse.

versus

MarkdownIt.renderInline():

Similar to MarkdownIt.render but for single paragraph content.
Result will NOT be wrapped into <p> tags.