Skip to content

Commit 62b6682

Browse files
patrickdappolloniopatrickdappollonio
authored
Add Github-style admonitions. (#181)
* Add Github-style admonitions. * Fix indentation. * Fix linter issues.
1 parent 322a529 commit 62b6682

3 files changed

Lines changed: 278 additions & 0 deletions

File tree

‎internal/mdrendering/goldmark_admonitions.go‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
package mdrendering
2+
3+
import (
4+
"bytes"
5+
"strings"
6+
7+
"github.com/yuin/goldmark"
8+
"github.com/yuin/goldmark/ast"
9+
"github.com/yuin/goldmark/parser"
10+
"github.com/yuin/goldmark/renderer"
11+
"github.com/yuin/goldmark/renderer/html"
12+
"github.com/yuin/goldmark/text"
13+
"github.com/yuin/goldmark/util"
14+
)
15+
16+
// KindAdmonition is the NodeKind for our custom admonition block.
17+
var KindAdmonition = ast.NewNodeKind("Admonition")
18+
19+
// Admonition represents a GitHub-style admonition block.
20+
type Admonition struct {
21+
ast.BaseBlock
22+
AdmonitionType string // e.g. "note", "warning", "tip", etc.
23+
}
24+
25+
func (n *Admonition) Kind() ast.NodeKind {
26+
return KindAdmonition
27+
}
28+
29+
func (n *Admonition) Dump(source []byte, level int) {
30+
ast.DumpHelper(n, source, level, map[string]string{"AdmonitionType": n.AdmonitionType}, nil)
31+
}
32+
33+
// ────────────────────────────────────────────────────────────────────────────────
34+
// Parser
35+
// ────────────────────────────────────────────────────────────────────────────────
36+
type admonitionParser struct{}
37+
38+
// NewAdmonitionParser returns a parser that recognizes GitHub-style admonitions.
39+
//
40+
//nolint:ireturn // This interface is required by the goldmark parser.
41+
func NewAdmonitionParser() parser.BlockParser {
42+
return &admonitionParser{}
43+
}
44+
45+
// Trigger implements the BlockParser interface and returns the trigger byte for this parser.
46+
func (b *admonitionParser) Trigger() []byte { return []byte{'>'} }
47+
48+
// Open implements the BlockParser interface and checks if the line starts with "> [!".
49+
//
50+
//nolint:ireturn // This interface is required by the goldmark parser.
51+
func (b *admonitionParser) Open(_ ast.Node, reader text.Reader, _ parser.Context) (ast.Node, parser.State) {
52+
line, seg := reader.PeekLine()
53+
trimmed := bytes.TrimSpace(line)
54+
// Must start with "> [!"
55+
if !bytes.HasPrefix(trimmed, []byte("> [!")) {
56+
return nil, parser.NoChildren
57+
}
58+
end := bytes.IndexByte(trimmed, ']')
59+
if end < 0 {
60+
return nil, parser.NoChildren
61+
}
62+
raw := trimmed[len("> [!"):end]
63+
node := &Admonition{AdmonitionType: strings.ToLower(string(raw))}
64+
reader.Advance(seg.Stop - seg.Start)
65+
return node, parser.HasChildren
66+
}
67+
68+
func (b *admonitionParser) Continue(_ ast.Node, reader text.Reader, _ parser.Context) parser.State {
69+
line, _ := reader.PeekLine()
70+
trimmed := bytes.TrimLeft(line, " \t")
71+
if len(trimmed) > 0 && trimmed[0] == '>' {
72+
return parser.Continue | parser.HasChildren
73+
}
74+
return parser.Close
75+
}
76+
77+
func (b *admonitionParser) Close(_ ast.Node, _ text.Reader, _ parser.Context) {}
78+
func (b *admonitionParser) CanInterruptParagraph() bool { return true }
79+
func (b *admonitionParser) CanAcceptIndentedLine() bool { return false }
80+
81+
// ────────────────────────────────────────────────────────────────────────────────
82+
// AST Transformer
83+
// ────────────────────────────────────────────────────────────────────────────────
84+
type admonitionTransformer struct{}
85+
86+
// NewAdmonitionTransformer returns an ASTTransformer that unwraps nested blockquotes.
87+
//
88+
//nolint:ireturn // This interface is required by the goldmark parser.
89+
func NewAdmonitionTransformer() parser.ASTTransformer {
90+
return &admonitionTransformer{}
91+
}
92+
93+
func (t *admonitionTransformer) Transform(root *ast.Document, _ text.Reader, _ parser.Context) {
94+
ast.Walk(root, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
95+
if !entering {
96+
return ast.WalkContinue, nil
97+
}
98+
adm, ok := n.(*Admonition)
99+
if !ok {
100+
return ast.WalkContinue, nil
101+
}
102+
// unwrap any blockquote children into the admonition
103+
for child := adm.FirstChild(); child != nil; {
104+
next := child.NextSibling()
105+
if bq, isBQ := child.(*ast.Blockquote); isBQ {
106+
for gc := bq.FirstChild(); gc != nil; {
107+
gnext := gc.NextSibling()
108+
bq.RemoveChild(bq, gc)
109+
adm.InsertBefore(adm, child, gc)
110+
gc = gnext
111+
}
112+
adm.RemoveChild(adm, child)
113+
}
114+
child = next
115+
}
116+
return ast.WalkContinue, nil
117+
})
118+
}
119+
120+
// ────────────────────────────────────────────────────────────────────────────────
121+
// Renderer
122+
// ────────────────────────────────────────────────────────────────────────────────
123+
type admonitionHTMLRenderer struct{ html.Config }
124+
125+
// NewAdmonitionHTMLRenderer returns a renderer for our admonition node.
126+
//
127+
//nolint:ireturn // This interface is required by the goldmark parser.
128+
func NewAdmonitionHTMLRenderer(opts ...html.Option) renderer.NodeRenderer {
129+
r := &admonitionHTMLRenderer{Config: html.NewConfig()}
130+
for _, opt := range opts {
131+
opt.SetHTMLOption(&r.Config)
132+
}
133+
return r
134+
}
135+
136+
// SVG icon path constants
137+
const (
138+
noteIconPath = `<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>`
139+
noteIconTip = `<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>`
140+
noteIconImportant = `<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.5a.25.25 0 0 0-.25-.25Zm7 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>`
141+
noteIconWarning = `<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>`
142+
noteIconCaution = `<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 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path>`
143+
)
144+
145+
func (r *admonitionHTMLRenderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer) {
146+
reg.Register(KindAdmonition, r.renderAdmonition)
147+
}
148+
149+
func (r *admonitionHTMLRenderer) renderAdmonition(w util.BufWriter, _ []byte, node ast.Node, entering bool) (ast.WalkStatus, error) {
150+
n := node.(*Admonition)
151+
if entering {
152+
// open admonition wrapper
153+
w.WriteString(`<div class="admonition admonition-` + n.AdmonitionType + `">`)
154+
// title + icon
155+
w.WriteString(`<p class="admonition-title">`)
156+
w.WriteString(`<svg class="admonition-icon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true">`)
157+
// insert appropriate icon constant
158+
switch n.AdmonitionType {
159+
case "note":
160+
w.WriteString(noteIconPath)
161+
case "tip":
162+
w.WriteString(noteIconTip)
163+
case "important":
164+
w.WriteString(noteIconImportant)
165+
case "warning":
166+
w.WriteString(noteIconWarning)
167+
case "caution":
168+
w.WriteString(noteIconCaution)
169+
default:
170+
w.WriteString(noteIconPath)
171+
}
172+
w.WriteString(`</svg>`)
173+
w.WriteString(`<strong>` + uppercaseFirstCharacter(n.AdmonitionType) + `</strong>`)
174+
w.WriteString(`</p>`)
175+
} else {
176+
// close admonition wrapper
177+
w.WriteString(`</div>`)
178+
}
179+
return ast.WalkContinue, nil
180+
}
181+
182+
func uppercaseFirstCharacter(s string) string {
183+
if s == "" {
184+
return s
185+
}
186+
187+
return strings.ToUpper(string(s[0])) + s[1:]
188+
}
189+
190+
// ────────────────────────────────────────────────────────────────────────────────
191+
// Extension
192+
// ────────────────────────────────────────────────────────────────────────────────
193+
type AdmonitionExtension struct{}
194+
195+
func (e *AdmonitionExtension) Extend(m goldmark.Markdown) {
196+
m.Parser().AddOptions(
197+
parser.WithBlockParsers(
198+
util.Prioritized(NewAdmonitionParser(), 100),
199+
),
200+
parser.WithASTTransformers(
201+
util.Prioritized(NewAdmonitionTransformer(), 0),
202+
),
203+
)
204+
m.Renderer().AddOptions(
205+
renderer.WithNodeRenderers(
206+
util.Prioritized(NewAdmonitionHTMLRenderer(), 500),
207+
),
208+
)
209+
}

