From a462575c4c1fbbf605d641c6c82e63745fb9745b Mon Sep 17 00:00:00 2001 From: Catalin Constantin Mititiuc Date: Sat, 21 Jun 2025 15:37:57 -0700 Subject: [PATCH] Update commands; add setup section --- posts/2025-06-20-chroma.md | 102 ++++++++++++++++++++++--------------- 1 file changed, 60 insertions(+), 42 deletions(-) diff --git a/posts/2025-06-20-chroma.md b/posts/2025-06-20-chroma.md index 14f4bb3..1cd581b 100644 --- a/posts/2025-06-20-chroma.md +++ b/posts/2025-06-20-chroma.md @@ -7,20 +7,47 @@ $index [Gitea](https://github.com/go-gitea/gitea) uses [Chroma](https://github.com/alecthomas/chroma) for syntax highlighting. Chroma is based on the Python syntax highlighter, [Pygments](https://github.com/pygments/pygments), and includes a [script](https://github.com/alecthomas/chroma/blob/484750a96fc430f49d6b69cc2a2a8b7a67691446/_tools/pygments2chroma_xml.py) to help convert Pygments -lexers for use with Chroma. This post describes that process. +lexers for use with Chroma. We describe how below. + +## Setup + +We're going to be using the `python` and `golang` [Docker][4] images. Docker +Desktop is _not_ required. + +```console +$ docker pull python +$ docker pull golang +``` + +Let's set up some aliases to make running the commands easier. + +```console +$ alias docker-run='docker run --rm -it -w /opt -v $PWD:/opt' +$ alias docker-run-go='docker-run golang' +$ alias docker-run-py='docker-run python' + ``` + +[3]: https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user +[4]: https://docs.docker.com/engine/ ## Convert a Pygments lexer to a Chroma lexer with `pygments2chroma_xml.py` +```console +$ git clone https://github.com/alecthomas/chroma.git +$ cd chroma +``` + In the Chroma root directory, we run: ```console -$ docker run --rm -it -w /opt -v $PWD:/opt python bash -c \ -"pip install pystache pygments && pip list \ -&& python _tools/pygments2chroma_xml.py \ -pygments.lexers.scripting.LuaLexer > lexers/embedded/lua.xml" +$ docker-run-py bash -c \ + "pip install pystache pygments && \ + python _tools/pygments2chroma_xml.py \ + pygments.lexers.scripting.LuaLexer > lexers/embedded/lua.xml && \ + pip list" ``` -As output, we should see this in our terminal: +We should see this in the output: ``` Package Version @@ -45,15 +72,15 @@ rules for the [Lua](https://www.lua.org) language. ... ``` -## Highlight some code with our new lexer +## Highlight some code with a Chroma lexer Chroma provides a [simple example test file][1] we can modify to see what syntax highlighting with our new lexer looks like. First, though, we need to create a new Go module by running `go mod init`: ```console -$ docker run --rm -it -w /opt -v $PWD:/opt golang:tip-bookworm \ -go mod init main +$ cd .. +$ docker-run-go go mod init main go: creating new go.mod: module main go: to add module requirements and sums: go mod tidy @@ -63,8 +90,7 @@ We will need required modules, so let's go ahead and run `go mod tidy` as the output suggests. ```console -$ docker run --rm -it -w /opt -v $PWD:/opt golang:tip-bookworm \ -go mod tidy +$ docker-run-go go mod tidy ``` We should now have 2 additional files, `go.mod` and `go.sum`. `go.sum` has some @@ -85,9 +111,8 @@ require github.com/dlclark/regexp2 v1.11.5 // indirect ``` Now we can create a `main.go` file and copy over the code from Chroma's example -test file, but we update the `code` variable and the lexer we pass into the -`Highlight` function for Lua: - +test file, but we update the `code` variable with some Lua, `print("hello")`, +and the lexer we pass into the `Highlight` function is changed to `"lua"`: ::: filename-for-code-block `main.go` @@ -116,7 +141,7 @@ func main() { Now we can try running our `main.go` like this: ```console -$ docker run --rm -it -w /opt -v $PWD:/opt golang:tip-bookworm go run main.go +$ docker-run-go go run main.go go: downloading github.com/alecthomas/chroma/v2 v2.18.0 go: downloading github.com/dlclark/regexp2 v1.11.5 @@ -130,8 +155,8 @@ the GitHub repo. If we want to use a local version of Chroma, we have to use a [`replace` directive][2] to import Chroma from our local directory: ```console -$ docker run --rm -it -w /opt -v $PWD:/opt golang:tip-bookworm \ -go mod edit -replace github.com/alecthomas/chroma/v2@v2.18.0=./chroma +$ docker-run-go go mod edit -replace \ +github.com/alecthomas/chroma/v2@v2.18.0=./chroma ``` Which adds this line to our `go.mod` file: @@ -150,7 +175,7 @@ Now, when we run `main.go`, we should no longer see Chroma being imported, because it's using our local copy: ```console -$ docker run --rm -it -w /opt -v $PWD:/opt golang:tip-bookworm go run main.go +$ docker-run-go go run main.go go: downloading github.com/dlclark/regexp2 v1.11.5