html

Documentation

Overview

Package html implements HTML renderer of parsed markdown document.

Configuring and customizing a renderer

A renderer can be configured with multiple options:

import "github.com/moorara/markdown/render/html"

flags := html.CommonFlags | html.CompletePage | html.HrefTargetBlank
opts := html.RendererOptions{
	TItle: "A custom title",
	Flags: flags,
}
renderer := html.NewRenderer(opts)

You can also re-use most of the logic and customize rendering of selected nodes by providing node render hook. This is most useful for rendering nodes that allow for design choices, like links or code blocks.

import (
	"github.com/moorara/markdown/render/html"
	"github.com/moorara/markdown/ast"
)

// a very dummy render hook that will output "code_replacements" instead of
// <code>${content}</code> emitted by html.Renderer
func renderHookCodeBlock(w io.Writer, node *ast.Node, entering bool) (ast.WalkStatus, bool) {
	_, ok := node.Data.(*ast.CodeBlockData)
	if !ok {
		return ast.GoToNext, false
	}
	io.WriteString(w, "code_replacement")
	return ast.GoToNext, true
}

opts := html.RendererOptions{
	RenderNodeHook: renderHookCodeBlock,
}
renderer := html.NewRenderer(opts)

Index

• Variables
• func BlockAttrs(node ast.Node) []string
• func Escape(w io.Writer, text []byte)
• func EscapeHTML(w io.Writer, d []byte)
• type Flags
• type RenderNodeFunc
• type Renderer
  • func NewRenderer(opts RendererOptions) *Renderer
  • func (r *Renderer) EscapeHTMLCallouts(w io.Writer, d []byte)
  • func (r *Renderer) RenderFooter(w io.Writer, _ ast.Node)
  • func (r *Renderer) RenderHeader(w io.Writer, ast ast.Node)
  • func (r *Renderer) RenderNode(w io.Writer, node ast.Node, entering bool) ast.WalkStatus
• type RendererOptions
• type SPRenderer
  • func NewSmartypantsRenderer(flags Flags) *SPRenderer
  • func (r *SPRenderer) Process(w io.Writer, text []byte)

Variables

var IDTag = "id"

IDTag is the tag used for tag identification, it defaults to "id", some renderers may wish to override this and use e.g. "anchor".

Functions

func BlockAttrs

func BlockAttrs(node ast.Node) []string

BlockAttrs takes a node and checks if it has block level attributes set. If so it will return a slice each containing a "key=value(s)" string.

func Escape

func Escape(w io.Writer, text []byte)

Escape writes the text to w, but skips the escape character.

func EscapeHTML

func EscapeHTML(w io.Writer, d []byte)

EscapeHTML writes html-escaped d to w. It escapes &, <, > and " characters.

Types

type Flags

type Flags int

Flags control optional behavior of HTML renderer.

const (
	FlagsNone               Flags = 0
	SkipHTML                Flags = 1 << iota // Skip preformatted HTML blocks
	SkipImages                                // Skip embedded images
	SkipLinks                                 // Skip all links
	Safelink                                  // Only link to trusted protocols
	NofollowLinks                             // Only link with rel="nofollow"
	NoreferrerLinks                           // Only link with rel="noreferrer"
	NoopenerLinks                             // Only link with rel="noopener"
	HrefTargetBlank                           // Add a blank target
	CompletePage                              // Generate a complete HTML page
	UseXHTML                                  // Generate XHTML output instead of HTML
	FootnoteReturnLinks                       // Generate a link at the end of a footnote to return to the source
	FootnoteNoHRTag                           // Do not output an HR after starting a footnote list.
	Smartypants                               // Enable smart punctuation substitutions
	SmartypantsFractions                      // Enable smart fractions (with Smartypants)
	SmartypantsDashes                         // Enable smart dashes (with Smartypants)
	SmartypantsLatexDashes                    // Enable LaTeX-style dashes (with Smartypants)
	SmartypantsAngledQuotes                   // Enable angled double quotes (with Smartypants) for double quotes rendering
	SmartypantsQuotesNBSP                     // Enable « French guillemets » (with Smartypants)
	TOC                                       // Generate a table of contents

	CommonFlags Flags = Smartypants | SmartypantsFractions | SmartypantsDashes | SmartypantsLatexDashes
)

