This is a tag plugin for hexo to support admonition.

Basic usage

Of course, install the plugin first:

npm install --save https://github.com/sieveLau/hexo-tag-admonition

Then in your markdown file:

{% admonition danger Don't do this %}
Hello this is just a test.
This is an another line.
{% endadmonition %}

will turn into something like this:

<div class="admonition danger">
  <p class="admonition-title">Don't do this</p>
  <p class="admonition-content">Hello this is just a test.</p>
  <p class="admonition-content">This is an another line.</p>
</div>

Note: there is no space or newline charater between tags in real implementation.

What does this mean

{% admonition danger Don't do this %} is the open tag. Here admonition is the tag name, danger will be class name being added to the admonition <div>, Don't do this will be the title of the admonition.

{% endadmonition %} is the close tag. It can't be omitted.

Lines between the open and close tag are the contents, contents will be put in admonition <div>, each line wrapped in a single <p>.

Styling

Then you can style it with proper css rules. Here is a example using stylus.

It is recommended to use at least 3 levels of admonition, for example: note, warning and danger. Each with it's own style.

Also, I think it's good practice to also styling similiar keywords. For example in CSS:

.info, .note {
  color: blue;
}

.warning, .important {
  color: orange;
}

.danger, .critical {
  color: red;
}

Have a look at this codepen.

More:

• admonition title will be wrapped between <p class="admonition-title"></p>
• admonition contents, each line wrapped in a single <p class="admonition-content"></p>
• the whole block wrapped in <div class="admonition level"></div>, note that level is the word you type in the tag (for example, danger)

Example: How to use this on Hexo Theme Landscape

First, install this plugin. Second, download landscape from its release page and extract into themes/landscape. Third, download the example admonition.styl to themes/landscape/source/css/_partial, and add this line to themes/landscape/source/css/style.styl:

@import "_partial/admonition"

Done.

What I modified

• Provide stylus example, since I use Hexo's default theme Lanscape. Basically it is a direct translation from the css example on codepen to stylus.
• Add jsdom as dependency, in order to add class admonition-content to admonition paragraphs. With this modification, we can now better control the appearance.

Useful Tools

• Stylus Doc: Mixins, Variables, and the CLI
• Stylus Playground: If you don't want to install stylus on your machine, you can use this online compiler.

License

MIT