Documentation
¶
Overview ¶
Package html implements an HTML renderer of a parsed markdown document.
Configuring and customizing a renderer ¶
A renderer can be configured with multiple options:
import "github.com/gomarkdown/markdown/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 a node render hook. This is most useful for rendering nodes that allow for design choices, like links or code blocks.
import (
"github.com/gomarkdown/markdown/html"
"github.com/gomarkdown/markdown/ast"
)
// a simple render hook that will output "code_replacement" instead of
// <code>${content}</code> emitted by html.Renderer
func renderHookCodeBlock(w io.Writer, node ast.Node, entering bool) (ast.WalkStatus, bool) {
_, ok := node.(*ast.CodeBlock)
if !ok {
return ast.GoToNext, false
}
io.WriteString(w, "code_replacement")
return ast.GoToNext, true
}
opts := html.RendererOptions{
RenderNodeHook: renderHookCodeBlock,
}
renderer := html.NewRenderer(opts)
Untrusted input ¶
For documents you don't trust, set SkipHTML and Safelink:
flags := html.CommonFlags | html.SkipHTML | html.Safelink
SkipHTML removes raw HTML and Safelink only allows http, https, ftp and mailto URLs and relative paths in links and images. With either of them, attributes that a document sets with the parser.Attributes or parser.InlineAttributes extension are limited to id, class, title, lang, dir, role, width, height, align, data-* and aria-*, which can't run script or load anything. A document never replaces an attribute the renderer writes, like the href of a link.
These flags don't make the output safe to show as it is. Use an HTML sanitizer such as github.com/microcosm-cc/bluemonday as well. Render hooks that write attributes with BlockAttrs get all of them, unfiltered.
Index ¶
- Variables
- func AddAbsPrefix(link []byte, prefix string) []byte
- func AddAbsPrefixToImage(link []byte, prefix string) []byte
- func BlockAttrs(node ast.Node) []string
- func EscLink(w io.Writer, text []byte)
- func Escape(w io.Writer, text []byte)
- func EscapeHTML(w io.Writer, d []byte)
- func FootnoteItem(prefix string, slug []byte) string
- func FootnoteRef(prefix string, node *ast.Link) string
- func FootnoteReturnLink(prefix, returnLink string, slug []byte) string
- func HeadingCloseTagFromLevel(level int) string
- func HeadingOpenTagFromLevel(level int) string
- func IsList(node ast.Node) bool
- func IsListItem(node ast.Node) bool
- func IsListItemTerm(node ast.Node) bool
- func IsListTight(node ast.Node) bool
- func ListItemOpenCR(listItem *ast.ListItem) bool
- func SkipParagraphTags(para *ast.Paragraph) bool
- func Slugify(in []byte) []byte
- func TagWithAttributes(name string, attrs []string) string
- type Flags
- type RenderNodeFunc
- type Renderer
- func (r *Renderer) CR(w io.Writer)
- func (r *Renderer) Callout(w io.Writer, node *ast.Callout)
- func (r *Renderer) Caption(w io.Writer, caption *ast.Caption, entering bool)
- func (r *Renderer) CaptionFigure(w io.Writer, figure *ast.CaptionFigure, entering bool)
- func (r *Renderer) Citation(w io.Writer, node *ast.Citation)
- func (r *Renderer) Code(w io.Writer, node *ast.Code)
- func (r *Renderer) CodeBlock(w io.Writer, codeBlock *ast.CodeBlock)
- func (r *Renderer) DocumentMatter(w io.Writer, node *ast.DocumentMatter, entering bool)
- func (r *Renderer) EnsureUniqueHeadingID(id string) string
- func (r *Renderer) EscapeHTMLCallouts(w io.Writer, d []byte)
- func (r *Renderer) HTMLBlock(w io.Writer, node *ast.HTMLBlock)
- func (r *Renderer) HTMLSpan(w io.Writer, span *ast.HTMLSpan)
- func (r *Renderer) HardBreak(w io.Writer, node *ast.Hardbreak)
- func (r *Renderer) Heading(w io.Writer, hdr *ast.Heading, entering bool)
- func (r *Renderer) HeadingEnter(w io.Writer, hdr *ast.Heading)
- func (r *Renderer) HeadingExit(w io.Writer, hdr *ast.Heading)
- func (r *Renderer) HorizontalRule(w io.Writer, node *ast.HorizontalRule)
- func (r *Renderer) Image(w io.Writer, node *ast.Image, entering bool)
- func (r *Renderer) Index(w io.Writer, node *ast.Index)
- func (r *Renderer) Link(w io.Writer, link *ast.Link, entering bool)
- func (r *Renderer) List(w io.Writer, list *ast.List, entering bool)
- func (r *Renderer) ListItem(w io.Writer, listItem *ast.ListItem, entering bool)
- func (r *Renderer) MakeUniqueHeadingID(hdr *ast.Heading) string
- func (r *Renderer) NonBlockingSpace(w io.Writer, node *ast.NonBlockingSpace)
- func (r *Renderer) Out(w io.Writer, d []byte)
- func (r *Renderer) OutHRTag(w io.Writer, attrs []string)
- func (r *Renderer) OutOneOf(w io.Writer, outFirst bool, first string, second string)
- func (r *Renderer) OutOneOfCr(w io.Writer, outFirst bool, first string, second string)
- func (r *Renderer) OutTag(w io.Writer, name string, attrs []string)
- func (r *Renderer) Outs(w io.Writer, s string)
- func (r *Renderer) Paragraph(w io.Writer, para *ast.Paragraph, entering bool)
- func (r *Renderer) RenderFooter(w io.Writer, _ ast.Node)
- func (r *Renderer) RenderHeader(w io.Writer, doc ast.Node)
- func (r *Renderer) RenderNode(w io.Writer, node ast.Node, entering bool) ast.WalkStatus
- func (r *Renderer) TableBody(w io.Writer, node *ast.TableBody, entering bool)
- func (r *Renderer) TableCell(w io.Writer, tableCell *ast.TableCell, entering bool)
- func (r *Renderer) Text(w io.Writer, text *ast.Text)
- type RendererOptions
- type SPRenderer
Constants ¶
This section is empty.
Variables ¶
var Escaper = [256][]byte{ '&': []byte("&"), '<': []byte("<"), '>': []byte(">"), '"': []byte("""), }
Escaper maps HTML special characters to their escaped forms.
var IDTag = "id"
IDTag is the name of the HTML attribute that holds a block attribute's ID. It defaults to "id".
Functions ¶
func AddAbsPrefix ¶
func AddAbsPrefixToImage ¶
func BlockAttrs ¶
BlockAttrs returns the serialized block attributes attached to node.
The renderer itself doesn't write all of them: see Renderer.blockAttrs.
func Escape ¶
Escape writes text while removing Markdown escape backslashes. It doesn't escape HTML: use EscapeHTML for that.
func EscapeHTML ¶
EscapeHTML writes d with HTML special characters escaped.
func FootnoteItem ¶
func FootnoteReturnLink ¶
func HeadingOpenTagFromLevel ¶
func IsListItem ¶
func IsListItemTerm ¶
func IsListTight ¶
func ListItemOpenCR ¶
func SkipParagraphTags ¶
func TagWithAttributes ¶
TagWithAttributes creates an HTML tag with the given name and attributes.
Types ¶
type Flags ¶
type Flags int
Flags control optional behavior of the HTML renderer.
const ( FlagsNone Flags = 0 SkipHTML Flags = 1 << iota // Skip raw HTML, and keep only document attributes that can't run script or load anything. SkipImages // Skip embedded images. SkipLinks // Render link text without links. Safelink // Allow only trusted URL schemes in links and images, and keep only safe document attributes. Doesn't check hosts or sanitize HTML. NofollowLinks // Add rel="nofollow" to external links. NoreferrerLinks // Add rel="noreferrer" to external links. NoopenerLinks // Add rel="noopener" to external links. HrefTargetBlank // Open external links in a new tab. CompletePage // Emit a complete HTML document. UseXHTML // Emit XHTML-compatible singleton tags. FootnoteReturnLinks // Link footnotes back to their references. FootnoteNoHRTag // Omit the rule before footnotes. Smartypants // Enable smart punctuation. SmartypantsFractions // Enable smart fractions. SmartypantsDashes // Enable smart dashes. SmartypantsLatexDashes // Enable LaTeX-style dashes. SmartypantsAngledQuotes // Use angled double quotes. SmartypantsQuotesNBSP // Use French guillemets with nonbreaking spaces. TOC // Generate a table of contents. LazyLoadImages // Add loading="lazy" to images. CommonFlags Flags = Smartypants | SmartypantsFractions | SmartypantsDashes | SmartypantsLatexDashes )
type RenderNodeFunc ¶
RenderNodeFunc can replace the default rendering of selected nodes.
type Renderer ¶
type Renderer struct {
Opts RendererOptions
DisableTags int // Strip tags from Out and Outs when positive.
IsSafeURLOverride func([]byte) bool // Optional safe-URL predicate. Gets the URL as written to the output.
// contains filtered or unexported fields
}
Renderer renders an AST as HTML. Construct one with NewRenderer.
func NewRenderer ¶
func NewRenderer(opts RendererOptions) *Renderer
NewRenderer creates an HTML renderer.
func (*Renderer) CaptionFigure ¶
CaptionFigure writes ast.CaptionFigure node
func (*Renderer) DocumentMatter ¶
DocumentMatter writes ast.DocumentMatter
func (*Renderer) EnsureUniqueHeadingID ¶
func (*Renderer) EscapeHTMLCallouts ¶
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) HorizontalRule ¶
func (r *Renderer) HorizontalRule(w io.Writer, node *ast.HorizontalRule)
HorizontalRule writes ast.HorizontalRule node
func (*Renderer) MakeUniqueHeadingID ¶
func (*Renderer) NonBlockingSpace ¶
func (r *Renderer) NonBlockingSpace(w io.Writer, node *ast.NonBlockingSpace)
NonBlockingSpace writes ast.NonBlockingSpace node
func (*Renderer) OutOneOfCr ¶
OutOneOfCr writes CR + first or second + CR depending on outFirst
func (*Renderer) RenderFooter ¶
RenderFooter writes HTML document footer.
func (*Renderer) RenderHeader ¶
RenderHeader writes HTML document preamble and TOC if requested.
func (*Renderer) RenderNode ¶
RenderNode renders a markdown node to HTML
type RendererOptions ¶
type RendererOptions struct {
AbsolutePrefix string // Prefix for relative URLs.
FootnoteAnchorPrefix string // Prefix for footnote anchors.
FootnoteReturnLinkContents string // HTML inside footnote return links.
CitationFormatString string // fmt string for citation targets.
HeadingIDPrefix string // Prefix for generated heading IDs.
HeadingIDSuffix string // Suffix for generated heading IDs.
ParagraphTag string // Paragraph tag override.
Title string // Complete-page document title.
CSS string // Complete-page stylesheet URL.
Icon string // Complete-page icon URL.
Head []byte // Extra complete-page head markup.
Flags Flags // Optional renderer behavior.
RenderNodeHook RenderNodeFunc // Optional node rendering override.
Comments [][]byte // Code comment markers for callouts.
Generator string // Complete-page generator meta tag.
}
RendererOptions configures HTML rendering.
type SPRenderer ¶
type SPRenderer struct {
// contains filtered or unexported fields
}
SPRenderer is a struct containing state of a Smartypants renderer.
func NewSmartypantsRenderer ¶
func NewSmartypantsRenderer(flags Flags) *SPRenderer
NewSmartypantsRenderer constructs a Smartypants renderer object.