customblock

README

Goldmark-Customblock

Overview

Goldmark is a fast markdown renderer for Go. Fences are a markdown extension that allows you to wrap parts of a markdown in a <div> or other html-tag with custom classes, ids or other html attributes.

Fences are also called "fenced divs" or "fenced containers." I will use fences because it's the shortest of the available options.

An Example

:::{.blue}
## Life Inside Fences

We are now inside a div with the css-class "blue". This can be used to style this block

:::{#insideme .red data="important"}
fences can be nested and given ids as well as classes
:::
:::

Now add the following css to your stylesheet:

.blue { background-color: steelblue; padding: 5px; }
#insideme { color: yellow; }
.red { background-color: red; }

And the fenced part will look like this (this is an image as github doesn't allow custom css in READMEs):

Full Code Example

A full code example to use the extension with goldmark could look like this:

func main() {
	src := []byte(`
## Hello
We now try out fences:

:::{#big-div .add-border}
This paragraph is inside the fenced block.

This as well.
:::
        `)

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

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

Possible Use Cases

You can use fences to e.g.

• style your output
• wrap semantic units into blocks - e.g. put your toc into one div - which allows you to...
• move parts outside the normal layout - e.g. create a floating toc on the left
• fulfill the requirements of third party libs regarding attributes like data= etc.
• use it for other extensions -- e.g. to wrap all sections in divs for a semantic output structure
• create random html creations

Documentation

Index

• Variables
• func NewFencedContainerParser() parser.BlockParser
• type Config
• type Extender
  • func (e *Extender) Extend(md goldmark.Markdown)
• type FencedContainer
  • func NewFencedContainer() *FencedContainer
  • func (n *FencedContainer) Dump(source []byte, level int)
  • func (n *FencedContainer) Kind() ast.NodeKind
  • func (n *FencedContainer) SetTitle(title string)
• type Renderer
  • func (r *Renderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer)

Variables

var FencedContainerAttributeFilter = html.GlobalAttributeFilter

HeadingAttributeFilter defines attribute names which heading elements can have

var KindFencedContainer = ast.NewNodeKind("FencedContainer")

KindFencedContainer is a NodeKind of the FencedContainer node.

Functions

func NewFencedContainerParser

func NewFencedContainerParser() parser.BlockParser

NewFencedContainerParser returns a new BlockParser that parses fenced code blocks.

Types

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
}

Extender allows you to use fenced divs / fenced containers / fences in markdown

Fences are a way to wrap other elements in divs and giving those divs attributes such as ids or css classes using the same syntax as with headings.

:::{#big-div .add-border} this is some text

## with a header

:::{.background-green .font-big} ```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-fences.Extender

type FencedContainer

type FencedContainer struct {
	ast.BaseBlock

	Title string
	// contains filtered or unexported fields
}

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

func NewFencedContainer

func NewFencedContainer() *FencedContainer

NewFencedContainer return a new FencedContainer node.

func (*FencedContainer) Dump

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

Dump implements Node.Dump .

func (*FencedContainer) Kind

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

Kind implements Node.Kind.

func (*FencedContainer) SetTitle

func (n *FencedContainer) SetTitle(title string)

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 .