Display Markdown Text in Command Line using Python

Motivation

Recently, I was given a task of refactoring our legacy command line application. I was thinking what more could we do to improvise a legacy command line application that’s working just fine.

Remembering the commands and their respective flags, optional parameters etc is bit hectic. Of course you could copy all the commands in a notepad and use ’em as needed. But that’s still annoying if you ask me.

So what did I do?

I came across this library called PyInquirer and rich with which we could make colorful command line applications that are interactive.To learn more about building interactive command lines please refer to my article here.

Another area of improvement was the help command.

Improvising the help

Help is the most under-rated and at the same time most significant feature for a command line application. Traditionally, we use plain text to print help for a command line application(referred as cli in future). Well I consider plain text helps to be cheugy.

Use of rst files for help in aws cli

If we see the code of aws cli, they use different .rst files to display help based on the command and subcommands.This was thought provoking and I decided to adopt something similar.

Markdown text for help using rich

To get rid of the traditional plan text help, the best bet I had was to leverage the Markdown library supported by rich.

From the docs: “Rich can render Markdown to the console. To render markdown, construct a [**_Markdown_**](https://rich.readthedocs.io/en/stable/reference/markdown.html#rich.markdown.Markdown) object then print it to the console. Markdown is a great way of adding rich content to your command line applications.”

Let’s quickly write code for displaying help in Python:

help.py:

from rich.console import Console
from rich.markdown import Markdown
import sys

console = Console()


def display_help():
    with open("help.md", "r+") as help_file:
        console.print(Markdown(help_file.read()))
    sys.exit(0)
   

if len(sys.argv) >= 2:
    if sys.argv[1].lower() == "help":
            display_help()

Execute the above code using the command line below:

$python help.py help

Contents of help.md file:

# MY COMMAND LINE APPLICATION HELP  
> A Python based command line interface to display markdown help
**Usage**
`$python help.py help`

Output:

GitHub gist for help.md can be found here.

Our help can now display code snippets, headings, emphasized texts but not limited to them. This looks much better than the regular plain text help.

Personally, I prefer using this with CLIs going forward.Not only does this look appealing to the user but also it is easier to maintain the code for help in one file which helps improve modularity.

Two birds with one stone!

To understand more about rich library and its support for additional features apart from markdown, please refer here.

Summary

• Markdown texts can be displayed to terminal using rich library
• One such usecase is display of help to user.