‎internal/server/assets/gfm.css‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -960,3 +960,71 @@
960960
.markdown-body ::-webkit-calendar-picker-indicator {
961961
filter: invert(50%);
962962
}
963+
964+
.markdown-body .admonition {
965+
border-radius: 6px;
966+
padding: 10px 16px;
967+
padding-left: 16px;
968+
border-left: 4px solid #ccc;
969+
margin-bottom: 16px;
970+
}
971+
972+
.markdown-body .admonition > *:last-child {
973+
margin-bottom: 0;
974+
}
975+
976+
.markdown-body .admonition .admonition-title {
977+
font-weight: 600;
978+
margin-bottom: 8px;
979+
}
980+
981+
.markdown-body .admonition .admonition-title svg {
982+
margin-right: 5px;
983+
margin-bottom: -2px;
984+
fill: currentColor;
985+
}
986+
987+
.markdown-body .admonition.admonition-note {
988+
border-color: #1f6feb;
989+
background-color: #1f6feb0d;
990+
}
991+
992+
.markdown-body .admonition.admonition-note .admonition-title {
993+
color: #1f6feb;
994+
}
995+
996+
.markdown-body .admonition.admonition-tip {
997+
border-color: #238636;
998+
background-color: #2386360d;
999+
}
1000+
1001+
.markdown-body .admonition.admonition-tip .admonition-title {
1002+
color: #238636;
1003+
}
1004+
1005+
.markdown-body .admonition.admonition-important {
1006+
border-color: #8957e5;
1007+
background-color: #8957e50d;
1008+
}
1009+
1010+
.markdown-body .admonition.admonition-important .admonition-title {
1011+
color: #8957e5;
1012+
}
1013+
1014+
.markdown-body .admonition.admonition-warning {
1015+
border-color: #9e6a03;
1016+
background-color: #9e6a030d;
1017+
}
1018+
1019+
.markdown-body .admonition.admonition-warning .admonition-title {
1020+
color: #9e6a03;
1021+
}
1022+
1023+
.markdown-body .admonition.admonition-caution {
1024+
border-color: #da3633;
1025+
background-color: #da36330d;
1026+
}
1027+
1028+
.markdown-body .admonition.admonition-caution .admonition-title {
1029+
color: #da3633;
1030+
}

‎internal/server/markdown.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ func (s *Server) renderMarkdownFile(location string, v *bytes.Buffer) error {
4949
RenderMode: mermaid.RenderModeClient,
5050
MermaidURL: s.assetpath("mermaid-11.6.0.min.js"),
5151
},
52+
&mdrendering.AdmonitionExtension{},
5253
),
5354
goldmark.WithParserOptions(
5455
parser.WithAutoHeadingID(),

0 commit comments

Comments
 (0)