admonitions

README

Goldmark-Admonitions

Overview

Goldmark is a fast markdown renderer for Go. Admonitions are a markdown extension that allows you to style markdown as nice boxes with a title.

An Example

!!!note This is a note
This is the body

## You can use other markdown elements in admonitions!

We are now inside a div with the css-class "adm-body" wrapped inside a div with "admonition" and "adm-note". This can be used to style this block
!!!

!!!danger This a warning
The same as above but instead of "adm-note" you have "adm-danger"
!!!

Now add the css to your stylesheet:

.admonition {
  border: 1px solid black;
  border-radius: 0.25rem;
}

.adm-title {color: #efefef;}
.adm-body {background-color: lightgrey;}

.adm-note .adm-title {background-color: darkblue;}

.adm-danger .adm-title {background-color: darkred;}

If you do that the admonitions will look like this (this is an image as GitHub doesn't allow custom css in READMEs):

Full Example

A full code example that renders to stdout could look like this:

func main() {
  src := []byte(`
## Hello

This is no admonition (no class)

!!!
Not an admonition
!!!

The following is an admonition:

!!!!note 
The body
!!!!

!!! note With title!
The body
!!!

!!!!danger With Attributes!{.otherclass}
The body
!!!!

This is the end.
  `)

  markdown := goldmark.New(
    goldmark.WithExtensions(
      &admonitions.Extender{},
    ),
  )

  doc := markdown.Parser().Parse(text.NewReader(src))
  markdown.Renderer().Render(os.Stdout, src, doc)
}

Indented Style

Instead of opening and closing blocks, i.e.

!!!note This is a note
   
   This is the body
!!!

and this isn't

you can also use indentation for compatibility with markdown-it:

!!!note This is a note
   
   this is the body

and this isn't

Documentation

Index

• Variables
• func NewAdmonitionParser() parser.BlockParser
• type Admonition
  • func NewAdmonition() *Admonition
  • func (n *Admonition) Dump(source []byte, level int)
  • func (n *Admonition) Kind() ast.NodeKind
• type Config
• type Extender
  • func (e *Extender) Extend(md goldmark.Markdown)
• type Renderer
  • func (r *Renderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer)

Variables

var AdmonitionAttributeFilter = html.GlobalAttributeFilter

HeadingAttributeFilter defines attribute names which heading elements can have

var KindAdmonition = ast.NewNodeKind("Admonition")

KindAdmonition is a NodeKind of the Admonition node.

Functions

func NewAdmonitionParser

func NewAdmonitionParser() parser.BlockParser

NewAdmonitionParser returns a new BlockParser that parses admonition blocks.

Types

type Admonition

type Admonition struct {
	ast.BaseBlock
	AdmonitionClass []byte
	Title           []byte
}

A Admonition struct represents a fenced code block of Markdown text.

func NewAdmonition

func NewAdmonition() *Admonition

NewAdmonition return a new Admonition node.

func (*Admonition) Dump

func (n *Admonition) Dump(source []byte, level int)

Dump implements Node.Dump .

func (*Admonition) Kind

func (n *Admonition) Kind() ast.NodeKind

Kind implements Node.Kind.

type Config

type Config struct {
	Writer    html.Writer
	HardWraps bool
	XHTML     bool
	Unsafe    bool
}

A Config struct has configurations for the HTML based renderers.

type Extender

type Extender struct {
	// contains filtered or unexported fields
}

This extender allows you to use admonitions in markdown

Admonitions are a markdown extension that allows you to style markdown as nice boxes with a title. This is done by way of wrapping other elements in divs with classes starting with "adm-"

!!!note This is the title {.some-additional-class} This is the admonition

## with a header

!!!danger Nesting is possible! ```R X <- as.data.table(iris) X[Species != "virginica", mean(Sepal.Length), Species] ``` !!! !!!

func (*Extender) Extend

func (e *Extender) Extend(md goldmark.Markdown)

This implements the Extend method for goldmark-admonitions.Extender

type Renderer

type Renderer struct {
	Config
}

A Renderer struct is an implementation of renderer.NodeRenderer that renders nodes as (X)HTML.

func (*Renderer) RegisterFuncs

func (r *Renderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer)

RegisterFuncs implements NodeRenderer.RegisterFuncs .