This is some sample code.
123 |func main() { 124 | fmt.Println("Hi") 125 | } 126 |127 | ``` 128 | 129 | ## Real-life example 130 | 131 | In [smallblog](https://github.com/Depado/smallblog) I'm using bfchroma to render 132 | my articles. It's using a combination of both bfchroma's options and blackfriday 133 | extensions and flags. 134 | 135 | ```go 136 | package main 137 | 138 | import ( 139 | "github.com/Depado/bfchroma/v2" 140 | 141 | "github.com/alecthomas/chroma/v2/formatters/html" 142 | bf "github.com/russross/blackfriday/v2" 143 | ) 144 | 145 | // Defines the extensions that are used 146 | var exts = bf.NoIntraEmphasis | bf.Tables | bf.FencedCode | bf.Autolink | 147 | bf.Strikethrough | bf.SpaceHeadings | bf.BackslashLineBreak | 148 | bf.DefinitionLists | bf.Footnotes 149 | 150 | // Defines the HTML rendering flags that are used 151 | var flags = bf.UseXHTML | bf.Smartypants | bf.SmartypantsFractions | 152 | bf.SmartypantsDashes | bf.SmartypantsLatexDashes | bf.TOC 153 | 154 | // render will take a []byte input and will render it using a new renderer each 155 | // time because reusing the same can mess with TOC and header IDs 156 | func render(input []byte) []byte { 157 | return bf.Run( 158 | input, 159 | bf.WithRenderer( 160 | bfchroma.NewRenderer( 161 | bfchroma.WithoutAutodetect(), 162 | bfchroma.ChromaOptions( 163 | html.WithLineNumbers(), 164 | ), 165 | bfchroma.Extend( 166 | bf.NewHTMLRenderer(bf.HTMLRendererParameters{ 167 | Flags: flags, 168 | }), 169 | ), 170 | ), 171 | ), 172 | bf.WithExtensions(exts), 173 | ) 174 | } 175 | ``` 176 | 177 | ## Classes 178 | 179 | If you have loads of code in your markdown, you might want to consider using 180 | `html.WithClasses()` in your `bfchroma.ChromaOptions()`. The CSS of the style 181 | you chose can then be accessed like this : 182 | 183 | ```go 184 | r := bfchroma.NewRenderer( 185 | bfchroma.WithoutAutodetect(), 186 | bfchroma.Extend( 187 | bf.NewHTMLRenderer(bf.HTMLRendererParameters{Flags: flags}), 188 | ), 189 | bfchroma.Style("monokai"), 190 | bfchroma.ChromaOptions(html.WithClasses()), 191 | ) 192 | 193 | var css template.CSS 194 | 195 | b := new(bytes.Buffer) 196 | if err := r.ChromaCSS(b); err != nil { 197 | logrus.WithError(err).Warning("Couldn't write CSS") 198 | } 199 | css = template.CSS(b.String()) 200 | 201 | bf.Run(input, bf.WithRenderer(r), bf.WithExtensions(exts)) 202 | ``` 203 | 204 | This way, you can pass your `css` var to any template and render it along the 205 | rendered markdown. 206 | -------------------------------------------------------------------------------- /_example/main.go: -------------------------------------------------------------------------------- 1 | package main 2 | 3 | import ( 4 | "fmt" 5 | 6 | "github.com/Depado/bfchroma" 7 | "github.com/alecthomas/chroma/v2/formatters/html" 8 | 9 | bf "github.com/russross/blackfriday/v2" 10 | ) 11 | 12 | var md = "This is some sample code.\n\n```go\n" + 13 | `func main() { 14 | fmt.Println("Hi") 15 | } 16 | ` + "```" 17 | 18 | func main() { 19 | var r *bfchroma.Renderer 20 | var h []byte 21 | 22 | // Basic usage 23 | r = bfchroma.NewRenderer() 24 | h = bf.Run([]byte(md), bf.WithRenderer(r)) 25 | fmt.Println(string(h)) 26 | 27 | // Option examples and extending a specific blackfriday renderer 28 | b := bf.NewHTMLRenderer(bf.HTMLRendererParameters{ 29 | Flags: bf.CommonHTMLFlags, 30 | }) 31 | r = bfchroma.NewRenderer( 32 | bfchroma.WithoutAutodetect(), 33 | bfchroma.Extend(b), 34 | bfchroma.ChromaOptions(html.WithLineNumbers(true)), 35 | ) 36 | h = bf.Run([]byte(md), bf.WithRenderer(r)) 37 | fmt.Println(string(h)) 38 | 39 | md := "```\npackage main\n\nfunc main() {\n}\n```" 40 | r = bfchroma.NewRenderer(bfchroma.WithoutAutodetect()) 41 | h = bf.Run([]byte(md), bf.WithRenderer(r)) 42 | fmt.Println(string(h)) 43 | 44 | md = "```go\npackage main\n\nfunc main() {\n}\n```" 45 | r = bfchroma.NewRenderer(bfchroma.ChromaOptions(html.WithLineNumbers(true))) 46 | h = bf.Run([]byte(md), bf.WithRenderer(r)) 47 | fmt.Println(string(h)) 48 | } 49 | -------------------------------------------------------------------------------- /go.mod: -------------------------------------------------------------------------------- 1 | module github.com/Depado/bfchroma/v2 2 | 3 | go 1.23 4 | 5 | require ( 6 | github.com/alecthomas/chroma/v2 v2.18.0 7 | github.com/russross/blackfriday/v2 v2.1.0 8 | github.com/stretchr/testify v1.10.0 9 | ) 10 | 11 | require ( 12 | github.com/davecgh/go-spew v1.1.1 // indirect 13 | github.com/dlclark/regexp2 v1.11.5 // indirect 14 | github.com/pmezard/go-difflib v1.0.0 // indirect 15 | gopkg.in/yaml.v3 v3.0.1 // indirect 16 | ) 17 | -------------------------------------------------------------------------------- /go.sum: -------------------------------------------------------------------------------- 1 | github.com/alecthomas/assert/v2 v2.11.0 h1:2Q9r3ki8+JYXvGsDyBXwH3LcJ+WK5D0gc5E8vS6K3D0= 2 | github.com/alecthomas/assert/v2 v2.11.0/go.mod h1:Bze95FyfUr7x34QZrjL+XP+0qgp/zg8yS+TtBj1WA3k= 3 | github.com/alecthomas/chroma/v2 v2.15.0 h1:LxXTQHFoYrstG2nnV9y2X5O94sOBzf0CIUpSTbpxvMc= 4 | github.com/alecthomas/chroma/v2 v2.15.0/go.mod h1:gUhVLrPDXPtp/f+L1jo9xepo9gL4eLwRuGAunSZMkio= 5 | github.com/alecthomas/chroma/v2 v2.16.0 h1:QC5ZMizk67+HzxFDjQ4ASjni5kWBTGiigRG1u23IGvA= 6 | github.com/alecthomas/chroma/v2 v2.16.0/go.mod h1:RVX6AvYm4VfYe/zsk7mjHueLDZor3aWCNE14TFlepBk= 7 | github.com/alecthomas/chroma/v2 v2.17.0 h1:3r2Cgk+nXNICMBxIFGnTRTbQFUwMiLisW+9uos0TtUI= 8 | github.com/alecthomas/chroma/v2 v2.17.0/go.mod h1:RVX6AvYm4VfYe/zsk7mjHueLDZor3aWCNE14TFlepBk= 9 | github.com/alecthomas/chroma/v2 v2.17.2 h1:Rm81SCZ2mPoH+Q8ZCc/9YvzPUN/E7HgPiPJD8SLV6GI= 10 | github.com/alecthomas/chroma/v2 v2.17.2/go.mod h1:RVX6AvYm4VfYe/zsk7mjHueLDZor3aWCNE14TFlepBk= 11 | github.com/alecthomas/chroma/v2 v2.18.0 h1:6h53Q4hW83SuF+jcsp7CVhLsMozzvQvO8HBbKQW+gn4= 12 | github.com/alecthomas/chroma/v2 v2.18.0/go.mod h1:RVX6AvYm4VfYe/zsk7mjHueLDZor3aWCNE14TFlepBk= 13 | github.com/alecthomas/repr v0.4.0 h1:GhI2A8MACjfegCPVq9f1FLvIBS+DrQ2KQBFZP1iFzXc= 14 | github.com/alecthomas/repr v0.4.0/go.mod h1:Fr0507jx4eOXV7AlPV6AVZLYrLIuIeSOWtW57eE/O/4= 15 | github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= 16 | github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= 17 | github.com/dlclark/regexp2 v1.11.4 h1:rPYF9/LECdNymJufQKmri9gV604RvvABwgOA8un7yAo= 18 | github.com/dlclark/regexp2 v1.11.4/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8= 19 | github.com/dlclark/regexp2 v1.11.5 h1:Q/sSnsKerHeCkc/jSTNq1oCm7KiVgUMZRDUoRu0JQZQ= 20 | github.com/dlclark/regexp2 v1.11.5/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8= 21 | github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUqJM= 22 | github.com/hexops/gotextdiff v1.0.3/go.mod h1:pSWU5MAI3yDq+fZBTazCSJysOMbxWL1BSow5/V2vxeg= 23 | github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= 24 | github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= 25 | github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk= 26 | github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= 27 | github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA= 28 | github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= 29 | gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= 30 | gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= 31 | gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= 32 | gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= 33 | -------------------------------------------------------------------------------- /renderer.go: -------------------------------------------------------------------------------- 1 | // Package bfchroma provides an easy and extensible blackfriday renderer that 2 | // uses the chroma syntax highlighter to render code blocks. 3 | package bfchroma 4 | 5 | import ( 6 | "io" 7 | 8 | "github.com/alecthomas/chroma/v2" 9 | "github.com/alecthomas/chroma/v2/formatters/html" 10 | "github.com/alecthomas/chroma/v2/lexers" 11 | "github.com/alecthomas/chroma/v2/styles" 12 | bf "github.com/russross/blackfriday/v2" 13 | ) 14 | 15 | // Option defines the functional option type 16 | type Option func(r *Renderer) 17 | 18 | // Style is a function option allowing to set the style used by chroma 19 | // Default : "monokai" 20 | func Style(s string) Option { 21 | return func(r *Renderer) { 22 | r.Style = styles.Get(s) 23 | } 24 | } 25 | 26 | // ChromaStyle is an option to directly set the style of the renderer using a 27 | // chroma style instead of a string 28 | func ChromaStyle(s *chroma.Style) Option { 29 | return func(r *Renderer) { 30 | r.Style = s 31 | } 32 | } 33 | 34 | // WithoutAutodetect disables chroma's language detection when no codeblock 35 | // extra information is given. It will fallback to a sane default instead of 36 | // trying to detect the language. 37 | func WithoutAutodetect() Option { 38 | return func(r *Renderer) { 39 | r.Autodetect = false 40 | } 41 | } 42 | 43 | // EmbedCSS will embed CSS needed for html.WithClasses() in beginning of the document 44 | func EmbedCSS() Option { 45 | return func(r *Renderer) { 46 | r.embedCSS = true 47 | } 48 | } 49 | 50 | // ChromaOptions allows to pass Chroma html.Option such as Standalone() 51 | // WithClasses(), ClassPrefix(prefix)... 52 | func ChromaOptions(options ...html.Option) Option { 53 | return func(r *Renderer) { 54 | r.ChromaOptions = options 55 | } 56 | } 57 | 58 | // Extend allows to specify the blackfriday renderer which is extended 59 | func Extend(br bf.Renderer) Option { 60 | return func(r *Renderer) { 61 | r.Base = br 62 | } 63 | } 64 | 65 | // NewRenderer will return a new bfchroma renderer with sane defaults 66 | func NewRenderer(options ...Option) *Renderer { 67 | r := &Renderer{ 68 | Base: bf.NewHTMLRenderer(bf.HTMLRendererParameters{ 69 | Flags: bf.CommonHTMLFlags, 70 | }), 71 | Style: styles.Get("monokai"), 72 | Autodetect: true, 73 | } 74 | for _, option := range options { 75 | option(r) 76 | } 77 | r.Formatter = html.New(r.ChromaOptions...) 78 | return r 79 | } 80 | 81 | // RenderWithChroma will render the given text to the w io.Writer 82 | func (r *Renderer) RenderWithChroma(w io.Writer, text []byte, data bf.CodeBlockData) error { 83 | var lexer chroma.Lexer 84 | 85 | // Determining the lexer to use 86 | if len(data.Info) > 0 { 87 | lexer = lexers.Get(string(data.Info)) 88 | } else if r.Autodetect { 89 | lexer = lexers.Analyse(string(text)) 90 | } 91 | if lexer == nil { 92 | lexer = lexers.Fallback 93 | } 94 | 95 | // Tokenize the code 96 | iterator, err := lexer.Tokenise(nil, string(text)) 97 | if err != nil { 98 | return err 99 | } 100 | return r.Formatter.Format(w, r.Style, iterator) 101 | } 102 | 103 | // Renderer is a custom Blackfriday renderer that uses the capabilities of 104 | // chroma to highlight code with triple backtick notation 105 | type Renderer struct { 106 | Base bf.Renderer 107 | Autodetect bool 108 | ChromaOptions []html.Option 109 | Style *chroma.Style 110 | Formatter *html.Formatter 111 | embedCSS bool 112 | } 113 | 114 | // RenderNode satisfies the Renderer interface 115 | func (r *Renderer) RenderNode(w io.Writer, node *bf.Node, entering bool) bf.WalkStatus { 116 | switch node.Type { 117 | case bf.Document: 118 | if entering && r.embedCSS { 119 | w.Write([]byte("")) // nolint: errcheck 122 | } 123 | return r.Base.RenderNode(w, node, entering) 124 | case bf.CodeBlock: 125 | if err := r.RenderWithChroma(w, node.Literal, node.CodeBlockData); err != nil { 126 | return r.Base.RenderNode(w, node, entering) 127 | } 128 | return bf.SkipChildren 129 | default: 130 | return r.Base.RenderNode(w, node, entering) 131 | } 132 | } 133 | 134 | // RenderHeader satisfies the Renderer interface 135 | func (r *Renderer) RenderHeader(w io.Writer, ast *bf.Node) { 136 | r.Base.RenderHeader(w, ast) 137 | } 138 | 139 | // RenderFooter satisfies the Renderer interface 140 | func (r *Renderer) RenderFooter(w io.Writer, ast *bf.Node) { 141 | r.Base.RenderFooter(w, ast) 142 | } 143 | 144 | // ChromaCSS returns CSS used with chroma's html.WithClasses() option 145 | func (r *Renderer) ChromaCSS(w io.Writer) error { 146 | return r.Formatter.WriteCSS(w, r.Style) 147 | } 148 | -------------------------------------------------------------------------------- /renderer_test.go: -------------------------------------------------------------------------------- 1 | package bfchroma 2 | 3 | import ( 4 | "bytes" 5 | "fmt" 6 | "testing" 7 | 8 | "github.com/alecthomas/chroma/v2" 9 | "github.com/alecthomas/chroma/v2/formatters/html" 10 | "github.com/alecthomas/chroma/v2/styles" 11 | bf "github.com/russross/blackfriday/v2" 12 | "github.com/stretchr/testify/assert" 13 | "github.com/stretchr/testify/require" 14 | ) 15 | 16 | func TestExtend(t *testing.T) { 17 | var b bf.Renderer 18 | var r *Renderer 19 | b = bf.NewHTMLRenderer(bf.HTMLRendererParameters{ 20 | Flags: bf.CommonHTMLFlags, 21 | }) 22 | r = NewRenderer(Extend(b)) 23 | assert.Equal(t, r.Base, b, "should be the same renderer") 24 | } 25 | 26 | func ExampleExtend() { 27 | md := "```go\npackage main\n\nfunc main() {\n}\n```" 28 | 29 | b := bf.NewHTMLRenderer(bf.HTMLRendererParameters{ 30 | Flags: bf.CommonHTMLFlags, 31 | }) 32 | r := NewRenderer(Extend(b)) 33 | 34 | h := bf.Run([]byte(md), bf.WithRenderer(r)) 35 | fmt.Println(string(h)) 36 | } 37 | 38 | func TestStyle(t *testing.T) { 39 | var r *Renderer 40 | for k, v := range styles.Registry { 41 | r = NewRenderer(Style(k)) 42 | assert.Equal(t, r.Style, v, "Style should match") 43 | } 44 | for _, v := range []string{"♥", "inexistent", "fallback!"} { 45 | r = NewRenderer(Style(v)) 46 | assert.Equal(t, r.Style, styles.Fallback) 47 | } 48 | } 49 | 50 | func ExampleStyle() { 51 | md := "```go\npackage main\n\nfunc main() {\n}\n```" 52 | 53 | r := NewRenderer(Style("github")) 54 | 55 | h := bf.Run([]byte(md), bf.WithRenderer(r)) 56 | fmt.Println(string(h)) 57 | } 58 | 59 | func TestChromaStyle(t *testing.T) { 60 | var r *Renderer 61 | for _, v := range styles.Registry { 62 | r = NewRenderer(ChromaStyle(v)) 63 | assert.Equal(t, r.Style, v, "Style should match") 64 | } 65 | } 66 | 67 | func ExampleChromaStyle() { 68 | md := "```go\npackage main\n\nfunc main() {\n}\n```" 69 | 70 | r := NewRenderer(ChromaStyle(styles.Get("github"))) 71 | 72 | h := bf.Run([]byte(md), bf.WithRenderer(r)) 73 | fmt.Println(string(h)) 74 | } 75 | 76 | func TestWithoutAutodetect(t *testing.T) { 77 | r := NewRenderer(WithoutAutodetect()) 78 | assert.False(t, r.Autodetect, "Should set Autodetect to false") 79 | r = NewRenderer() 80 | assert.True(t, r.Autodetect, "Not using option should leave Autodetect to true") 81 | } 82 | 83 | func ExampleWithoutAutodetect() { 84 | md := "```\npackage main\n\nfunc main() {\n}\n```" 85 | 86 | r := NewRenderer(WithoutAutodetect()) 87 | 88 | h := bf.Run([]byte(md), bf.WithRenderer(r)) 89 | fmt.Println(string(h)) 90 | } 91 | 92 | func TestChromaOptions(t *testing.T) { 93 | NewRenderer(ChromaOptions(html.WithClasses(true))) 94 | } 95 | 96 | func ExampleChromaOptions() { 97 | md := "```go\npackage main\n\nfunc main() {\n}\n```" 98 | 99 | r := NewRenderer(ChromaOptions(html.WithLineNumbers(true))) 100 | 101 | h := bf.Run([]byte(md), bf.WithRenderer(r)) 102 | fmt.Println(string(h)) 103 | } 104 | 105 | func TestRenderWithChroma(t *testing.T) { 106 | var err error 107 | var b *bytes.Buffer 108 | r := NewRenderer() 109 | tests := []struct { 110 | in []byte 111 | cbd bf.CodeBlockData 112 | out string 113 | }{ 114 | {[]byte{0}, bf.CodeBlockData{}, "
\x00\x00\x01\x02Hello World