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 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 very dummy 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)
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 ¶
View Source
var Escaper = [256][]byte{ '&': []byte("&"), '<': []byte("<"), '>': []byte(">"), '"': []byte("""), }
Escaper maps HTML special characters to their escaped forms.
View Source
var IDTag = "id"
IDTag is the tag used for tag identification. It defaults to "id".
Functions ¶
func AddAbsPrefix ¶
func AddAbsPrefixToImage ¶
func BlockAttrs ¶
BlockAttrs returns the serialized block attributes attached to node.
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 blocks. SkipImages // Skip embedded images. SkipLinks // Render link text without links. Safelink // Link only to trusted protocols. 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.
// 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 ¶
prevVisibleBlock skips siblings that emit no HTML, such as reference definitions, so inter-block spacing stays stable. 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.
Source Files
Click to show internal directories.
Click to hide internal directories.