Admonition Extension

Overview

Creates block-styled side content. Based on Admonition Extension, Material for MkDocs (Personal opinion: Material for MkDocs is eye-candy. If you have not taken a look at it, you are missing out on a visual treat.).

Syntax

Block-Styled Side Content

!!! qualifier "Optional Title"
    block content 

No-Heading Content

!!! qualifier ""
    block content 

Collapsible Block-Styled Side Content:

Collapsed by default

??? qualifier "Optional Title"
    block content 

Open by default

???+ qualifier "Optional Title"
     block content 

SVG images and stylesheet included for default qualifiers. User definable qualifiers can be added by specifying recognized style qualifiers, their aliases and image mapping.

Qualifiers are used to select the icon and the color of the block.

abstract style abstract summary tldr bug style bug danger style danger error example style example snippet fail style failure fail missing faq style question help faq info style info todo note style note seealso quote style quote cite success style success check done tip style tip hint important warning style warning caution attention

Parsing Details

Use class AdmonitionExtension from artifact flexmark-ext-admonition.

Defined in AdmonitionExtension class:

CSS and JavaScript must be included in your page

Default CSS and JavaScript are contained in the jar as resources:

• admonition.css
• admonition.js

Their content is also available by calling AdmonitionExtension.getDefaultCSS() and AdmonitionExtension.getDefaultScript() static methods.

The script should be included at the bottom of the body of the document and is used to toggle open/closed state of collapsible admonition elements.

The following options are available:

Defined in AdmonitionExtension class:

Static Field	Default Value	Description
CONTENT_INDENT	4	indent for child nodes
ALLOW_LEADING_SPACE	true	if non-indenting leading space allowed before opening marker
INTERRUPTS_PARAGRAPH	true	if false then blank line required before
INTERRUPTS_ITEM_PARAGRAPH	true	if false then blank line required before in list items
WITH_SPACES_INTERRUPTS_ITEM_PARAGRAPH	true	whether having a leading non-indenting space requires blank line before in list item
ALLOW_LAZY_CONTINUATION	true	if true then first paragraph can be lazy, otherwise requires content indent
UNRESOLVED_QUALIFIER	"note"	type to use when qualifier is not known
QUALIFIER_TYPE_MAP	see below	mapping of qualifier to type
QUALIFIER_TITLE_MAP	see below	mapping of qualifier to default title, when title is not specified
TYPE_SVG_MAP	see below	mapping of type to svg for the icon

• Default qualifier to type map:

  • abstract: "abstract"
  • summary: "abstract"
  • tldr: "abstract"
  • bug: "bug"
  • danger: "danger"
  • error: "danger"
  • example: "example"
  • snippet: "example"
  • fail: "fail"
  • failure: "fail"
  • missing: "fail"
  • faq: "faq"
  • question: "faq"
  • help: "faq"
  • info: "info"
  • todo: "info"
  • note: "note"
  • seealso: "note"
  • quote: "quote"
  • cite: "quote"
  • success: "success"
  • check: "success"
  • done: "success"
  • tip: "tip"
  • hint: "tip"
  • important: "tip"
  • warning: "warning"
  • caution: "warning"
  • attention: "warning"

• Default qualifier to title map:

  • abstract: "Abstract"
  • summary: "Summary"
  • tldr: "tldr"
  • bug: "Bug"
  • danger: "Danger"
  • error: "Error"
  • example: "Example"
  • snippet: "Snippet"
  • fail: "Fail"
  • failure: "Failure"
  • missing: "Missing"
  • faq: "Faq"
  • question: "Question"
  • help: "Help"
  • info: "Info"
  • todo: "To Do"
  • note: "Note"
  • seealso: "See Also"
  • quote: "Quote"
  • cite: "Cite"
  • success: "Success"
  • check: "Check"
  • done: "Done"
  • tip: "Tip"
  • hint: "Hint"
  • important: "Important"
  • warning: "Warning"
  • caution: "Caution"
  • attention: "Attention"

• Default type to SVG map provides the SVG icon to use for the given type. Default types provided:

  • abstract:
  • bug:
  • danger:
  • example:
  • fail:
  • faq:
  • info:
  • note:
  • success:
  • tip:
  • warning:

  ⚠️ When adding your own SVG icons, make sure you have fill="currentColor" set for the svg, otherwise it will not follow the CSS color for the type.