# How do I enable ANSI colored text output within Documenter.jl?

**URL:** <https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398>\
**Category:** New to Julia\
**Tags:** documenter\
**Created:** [October 14, 2020, 11:26pm UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398 "2020-10-14T23:26:06Z")\
**Posts on this page:** 15\
**Page:** 1

<div class="post-metadata">

**Author:** ![kimikage](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kimikage/32/14534_2.png) [@kimikage](https://discourse.julialang.org/u/kimikage)\
**Post date:** [October 14, 2020, 11:26pm UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398/1 "2020-10-14T23:26:06Z")

</div>

Hi, I’m currently developing a package in which coloring plays an important role.

The HTML output of Documenter.jl writes raw ANSI escape codes for text output such as `@example` as shown in the upper block in the screenshot. (Of course, the `:color` property of `IOContext` is not set, so ANSI escape codes are not usually displayed.)

I would like to get the ANSI colored output as shown in the lower block. Also, I don’t want to implement terminal emulation on the package (i.e. `src`, not `docs`) side, because the package will support both static “text/plain” and interactive “text/html” printing.

What are the best practices for ANSI color printing?

 ![ansicolor](https://global.discourse-cdn.com/julialang/original/3X/8/8/88560883301b5fe42883f3fb06340fddac459d97.png)

---

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [October 15, 2020, 4:29am UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398/2 "2020-10-15T04:29:27Z")

</div>

As you already observed, Documenter does not have any support for the ANSI colors at the moment. However, I do think it would be neat if it did (i.e. that if something can be printed in color, it will be).

It shouldn’t be too hard to get it working natively with Documenter, but it would need a little bit of work. A few breadcrumbs:

1. The return values of at-example blocks get [`show`ed in the `Expanders` module](https://github.com/JuliaDocs/Documenter.jl/blob/3b1934262da03c1bbf461420c46c9e12b5b05ec5/src/Expanders.jl#L581-L582), which uses [these functions here](https://github.com/JuliaDocs/Documenter.jl/blob/3b1934262da03c1bbf461420c46c9e12b5b05ec5/src/Utilities/Utilities.jl#L593-L610). Handling of stdout/stderr is near there as well.
2. We’d need to parse the ANSI sequences and figure out what style each character has. You already have a working implementation for this (`AnsiToHTML`)?
3. [HTMLWriter converts the `text/plain`](https://github.com/JuliaDocs/Documenter.jl/blob/3b1934262da03c1bbf461420c46c9e12b5b05ec5/src/Writers/HTMLWriter.jl#L1739-L1741) into HTML by using our [DOM representation](https://github.com/JuliaDocs/Documenter.jl/blob/3b1934262da03c1bbf461420c46c9e12b5b05ec5/src/Utilities/DOM.jl). Here we’d just need to loop over the string and wrap all the characters in `<span>`s I think.

What needs some thought is whether/how we should handle both colored and uncolored output simultaneously.

---

<div class="post-metadata">

**Author:** ![kimikage](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kimikage/32/14534_2.png) [@kimikage](https://discourse.julialang.org/u/kimikage)\
**Post date:** [October 15, 2020, 5:35am UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398/3 "2020-10-15T05:35:23Z")

</div>

Thanks for the helpful references.

> [@mortenpi](#):
>
> You already have a working implementation for this ( `AnsiToHTML` )?

I have ~200 lines of “rough” code supporting [SGR](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters) code 0-9, 22, ( **Edit:** 23-25, 27-29), 30-39, 40-49, 90-97, 100-107.

I guess such code already exists somewhere, but I couldn’t find it in JuliaHub package search.  
(Although I know there are some JavaScript libraries, I prefer a static conversion on this one.)

If we don’t have a standard tool, I’ll release the code.

BTW, while the state management shares some similarities with Crayons.jl, my code does not rely on Crayons.jl at the moment, because there are some differences in the concept of stack management.

---

<div class="post-metadata">

**Author:** ![kimikage](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kimikage/32/14534_2.png) [@kimikage](https://discourse.julialang.org/u/kimikage)\
**Post date:** [October 15, 2020, 2:50pm UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398/4 "2020-10-15T14:50:32Z")

</div>

~~I haven’t written the test code yet.~~ 😅  
**Edit:** It has been transferred from my personal repository to JuliaDocs.  
[https://github.com/JuliaDocs/ANSIColoredPrinters.jl](https://github.com/JuliaDocs/ANSIColoredPrinters.jl)

Documentation with examples (dev):  
[https://juliadocs.github.io/ANSIColoredPrinters.jl/dev/](https://juliadocs.github.io/ANSIColoredPrinters.jl/dev/)

Package design issue:  
[https://github.com/JuliaDocs/ANSIColoredPrinters.jl/issues/4](https://github.com/JuliaDocs/ANSIColoredPrinters.jl/issues/4)

---

<div class="post-metadata">

**Author:** ![kimikage](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kimikage/32/14534_2.png) [@kimikage](https://discourse.julialang.org/u/kimikage)\
**Post date:** [October 17, 2020, 9:55am UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398/5 "2020-10-17T09:55:57Z")

</div>

Now, I’ve tried the following changes.  
(WIP: [Comparing JuliaDocs:master...kimikage:ansicolor · JuliaDocs/Documenter.jl · GitHub](https://github.com/JuliaDocs/Documenter.jl/compare/master...kimikage:ansicolor))

1. add a field / argument `ansicolor` to `User` / `makedocs()`.
2. add a keyword argument `ansicolor` in the `@example` block to override the `user.ansicolor`.
3. add a `context` keyword argument to `Utilities.display_dict()`.

```julia
function limitstringmime(m::MIME"text/plain", x; context=nothing)
    io = IOBuffer()
    ioc = IOContext(context === nothing ? io : IOContext(io, context), :limit => true)
    show(ioc, m, x)
    return String(take!(io))
end
function display_dict(x; context=nothing)
    out = Dict{MIME,Any}()
    x === nothing && return out
    # Always generate text/plain
    out[MIME"text/plain"()] = limitstringmime(MIME"text/plain"(), x, context=context)
    for m in [MIME"text/html"(), MIME"image/svg+xml"(), MIME"image/png"(),
              MIME"image/webp"(), MIME"image/gif"(), MIME"image/jpeg"(),
              MIME"text/latex"(), MIME"text/markdown"()]
        showable(m, x) && (out[m] = stringmime(m, x, context=context))
    end
    return out
end

```

1. in `Selectors.runner(::Type{ExampleBlocks}, x, page, doc)`, call:

```julia
output = Base.invokelatest(Utilities.display_dict, result, context=:color => ansicolor)

```

1. in `HTMLWriter.mdconvert()`, use `AnsiColoredPrinters.HTMLPrinter`:

```julia
...
    elseif haskey(d, MIME"text/plain"())
        input = IOBuffer(d[MIME"text/plain"()])
        printer = AnsiColoredPrinters.HTMLPrinter(input, root_class="documenter-example-output")
        out = Documents.RawHTML(repr(MIME"text/html"(), printer))
...

```

The changes successfully colorize lazy-printing objects.

 ![ansi2](https://global.discourse-cdn.com/julialang/original/3X/8/1/815e3c54e97b7273cf2b3f6c66fa6c6ce48941bd.png)

However, the `stdout` output does not have ANSI escape codes.

What should I do after that? In the meantime, should I submit a WIP PR?  
cc: @mortenpi

* * *

BTW, which setting of which SASS/SCSS compiler should I use?

---

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [October 18, 2020, 9:46pm UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398/6 "2020-10-18T21:46:22Z")

</div>

Scrolling through the diff quickly, this looks great! Please do open a PR and we can discuss the technical details there.

Regarding Sass, [DocumenterTools](https://github.com/JuliaDocs/DocumenterTools.jl/blob/09c8c05d65b4d129b511f1868510933fe295a03b/src/Themes.jl#L53-L72) can re-compile the themes for you (it will re-generate the `.css` files under `assets/html/themes`, using [Sass.jl](https://github.com/piever/Sass.jl)):

```julia
using DocumenterTools: Themes
Themes.compile_native_themes()

```

---

<div class="post-metadata">

**Author:** ![kimikage](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kimikage/32/14534_2.png) [@kimikage](https://discourse.julialang.org/u/kimikage)\
**Post date:** [October 19, 2020, 10:42am UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398/7 "2020-10-19T10:42:53Z")

</div>

I opened a draft PR.  
xref: [https://github.com/JuliaDocs/Documenter.jl/pull/1441](https://github.com/JuliaDocs/Documenter.jl/pull/1441)

(Due to troubles with the use of unregistered packages and automatic whitespace removal from CSS files by the IDE 😱, I’ve only checked that it works locally yet. 😅)

Also, thank you for telling me about `compile_native_themes()`!

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [July 6, 2021, 3:08pm UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398/8 "2021-07-06T15:08:06Z")

</div>

Update on this.

[JuliaDocs/Documenter.jl#1441](https://github.com/JuliaDocs/Documenter.jl/pull/1441) is now merged, and the next Documenter version (0.27.4) will have color output! Here is a screenshot of the generated HTML:

 ![Screenshot from 2021-07-06 17-05-06](https://global.discourse-cdn.com/julialang/original/3X/a/2/a295a4c9be0460fa53141a19a331fdacaa91a37e.png)

Thanks @kimikage !

---

<div class="post-metadata">

**Author:** ![maxkapur](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/maxkapur/32/21208_2.png) [@maxkapur](https://discourse.julialang.org/u/maxkapur)\
**Post date:** [April 22, 2022, 4:37am UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398/9 "2022-04-22T04:37:38Z")

</div>

Sorry to bump an old thread, but are there any extra steps needed to get this to work? My docs are still showing up uncolored. Here is a UnicodePlot:

 ![image](https://global.discourse-cdn.com/julialang/original/3X/0/0/00901cba464294f66919521bdc015f1a9b8960da.png)

The markdown code is

````markdown
```@example
using UnicodePlots, Crayons
scatterplot(rand(50), rand(50), color=crayon"magenta")
```

````

and my make.jl file reads

```julia
using Documenter
using PackageName

makedocs(
    sitename="PackageName",
    modules=[PackageName],
    pages=Any[
        # ...
    ],
)

```

---

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [April 25, 2022, 2:55am UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398/10 "2022-04-25T02:55:23Z")

</div>

Currently, the color capture is disabled by default (to maintain backwards compatibility; this should change in 0.28, which is why the docs already imply that it’s enabled).

You need to explicitly pass `format = Documenter.HTML(ansicolor = true)` to `makedocs` to enable it (or set `@example; ansicolor = true` for each block you want colored).

---

<div class="post-metadata">

**Author:** ![Maximilian](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/maximilian/32/12206_2.png) [@Maximilian](https://discourse.julialang.org/u/Maximilian)\
**Post date:** [May 1, 2022, 12:00am UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398/11 "2022-05-01T00:00:21Z")

</div>

I successfully got this to work if I build the documentation locally, but color is still disabled when the docs are build via github actions. Is there anything else to do to get this to work online?

---

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [May 2, 2022, 1:12am UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398/12 "2022-05-02T01:12:56Z")

</div>

If it works locally, it should work on GHA without any additional configuration. Without seeing the repo and CI logs, it’s hard to say anything more. I would double check that (1) the new version actually deployed, and (2) that the Documenter setup in the repository is actually fully up to date.

---

<div class="post-metadata">

**Author:** ![Maximilian](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/maximilian/32/12206_2.png) [@Maximilian](https://discourse.julialang.org/u/Maximilian)\
**Post date:** [May 2, 2022, 9:26am UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398/13 "2022-05-02T09:26:35Z")

</div>

Okay, the last documentation build looks fine:  
[https://github.com/StructuralEquationModels/StructuralEquationModels.jl/actions/runs/2257064202](https://github.com/StructuralEquationModels/StructuralEquationModels.jl/actions/runs/2257064202)  
The make.jl file is here:

> <https://github.com/StructuralEquationModels/StructuralEquationModels.jl/blob/devel/docs/make.jl>

ansicolor = true is enabelled globally and also in the @example blocks.  
For example, the outputs on this page should be colored  
[https://structuralequationmodels.github.io/StructuralEquationModels.jl/dev/tutorials/first\_model/](https://structuralequationmodels.github.io/StructuralEquationModels.jl/dev/tutorials/first_model/)  
that is specified here

> <https://github.com/StructuralEquationModels/StructuralEquationModels.jl/blob/devel/docs/src/tutorials/first_model.md>

For example, the last output on this page locally looks like this:

 ![output](https://global.discourse-cdn.com/julialang/original/3X/4/6/4624274cb141786096b2332ccc118ebb0d69cf40.png)

---

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [May 3, 2022, 4:08am UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398/14 "2022-05-03T04:08:55Z")

</div>

Interesting. As a test, could you add a `--color=yes` to the `make.jl` call on CI (i.e. change [this](https://github.com/StructuralEquationModels/StructuralEquationModels.jl/blob/874c3b4a264079db862040da16ad3203ab342b6c/.github/workflows/documentation.yml#L27) to `julia --color=yes --project=docs/ docs/make.jl`)?

Edit: I tested this locally now. It looks like the coloring of the StructuralEquationModels output is sensitive to the `--color` option, so setting `--color=yes` on CI will likely fix this.

---

<div class="post-metadata">

**Author:** ![Maximilian](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/maximilian/32/12206_2.png) [@Maximilian](https://discourse.julialang.org/u/Maximilian)\
**Post date:** [May 3, 2022, 7:31am UTC](https://discourse.julialang.org/t/how-do-i-enable-ansi-colored-text-output-within-documenter-jl/48398/15 "2022-05-03T07:31:12Z")

</div>

Cool, it works now! Thanks!