README
¶
goldmark-alert
goldmark-alert is a goldmark extension that adds support for Github-style alert blocks in Markdown.
Compatiblity
github.com/yuin/goldmark-alert is compatible with goldmark/v2.
Installation
go get github.com/yuin/goldmark-alert
Usage
import (
"bytes"
"fmt"
"github.com/yuin/goldmark-alert"
"github.com/yuin/goldmark/v2/parser"
"github.com/yuin/goldmark/v2/renderer/html"
)
func main() {
p := parser.New(parser.WithExtensions(alert.Parser)
// p := parser.New(parser.WithExtensions(alert.NewParser(alert.WithAlertKinds("INFO", "TIP"), alert.WithAllowsNested(true))))
r := html.New(html.WithExtensions(alert.HTMLRenderer))
// r := html.New(html.WithExtensions(alert.NewHTMLRenderer(alert.WithIcons(map[string]string{...})))
source := []byte(`# Title
> [!NOTE] Custom title
>
> This is a note.
`)
node := p.Parse((source)
var buf bytes.Buffer
_ := r.Render(&buf, source, node)
}
goldmark-alert supports GitLab alerts custom titles
HTML output for the above example:
<div class="markdown-alert markdown-alert-note">
<p class="markdown-alert-title">
<svg class="markdown-icon markdown-icon-note mr-2" ... ></svg>
Custom title
</p>
<p>This is a note</p>
</div>
Parser options
| Option | Description | Default |
|---|---|---|
alert.WithAlertKinds(kinds ... string) |
Enable info alert blocks | []string{"NOTE", "TIP", "IMPORTANT", "WARNING", "CAUTION"} |
alert.WithAllowsNested(...bool) |
Github does not allow nested alert blocks, but you can enable it | false |
HTML Renderer options
| Option | Description | Default |
|---|---|---|
alert.WithIcons(icons map[string]string) |
Set icons html for each alert kind | default icons |
License
MIT
Author
Yusuke Inuzuka
Documentation
¶
Overview ¶
Package alert provides a goldmark extension for parsing and rendering alert blocks in Markdown.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var GithubAlertIcons = map[string]string{
"NOTE": `<svg
class="markdown-icon markdown-icon-info mr-2"
viewBox="0 0 16 16"
width="16"
height="16"
aria-hidden="true"
>
<path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path>
</svg>`,
"TIP": `<svg class="markdown-icon markdown-icon-tip mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">
<path d="M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z"></path>
</svg>`,
"IMPORTANT": `<svg class="markdown-icon markdown-icon-important mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">
<path d="M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path>
</svg>`,
"WARNING": `<svg class="markdown-icon markdown-icon-warning mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">
<path d="M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path>
</svg>`,
"CAUTION": `<svg class="markdown-icon markdown-icon-caution mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">
<path d="M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5a.75.75 0 0 1 .75-.75Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path>
</svg>`,
}
GithubAlertIcons is a map of the default icons to be used for each alert kind in GitHub Flavored Markdown (GFM).
var GithubAlertKinds = []string{"NOTE", "TIP", "IMPORTANT", "WARNING", "CAUTION"}
GithubAlertKinds is a list of the allowed kinds of alerts in GitHub Flavored Markdown (GFM).
var HTMLRenderer = NewHTMLRenderer()
HTMLRenderer is a default HTML renderer extension for rendering alert blocks in Markdown.
var KindAlert = ast.NewNodeKind("Alert")
KindAlert is a custom AST node kind representing an alert in Markdown.
var Parser = NewParser()
Parser is a default parser extension for handling alert blocks in Markdown.
Functions ¶
func NewHTMLRenderer ¶
func NewHTMLRenderer(opts ...HTMLRendererOption) html.Extension
NewHTMLRenderer creates a new HTML renderer extension for rendering alert blocks in Markdown.
func NewParser ¶
func NewParser(opts ...ParserOption) parser.Extension
NewParser creates a new parser extension for handling alert blocks in Markdown.
Types ¶
type Alert ¶
type Alert struct {
ast.BaseBlock
// AlertKind is the type of alert (e.g., "info", "warning", "error").
//
// Note that this value is not 'normalized'; it is the raw value as provided in the Markdown source.
AlertKind text.SingleLineValue
// Title is the title of the alert, if provided.
//
// If no title is provided, capitization of the Kind is used as the title.
Title text.SingleLineValue
}
Alert is a custom AST node representing an alert in Markdown.
func NewAlert ¶
func NewAlert(kind text.SingleLineValue, opts ...Option) *Alert
NewAlert creates a new Alert node with the specified kind and options.
func (*Alert) DisplayTitle ¶
DisplayTitle returns the title of the alert for display purposes.
type HTMLRendererOption ¶
type HTMLRendererOption func(*htmlRendererConfig)
HTMLRendererOption is a function for configuring the HTML renderer.
func WithAlertIcons ¶
func WithAlertIcons(icons map[string]string) HTMLRendererOption
WithAlertIcons sets the icons to be used for each alert kind in the HTML renderer.
This defaults to GithubAlertIcons. Values are rendered as raw HTML, so they should be valid HTML fragments (e.g., SVG elements, image tags, etc.).
type Option ¶
type Option func(*Alert)
Option is a function for configuring an Alert node.
func WithTitle ¶
func WithTitle(title text.SingleLineValue) Option
WithTitle sets the title of the alert.
type ParserOption ¶
type ParserOption func(*parserConfig)
ParserOption is a function for configuring the parser.
func WithAlertKinds ¶
func WithAlertKinds(kinds ...string) ParserOption
WithAlertKinds sets the allowed kinds of alerts.
This defaults to GithubAlertKinds.
func WithAllowsNested ¶
func WithAllowsNested(allowsNested ...bool) ParserOption
WithAllowsNested enables or disables the ability to nest alerts within other alerts.
This defaults to false.
Source Files