HTML renderer configuration options.

type RenderNodeFunc

type RenderNodeFunc func(w io.Writer, node ast.Node, entering bool) (ast.WalkStatus, bool)

RenderNodeFunc allows reusing most of Renderer logic and replacing rendering of some nodes. If it returns false, Renderer.RenderNode will execute its logic. If it returns true, Renderer.RenderNode will skip rendering this node and will return WalkStatus

type Renderer

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

Renderer implements Renderer interface for HTML output.

Do not create this directly, instead use the NewRenderer function.

func NewRenderer

func NewRenderer(opts RendererOptions) *Renderer

NewRenderer creates and configures an Renderer object, which satisfies the Renderer interface.

func (*Renderer) EscapeHTMLCallouts

func (r *Renderer) EscapeHTMLCallouts(w io.Writer, d []byte)

EscapeHTMLCallouts writes html-escaped d to w. It escapes &, <, > and " characters, *but* expands callouts <<N>> with the callout HTML, i.e. by calling r.callout() with a newly created ast.Callout node.

func (*Renderer) RenderFooter

func (r *Renderer) RenderFooter(w io.Writer, _ ast.Node)

RenderFooter writes HTML document footer.

func (*Renderer) RenderHeader

func (r *Renderer) RenderHeader(w io.Writer, ast ast.Node)

RenderHeader writes HTML document preamble and TOC if requested.

func (*Renderer) RenderNode

func (r *Renderer) RenderNode(w io.Writer, node ast.Node, entering bool) ast.WalkStatus

RenderNode renders a markdown node to HTML

type RendererOptions

type RendererOptions struct {
	// Prepend this text to each relative URL.
	AbsolutePrefix string
	// Add this text to each footnote anchor, to ensure uniqueness.
	FootnoteAnchorPrefix string
	// Show this text inside the <a> tag for a footnote return link, if the
	// FootnoteReturnLinks flag is enabled. If blank, the string
	// <sup>[return]</sup> is used.
	FootnoteReturnLinkContents string
	// CitationFormatString defines how a citation is rendered. If blnck, the string
	// <sup>[%s]</sup> is used. Where %s will be substituted with the citation target.
	CitationFormatString string
	// If set, add this text to the front of each Heading ID, to ensure uniqueness.
	HeadingIDPrefix string
	// If set, add this text to the back of each Heading ID, to ensure uniqueness.
	HeadingIDSuffix string

	Title string // Document title (used if CompletePage is set)
	CSS   string // Optional CSS file URL (used if CompletePage is set)
	Icon  string // Optional icon file URL (used if CompletePage is set)
	Head  []byte // Optional head data injected in the <head> section (used if CompletePage is set)

	Flags Flags // Flags allow customizing this renderer's behavior

	// if set, called at the start of RenderNode(). Allows replacing
	// rendering of some nodes
	RenderNodeHook RenderNodeFunc

	// Comments is a list of comments the renderer should detect when
	// parsing code blocks and detecting callouts.
	Comments [][]byte

	// Generator is a meta tag that is inserted in the generated HTML so show what rendered it. It should not include the closing tag.
	// Defaults (note content quote is not closed) to `  <meta name="GENERATOR" content="github.com/moorara/markdown markdown processor for Go`
	Generator string
}

RendererOptions is a collection of supplementary parameters tweaking the behavior of various parts of HTML renderer.

type SPRenderer

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

SPRenderer is a struct containing state of a Smarty Pants renderer.

func NewSmartypantsRenderer

func NewSmartypantsRenderer(flags Flags) *SPRenderer

NewSmartypantsRenderer constructs a Smartypants renderer object.

func (*SPRenderer) Process

func (r *SPRenderer) Process(w io.Writer, text []byte)

Process is the entry point of the Smartypants renderer.