# Markdown rendering in ArgParse.jl

**URL:** <https://discourse.julialang.org/t/markdown-rendering-in-argparse-jl/115871>\
**Category:** General Usage\
**Created:** [June 19, 2024, 3:32pm UTC](https://discourse.julialang.org/t/markdown-rendering-in-argparse-jl/115871 "2024-06-19T15:32:20Z")\
**Posts on this page:** 3\
**Page:** 1

<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:** [June 19, 2024, 3:32pm UTC](https://discourse.julialang.org/t/markdown-rendering-in-argparse-jl/115871/1 "2024-06-19T15:32:20Z")

</div>

Julia lets you include some Markdown syntax in docstrings, and renders it with nice colors in the terminal, e.g. in interactive help:

![](https://global.discourse-cdn.com/julialang/original/3X/2/c/2cb3b4429c88e7defc0b92d2db57fee61e62e1f2.png)

Is it possible to achieve the same with ArgParse.jl?

If you type Markdown into the help text, it just renders as plain text (try `julia main.jl --help` with the file below).

> **\`main.jl\`**
>
> ```julia
> using ArgParse
> using Markdown
> 
> function parse_commandline()
> s = ArgParseSettings()
> 
> @add_arg_table! s begin
> "--opt1"
> help = "an option with an argument `and some markdown`"
> "--opt2", "-o"
> help = "another option with an argument"
> arg_type = Int
> default = 0
> "--flag1"
> help = "an option without argument, i.e. a flag"
> action = :store_true
> "arg1"
> help = "a positional argument"
> required = true
> end
> 
> return parse_args(s)
> end
> 
> function main()
> parsed_args = parse_commandline()
> println("Parsed args:")
> for (arg,val) in parsed_args
> println(" $arg => $val")
> end
> end
> 
> main()
> 
> ```

And if you change the help strings to a `md"markdown string"` (after `using Markdown`) you get:

```julia
> julia main.jl --help
ERROR: LoadError: ArgParseSettingsError("help must be an AbstractString")

```

---

<div class="post-metadata">

**Author:** ![stevengj](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stevengj/32/71_2.png) [@stevengj](https://discourse.julialang.org/u/stevengj)\
**Post date:** [June 19, 2024, 4:04pm UTC](https://discourse.julialang.org/t/markdown-rendering-in-argparse-jl/115871/2 "2024-06-19T16:04:37Z")

</div>

> [@maxkapur](#):
>
> Is it possible to achieve the same with [ArgParse.jl](https://juliahub.com/ui/Packages/General/ArgParse)?

I looked into it, and it seems that patching the source is required. An example PR is: [support markdown in help strings by stevengj · Pull Request #134 · carlobaldassi/ArgParse.jl · GitHub](https://github.com/carlobaldassi/ArgParse.jl/pull/134)

---

<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:** [June 26, 2024, 9:13pm UTC](https://discourse.julialang.org/t/markdown-rendering-in-argparse-jl/115871/3 "2024-06-26T21:13:16Z")

</div>

# Partial solution

Studying Steven’s patch, it is possible to render many Markdown strings in ArgParse.jl without patching the source if you use `repr()` to convert the Markdown to text with ANSI escape codes. Here is a minimal example:

```julia-auto
# demo.jl

using ArgParse
using Markdown

function to_ansi(markdown::Markdown.MD)
    ansi_escaped = repr("text/plain", markdown; context=:color => true)
    # Remove 2-space indent inserted by repr
    Base.unindent(ansi_escaped, 2)
end

function main(args)
    s = ArgParseSettings(
        description=to_ansi(md"""
        Example of using **Markdown** syntax within `Argparse.jl`.

        Multiple paragraphs parse correctly as long as you set `preformatted_description` to `true`.
        """) * '\n',
        preformatted_description=true
    )

    @add_arg_table! s begin
        "arg1"
        begin
            help = to_ansi(md"You can also use Markdown in the `help` text")
        end
    end

    parse_args(s)
end

main(ARGS)

```

Then `julia ./demo.jl --help` gets you:

 ![image](https://global.discourse-cdn.com/julialang/original/3X/c/e/ce112de164025d74d4809eaaf34e0de85b3befe5.png)

However, this will fail or produce weird indentation in certain edge cases, such as when the Markdown includes subheadings or when you combine it with options like `help_width`. See the pull request linked above for more discussion.