github.com/graemephi/kahugo@v0.62.3-0.20211121071557-d78c0423784d/README.md (about) 1 # KaHugo 2 3 KaHugo is a fork of Hugo to add server-side [KaTeX](https://katex.org) mathematics rendering, with [a goldmark extension](https://github.com/graemephi/goldmark-qjs-katex). Markdown like this: 4 5 ```markdown 6 $x$ 7 8 $$ 9 x 10 $$ 11 ``` 12 13 gets rendered as this: 14 ```html 15 <p><span class="katex">...</span></p> 16 <p><span class="katex-display">...</span></p> 17 ``` 18 19 You still need to include the KaTeX CSS in your HTML templates. 20 21 ## Config 22 ``` 23 [markup.goldmark.katex] 24 enabled = true 25 warnings = false 26 ``` 27 28 ## Building 29 30 Like the Hugo extended build, you need cgo. 31 ``` 32 go build 33 ``` 34 35 ## Changes 36 The changes are pretty small, so here's a complete diff of the repo, minus go.mod, go.sum and this readme. 37 38 ```diff 39 diff --git a/markup/goldmark/convert.go b/markup/goldmark/convert.go 40 index d4c3533..b94087e 100644 41 --- a/markup/goldmark/convert.go 42 +++ b/markup/goldmark/convert.go 43 @@ -39,6 +39,8 @@ import ( 44 "github.com/yuin/goldmark/renderer/html" 45 "github.com/yuin/goldmark/text" 46 "github.com/yuin/goldmark/util" 47 + 48 + "github.com/graemephi/goldmark-qjs-katex" 49 ) 50 51 // Provider is the package entry point. 52 @@ -143,6 +145,10 @@ func newMarkdown(pcfg converter.ProviderConfig) goldmark.Markdown { 53 parserOptions = append(parserOptions, parser.WithAttribute()) 54 } 55 56 + if cfg.Katex.Enable { 57 + extensions = append(extensions, &qjskatex.Extension{EnableWarnings: cfg.Katex.Warnings}) 58 + } 59 + 60 md := goldmark.New( 61 goldmark.WithExtensions( 62 extensions..., 63 diff --git a/markup/goldmark/goldmark_config/config.go b/markup/goldmark/goldmark_config/config.go 64 index af33e03..f4d9a10 100644 65 --- a/markup/goldmark/goldmark_config/config.go 66 +++ b/markup/goldmark/goldmark_config/config.go 67 @@ -39,6 +39,10 @@ var Default = Config{ 68 AutoHeadingIDType: AutoHeadingIDTypeGitHub, 69 Attribute: true, 70 }, 71 + Katex: Katex{ 72 + Enable: true, 73 + Warnings: false, 74 + }, 75 } 76 77 // Config configures Goldmark. 78 @@ -46,6 +50,7 @@ type Config struct { 79 Renderer Renderer 80 Parser Parser 81 Extensions Extensions 82 + Katex Katex 83 } 84 85 type Extensions struct { 86 @@ -84,3 +89,10 @@ type Parser struct { 87 // Enables custom attributes. 88 Attribute bool 89 } 90 + 91 +type Katex struct { 92 + // Enable the Katex extension. 93 + Enable bool 94 + // Enables warnings. 95 + Warnings bool 96 +} 97 ``` 98 ## Additional Dependencies 99 100 | Dependency | License | 101 | :------------- | :------------- | 102 | [katex.org](https://katex.org/) | MIT License | 103 | [bellard.org/quickjs](https://bellard.org/quickjs/) | MIT License | 104 105 # Original Hugo Readme 106 <a href="https://gohugo.io/"><img src="https://raw.githubusercontent.com/gohugoio/gohugoioTheme/master/static/images/hugo-logo-wide.svg?sanitize=true" alt="Hugo" width="565"></a> 107 108 A Fast and Flexible Static Site Generator built with love by [bep](https://github.com/bep), [spf13](http://spf13.com/) and [friends](https://github.com/gohugoio/hugo/graphs/contributors) in [Go][]. 109 110 [Website](https://gohugo.io) | 111 [Forum](https://discourse.gohugo.io) | 112 [Documentation](https://gohugo.io/getting-started/) | 113 [Installation Guide](https://gohugo.io/getting-started/installing/) | 114 [Contribution Guide](CONTRIBUTING.md) | 115 [Twitter](https://twitter.com/gohugoio) 116 117 [](https://godoc.org/github.com/gohugoio/hugo) 118 [](https://github.com/gohugoio/hugo/actions?query=workflow%3ATest) 119 [](https://goreportcard.com/report/github.com/gohugoio/hugo) 120 121 ## Overview 122 123 Hugo is a static HTML and CSS website generator written in [Go][]. 124 It is optimized for speed, ease of use, and configurability. 125 Hugo takes a directory with content and templates and renders them into a full HTML website. 126 127 Hugo relies on Markdown files with front matter for metadata, and you can run Hugo from any directory. 128 This works well for shared hosts and other systems where you don’t have a privileged account. 129 130 Hugo renders a typical website of moderate size in a fraction of a second. 131 A good rule of thumb is that each piece of content renders in around 1 millisecond. 132 133 Hugo is designed to work well for any kind of website including blogs, tumbles, and docs. 134 135 #### Supported Architectures 136 137 Currently, we provide pre-built Hugo binaries for Windows, Linux, FreeBSD, NetBSD, DragonFly BSD, OpenBSD, macOS (Darwin), and [Android](https://gist.github.com/bep/a0d8a26cf6b4f8bc992729b8e50b480b) for x64, i386 and ARM architectures. 138 139 Hugo may also be compiled from source wherever the Go compiler tool chain can run, e.g. for other operating systems including Plan 9 and Solaris. 140 141 **Complete documentation is available at [Hugo Documentation](https://gohugo.io/getting-started/).** 142 143 ## Choose How to Install 144 145 If you want to use Hugo as your site generator, simply install the Hugo binaries. 146 The Hugo binaries have no external dependencies. 147 148 To contribute to the Hugo source code or documentation, you should [fork the Hugo GitHub project](https://github.com/gohugoio/hugo#fork-destination-box) and clone it to your local machine. 149 150 Finally, you can install the Hugo source code with `go`, build the binaries yourself, and run Hugo that way. 151 Building the binaries is an easy task for an experienced `go` getter. 152 153 ### Install Hugo as Your Site Generator (Binary Install) 154 155 Use the [installation instructions in the Hugo documentation](https://gohugo.io/getting-started/installing/). 156 157 ### Build and Install the Binaries from Source (Advanced Install) 158 159 #### Prerequisite Tools 160 161 * [Git](https://git-scm.com/) 162 * [Go (we test it with the last 2 major versions; but note that Hugo 0.81.0 only builds with >= Go 1.16.)](https://golang.org/dl/) 163 164 #### Fetch from GitHub 165 166 Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build. The easiest is to clone Hugo in a directory outside of `GOPATH`, as in the following example: 167 168 ```bash 169 mkdir $HOME/src 170 cd $HOME/src 171 git clone https://github.com/gohugoio/hugo.git 172 cd hugo 173 go install 174 ``` 175 176 **If you are a Windows user, substitute the `$HOME` environment variable above with `%USERPROFILE%`.** 177 178 If you want to compile with Sass/SCSS support use `--tags extended` and make sure `CGO_ENABLED=1` is set in your go environment. If you don't want to have CGO enabled, you may use the following command to temporarily enable CGO only for hugo compilation: 179 180 ```bash 181 CGO_ENABLED=1 go install --tags extended 182 ``` 183 184 ## The Hugo Documentation 185 186 The Hugo documentation now lives in its own repository, see https://github.com/gohugoio/hugoDocs. But we do keep a version of that documentation as a `git subtree` in this repository. To build the sub folder `/docs` as a Hugo site, you need to clone this repo: 187 188 ```bash 189 git clone git@github.com:gohugoio/hugo.git 190 ``` 191 ## Contributing to Hugo 192 193 For a complete guide to contributing to Hugo, see the [Contribution Guide](CONTRIBUTING.md). 194 195 We welcome contributions to Hugo of any kind including documentation, themes, 196 organization, tutorials, blog posts, bug reports, issues, feature requests, 197 feature implementations, pull requests, answering questions on the forum, 198 helping to manage issues, etc. 199 200 The Hugo community and maintainers are [very active](https://github.com/gohugoio/hugo/pulse/monthly) and helpful, and the project benefits greatly from this activity. 201 202 ### Asking Support Questions 203 204 We have an active [discussion forum](https://discourse.gohugo.io) where users and developers can ask questions. 205 Please don't use the GitHub issue tracker to ask questions. 206 207 ### Reporting Issues 208 209 If you believe you have found a defect in Hugo or its documentation, use 210 the GitHub issue tracker to report the problem to the Hugo maintainers. 211 If you're not sure if it's a bug or not, start by asking in the [discussion forum](https://discourse.gohugo.io). 212 When reporting the issue, please provide the version of Hugo in use (`hugo version`). 213 214 ### Submitting Patches 215 216 The Hugo project welcomes all contributors and contributions regardless of skill or experience level. 217 If you are interested in helping with the project, we will help you with your contribution. 218 Hugo is a very active project with many contributions happening daily. 219 220 We want to create the best possible product for our users and the best contribution experience for our developers, 221 we have a set of guidelines which ensure that all contributions are acceptable. 222 The guidelines are not intended as a filter or barrier to participation. 223 If you are unfamiliar with the contribution process, the Hugo team will help you and teach you how to bring your contribution in accordance with the guidelines. 224 225 For a complete guide to contributing code to Hugo, see the [Contribution Guide](CONTRIBUTING.md). 226 227 [Go]: https://golang.org/ 228 [Hugo Documentation]: https://gohugo.io/overview/introduction/ 229 230 ## Dependencies 231 232 Hugo stands on the shoulder of many great open source libraries. 233 234 If you run `hugo env -v` you will get a complete and up to date list. 235 236 In Hugo 0.89.0 that list is, in lexical order: 237 238 ``` 239 cloud.google.com/go/storage="v1.10.0" 240 cloud.google.com/go="v0.87.0" 241 github.com/Azure/azure-pipeline-go="v0.2.2" 242 github.com/Azure/azure-storage-blob-go="v0.9.0" 243 github.com/BurntSushi/locker="v0.0.0-20171006230638-a6e239ea1c69" 244 github.com/BurntSushi/toml="v0.3.1" 245 github.com/PuerkitoBio/purell="v1.1.1" 246 github.com/PuerkitoBio/urlesc="v0.0.0-20170810143723-de5bf2ad4578" 247 github.com/alecthomas/chroma="v0.9.4" 248 github.com/armon/go-radix="v1.0.0" 249 github.com/aws/aws-sdk-go="v1.41.14" 250 github.com/bep/debounce="v1.2.0" 251 github.com/bep/gitmap="v1.1.2" 252 github.com/bep/godartsass="v0.12.0" 253 github.com/bep/golibsass="v1.0.0" 254 github.com/bep/gowebp="v0.1.0" 255 github.com/bep/tmc="v0.5.1" 256 github.com/cli/safeexec="v1.0.0" 257 github.com/cpuguy83/go-md2man/v2="v2.0.0" 258 github.com/disintegration/gift="v1.2.1" 259 github.com/dlclark/regexp2="v1.4.0" 260 github.com/dustin/go-humanize="v1.0.0" 261 github.com/evanw/esbuild="v0.13.12" 262 github.com/fsnotify/fsnotify="v1.5.1" 263 github.com/getkin/kin-openapi="v0.80.0" 264 github.com/ghodss/yaml="v1.0.0" 265 github.com/go-openapi/jsonpointer="v0.19.5" 266 github.com/go-openapi/swag="v0.19.5" 267 github.com/gobuffalo/flect="v0.2.3" 268 github.com/gobwas/glob="v0.2.3" 269 github.com/gohugoio/go-i18n/v2="v2.1.3-0.20210430103248-4c28c89f8013" 270 github.com/gohugoio/locales="v0.14.0" 271 github.com/gohugoio/localescompressed="v0.14.0" 272 github.com/golang/groupcache="v0.0.0-20200121045136-8c9f03a8e57e" 273 github.com/golang/protobuf="v1.5.2" 274 github.com/google/go-cmp="v0.5.6" 275 github.com/google/uuid="v1.1.2" 276 github.com/google/wire="v0.4.0" 277 github.com/googleapis/gax-go/v2="v2.0.5" 278 github.com/googleapis/gax-go="v2.0.2+incompatible" 279 github.com/gorilla/websocket="v1.4.2" 280 github.com/inconshreveable/mousetrap="v1.0.0" 281 github.com/jdkato/prose="v1.2.1" 282 github.com/jmespath/go-jmespath="v0.4.0" 283 github.com/kyokomi/emoji/v2="v2.2.8" 284 github.com/mailru/easyjson="v0.0.0-20190626092158-b2ccc519800e" 285 github.com/mattn/go-ieproxy="v0.0.1" 286 github.com/mattn/go-isatty="v0.0.14" 287 github.com/mattn/go-runewidth="v0.0.9" 288 github.com/miekg/mmark="v1.3.6" 289 github.com/mitchellh/hashstructure="v1.1.0" 290 github.com/mitchellh/mapstructure="v1.4.2" 291 github.com/muesli/smartcrop="v0.3.0" 292 github.com/niklasfasching/go-org="v1.5.0" 293 github.com/olekukonko/tablewriter="v0.0.5" 294 github.com/pelletier/go-toml/v2="v2.0.0-beta.3.0.20210727221244-fa0796069526" 295 github.com/pkg/errors="v0.9.1" 296 github.com/rogpeppe/go-internal="v1.8.0" 297 github.com/russross/blackfriday/v2="v2.0.1" 298 github.com/russross/blackfriday="v1.5.3-0.20200218234912-41c5fccfd6f6" 299 github.com/rwcarlsen/goexif="v0.0.0-20190401172101-9e8deecbddbd" 300 github.com/sanity-io/litter="v1.5.1" 301 github.com/sass/libsass="3.6.5" 302 github.com/shurcooL/sanitized_anchor_name="v1.0.0" 303 github.com/spf13/afero="v1.6.0" 304 github.com/spf13/cast="v1.4.1" 305 github.com/spf13/cobra="v1.2.1" 306 github.com/spf13/fsync="v0.9.0" 307 github.com/spf13/jwalterweatherman="v1.1.0" 308 github.com/spf13/pflag="v1.0.5" 309 github.com/tdewolff/minify/v2="v2.9.22" 310 github.com/tdewolff/parse/v2="v2.5.21" 311 github.com/webmproject/libwebp="v1.2.0" 312 github.com/yuin/goldmark-highlighting="v0.0.0-20200307114337-60d527fdb691" 313 github.com/yuin/goldmark="v1.4.2" 314 go.opencensus.io="v0.23.0" 315 gocloud.dev="v0.20.0" 316 golang.org/x/image="v0.0.0-20210220032944-ac19c3e999fb" 317 golang.org/x/net="v0.0.0-20210614182718-04defd469f4e" 318 golang.org/x/oauth2="v0.0.0-20210628180205-a41e5a781914" 319 golang.org/x/sync="v0.0.0-20210220032951-036812b2e83c" 320 golang.org/x/sys="v0.0.0-20210908233432-aa78b53d3365" 321 golang.org/x/text="v0.3.7" 322 golang.org/x/xerrors="v0.0.0-20200804184101-5ec99f83aff1" 323 google.golang.org/api="v0.51.0" 324 google.golang.org/genproto="v0.0.0-20210716133855-ce7ef5c701ea" 325 google.golang.org/grpc="v1.39.0" 326 google.golang.org/protobuf="v1.27.1" 327 gopkg.in/yaml.v2="v2.4.0" 328 ```