Add admonition support

[talha131]

Markdown and rest both have admonitions. We should support it.

https://python-markdown.github.io/extensions/admonition/

Related to https://github.com/Pelican-Elegant/documentation/issues/36

[AWegnerGitHub]

Related - those docs recommend looking at Sphinx for inspiration for styling. Here is a link to how that looks: https://pythonhosted.org/sphinxjp.themes.basicstrap/sample.html#admonitions-docutils-origin

[AWegnerGitHub]

Using the Sphinx CSS from the link above, this is what the different styles look like in Elegant. It's about 60 lines of CSS. I admit that I am not a CSS expert. I have no idea if these can be paired down to be more efficient.

The CSS uses a bit of FontAwesome to get the icons before the admonition title text.

/* Admonition styles */
div.admonition {
  padding: 8px 35px 8px 0px;
  margin-bottom: 20px;
  color: #c09853;
  text-shadow: 0 1px 0 rgba(255, 255, 255, 0.5);
  background-color: #fcf8e3;
  border: 1px solid #fbeed5;
  -webkit-border-radius: 4px;
     -moz-border-radius: 4px;
          border-radius: 4px;
}

div.admonition p {
  margin: 0.5em 1em 0.5em 1em;
  padding: 0;
}

div.admonition pre {
  margin: 0.4em 1em 0.4em 1em;
}

div.admonition p.admonition-title {
  margin: 0;
  padding: 0.1em 0 0.1em 0.5em;
  font-weight: bold;
}

div.admonition ul, div.admonition ol {
  margin: 0.1em 0.5em 0.5em 3em;
  padding: 0;
}

/* -- danger, error -- */
div.danger,
div.error {
  color: #b94a48;
  background-color: #f2dede;
  border-color: #eed3d7;
}

/* -- warning, caution, attention -- */
div.warning,
div.caution,
div.attention {

}

/* -- note, important -- */
div.note,
div.important {
  color: #468847;
  background-color: #dff0d8;
  border-color: #d6e9c6;
}

/* -- hint, tip -- */
div.hint,
div.tip {
  color: #3a87ad;
  background-color: #d9edf7;
  border-color: #bce8f1;
}

div.danger p.admonition-title:before,
div.error p.admonition-title:before,
div.warning p.admonition-title:before,
div.caution p.admonition-title:before,
div.attention p.admonition-title:before,
div.important p.admonition-title:before,
div.note p.admonition-title:before,
div.hint p.admonition-title:before,
div.tip p.admonition-title:before
{
  display: inline-block;
  font-family: FontAwesome;
  font-style: normal;
  font-weight: normal;
  line-height: 1;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

div.danger p.admonition-title:before,
div.error p.admonition-title:before {
  content: "\f06a\00a0";
}
div.warning p.admonition-title:before,
div.caution p.admonition-title:before,
div.attention p.admonition-title:before {
  content: "\f071\00a0";
}
div.important p.admonition-title:before,
div.note p.admonition-title:before {
  content: "\f05a\00a0";
}
div.hint p.admonition-title:before,
div.tip p.admonition-title:before {
  content: "\f0eb\00a0";
}

Adding each of these is easy:

!!! attention
    Attention please!

This adds the attention admonition. Available options are:

• danger, error - These are red
• warning, caution - These are yellow
• important, note - These are green
• tip, hint - These are blue

Using admonition support, at least with Markdown, requires one entry in MARKDOWN in pelicanconf.py:

MARKDOWN = {
    ...
    'markdown.extensions.admonition': {},
    ...
}

---

Requests to the community:

1. Does this look ok or should colors be adjusted?
2. Can the CSS be optimized? As I mentioned above, CSS is not my skillset.

[talha131]

Thank you @AWegnerGitHub. It looks great. As for CSS, we can always iterate over it like everything else later.

Although it's in milestone 3.0 but I don't see why we should hold this feature, if it is ready.

1. Can you open a PR against master
2. Put admonition CSS in a separate CSS file
3. Include CSS file in base.html head

Later we would add an article about admonition to the documentation.

Great job @AWegnerGitHub. I am sure we are the first pelican theme to offer admonition support.