Mercurial > yakumo_izuru > aya

comparison vendor/github.com/Depado/bfchroma/v2/README.md @ 66:787b5ee0289d draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Use vendored modules Signed-off-by: Izuru Yakumo <yakumo.izuru@chaotic.ninja>
author yakumo.izuru
date Sun, 23 Jul 2023 13:18:53 +0000
parents
children
comparison
equal deleted inserted replaced
65:6d985efa0f7a 66:787b5ee0289d
1 # bfchroma
2
3 [![forthebadge](https://forthebadge.com/images/badges/made-with-go.svg)](https://forthebadge.com)[![forthebadge](https://forthebadge.com/images/badges/built-with-love.svg)](https://forthebadge.com)
4
5 [![Go Report Card](https://goreportcard.com/badge/github.com/Depado/bfchroma)](https://goreportcard.com/report/github.com/Depado/bfchroma)
6 [![Build Status](https://drone.depa.do/api/badges/Depado/bfchroma/status.svg)](https://drone.depa.do/Depado/bfchroma)
7 [![codecov](https://codecov.io/gh/Depado/bfchroma/branch/master/graph/badge.svg)](https://codecov.io/gh/Depado/bfchroma)
8 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Depado/bfchroma/blob/master/LICENSE)
9 [![Godoc](https://godoc.org/github.com/Depado/bfchroma?status.svg)](https://godoc.org/github.com/Depado/bfchroma)
10 [![Sourcegraph](https://sourcegraph.com/github.com/Depado/bfchroma/-/badge.svg)](https://sourcegraph.com/github.com/Depado/bfchroma?badge)
11 [![Say Thanks!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/Depado)
12
13
14 Integrating [Chroma](https://github.com/alecthomas/chroma) syntax highlighter as
15 a [Blackfriday](https://github.com/russross/blackfriday) renderer.
16
17 ## Install and prerequisites
18
19 This project requires and uses the `v2` version of
20 [Blackfriday](https://github.com/russross/blackfriday/tree/v2).
21
22 ```
23 $ go get github.com/Depado/bfchroma
24 ```
25
26 ## Features
27
28 This renderer integrates chroma to highlight code with triple backtick notation.
29 It will try to use the given language when available otherwise it will try to
30 detect the language. If none of these two method works it will fallback to sane
31 defaults.
32
33 ## Usage
34
35 bfchroma uses the functional options approach so you can customize the behavior
36 of the renderer. It uses sane defaults when no option is passed so you can use
37 the renderer simply by doing so :
38
39 ```go
40 html := bf.Run([]byte(md), bf.WithRenderer(bfchroma.NewRenderer()))
41 ```
42
43 ### Options
44
45 - `Style(s string)`
46 Define the style used by chroma for the rendering. The full list can be found [here](https://github.com/alecthomas/chroma/tree/master/styles)
47 - `ChromaStyle(*chroma.Style)`
48 This option can be used to passe directly a `*chroma.Style` instead of the
49 string representing the style as with the `Style(string)` option.
50 - `WithoutAutodetect()`
51 By default when no language information is written in the code block, this
52 renderer will try to auto-detect the used language. This option disables
53 this behavior and will fallback to a sane default when no language
54 information is available.
55 - `EmbedCSS()`
56 This option will embed CSS needed for chroma's `html.WithClasses()` at the beginning of blackfriday document.
57 CSS can also be extracted separately by calling `Renderer`'s.`ChromaCSS(w)` method, which will return styleshet for currently set style
58 - `Extend(bf.Renderer)`
59 This option allows to define the base blackfriday that will be extended.
60 - `ChromaOptions(...html.Option)`
61 This option allows you to pass Chroma's html options in the renderer. Such
62 options can be found [here](https://github.com/alecthomas/chroma#the-html-formatter).
63
64 ### Option examples
65
66 Disabling language auto-detection and displaying line numbers
67
68 ```go
69 r := bfchroma.NewRenderer(
70 bfchroma.WithoutAutodetect(),
71 bfchroma.ChromaOptions(html.WithLineNumbers()),
72 )
73 ```
74
75 Extend a blackfriday renderer
76
77 ```go
78 b := bf.NewHTMLRenderer(bf.HTMLRendererParameters{
79 Flags: bf.CommonHTMLFlags,
80 })
81
82 r := bfchroma.NewRenderer(bfchroma.Extend(b))
83 ```
84
85 Use a different style
86
87 ```go
88 r := bfchroma.NewRenderer(bfchroma.Style("dracula"))
89 // Or
90 r = bfchroma.NewRenderer(bfchroma.ChromaStyle(styles.Dracula))
91 ```
92
93
94
95 ## Examples
96
97 ```go
98 package main
99
100 import (
101 "fmt"
102
103 "github.com/Depado/bfchroma"
104
105 bf "github.com/russross/blackfriday/v2"
106 )
107
108 var md = "This is some sample code.\n\n```go\n" +
109 `func main() {
110 fmt.Println("Hi")
111 }
112 ` + "```"
113
114 func main() {
115 html := bf.Run([]byte(md), bf.WithRenderer(bfchroma.NewRenderer()))
116 fmt.Println(string(html))
117 }
118 ```
119
120
121 Will output :
122
123 ```html
124 <p>This is some sample code.</p>
125 <pre style="color:#f8f8f2;background-color:#272822"><span style="color:#66d9ef">func</span> <span style="color:#a6e22e">main</span>() {
126 <span style="color:#a6e22e">fmt</span>.<span style="color:#a6e22e">Println</span>(<span style="color:#e6db74">&#34;Hi&#34;</span>)
127 }
128 </pre>
129 ```
130
131 ## Real-life example
132
133 In [smallblog](https://github.com/Depado/smallblog) I'm using bfchroma to render
134 my articles. It's using a combination of both bfchroma's options and blackfriday
135 extensions and flags.
136
137 ```go
138 package main
139
140 import (
141 "github.com/Depado/bfchroma"
142 "github.com/alecthomas/chroma/formatters/html"
143 bf "github.com/russross/blackfriday/v2"
144 )
145
146 // Defines the extensions that are used
147 var exts = bf.NoIntraEmphasis | bf.Tables | bf.FencedCode | bf.Autolink |
148 bf.Strikethrough | bf.SpaceHeadings | bf.BackslashLineBreak |
149 bf.DefinitionLists | bf.Footnotes
150
151 // Defines the HTML rendering flags that are used
152 var flags = bf.UseXHTML | bf.Smartypants | bf.SmartypantsFractions |
153 bf.SmartypantsDashes | bf.SmartypantsLatexDashes | bf.TOC
154
155 // render will take a []byte input and will render it using a new renderer each
156 // time because reusing the same can mess with TOC and header IDs
157 func render(input []byte) []byte {
158 return bf.Run(
159 input,
160 bf.WithRenderer(
161 bfchroma.NewRenderer(
162 bfchroma.WithoutAutodetect(),
163 bfchroma.ChromaOptions(
164 html.WithLineNumbers(),
165 ),
166 bfchroma.Extend(
167 bf.NewHTMLRenderer(bf.HTMLRendererParameters{
168 Flags: flags,
169 }),
170 ),
171 ),
172 ),
173 bf.WithExtensions(exts),
174 )
175 }
176 ```
177
178 ## Classes
179
180 If you have loads of code in your markdown, you might want to consider using
181 `html.WithClasses()` in your `bfchroma.ChromaOptions()`. The CSS of the style
182 you chose can then be accessed like this :
183
184 ```go
185 r := bfchroma.NewRenderer(
186 bfchroma.WithoutAutodetect(),
187 bfchroma.Extend(
188 bf.NewHTMLRenderer(bf.HTMLRendererParameters{Flags: flags}),
189 ),
190 bfchroma.Style("monokai"),
191 bfchroma.ChromaOptions(html.WithClasses()),
192 )
193
194 var css template.CSS
195
196 b := new(bytes.Buffer)
197 if err := r.ChromaCSS(b); err != nil {
198 logrus.WithError(err).Warning("Couldn't write CSS")
199 }
200 css = template.CSS(b.String())
201
202 bf.Run(input, bf.WithRenderer(r), bf.WithExtensions(exts))
203 ```
204
205 This way, you can pass your `css` var to any template and render it along the
206 rendered markdown.