frm

A Bash script to fully render Markdown.

Motivation

There are many great Markdown viewers out there. Unfortunately, those tools always come with limitations on what Markdown syntax they know how to render and how nicely they can render it. This is because...

• there are multiple standards that define Markdown syntax
• Markdown can contain arbitrary HTML
• viewers are limited by the capabilities of the environments they run in

frm solves these issues by using Pandoc to convert Markdown files to HTML pages, then opening those pages with your default program for HTML (which is usually a web browser).

frm isn't meant to be the last (or fastest) Markdown viewer you'll ever use. Viewers that render directly to the terminal or that are built-in to an application you're already using often provide a quicker/more convenient experience that does a good enough job most the time. Conversely, frm excels at rendering the many syntaxes and custom HTML you might find in Markdown files and leveraging the power of CSS to make content look amazing ✨️.

Installation

Ensure you have frm's dependencies installed and available in your path.

• Required: Bash (to execute the script)
• Required: Pandoc (to perform document conversion)
• Conditionally Optional: xdg-mime (to check the selected file's type).
  • xdg-mime is part of xdg-utils which should be installed on most Linux distributions by default. If xdg-mime is not in your path, you must set FRM_CHECK_COMMAND.
• Optional: fzf (to enable running frm without a file path)
• Optional: fd (as an alternative file searcher)

Then download the script, and place it in your path, and make it executable. I like to use ~/.local/bin, but anywhere in your path should work.

NOTE: If you're copying the code below, make sure to replace {release-tag} with the release name of your desired version.

curl "https://git.nicolaos.dev/nicolaos/frm/raw/tag/{release-tag}/frm.sh" > ~/.local/bin/frm
chmod +x ~/.local/bin/frm

Usage

Run frm with a file path to a Markdown file as an argument.

frm <path-to-markdown-file>

If you have fzf installed, you may omit the file path. frm will search for Markdown files in your current directory and allow you to choose one using fzf. The search will use fd if its available, otherwise it falls back to find.

# Must have fzf available
frm

You can use the --no-open option to prevent frm from opening the HTML ouput file after conversion. This can be useful when repeatedly running frm on a file and you'd rather refresh an existing browser tab instead of creating a new one.

frm --no-open README.md

The examples below set variables inline for ease of demonstration, but its probably more convenient to set them in your shell config.

CSS

frm uses Simple.css as its default styles. You can override this by setting the FRM_CSS variable to the URL of a different CSS file. Classless style sheets tend to work well for this.

FRM_CSS='https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css' frm README.md

If you want to use your own custom style sheet you may provide an absolute local file path. You can use this same approach with a downloaded style sheet to avoid the browser making a network request to retrieve styles.

FRM_CSS="$HOME/my-styles.css" frm

Pandoc Options

If you've set the FRM_PANDOC_OPTIONS variable, frm will send its value to Pandoc when processing the Markdown file. See the Pandoc User’s Guide for a full list of options.

# Generate a table of context and change the syntax highlighting colors
FRM_PANDOC_OPTIONS='--toc --syntax-highlighting=kate' frm hello.md

# Process the file as GitHub Flavored Markdown rather than Pandoc's Markdown
FRM_PANDOC_OPTIONS='--from=gfm' frm my-gfm-file.md

Custom Check Command

frm tries to verify the file selected can be processed as Markdown before processing it with Pandoc. It does so by checking the MIME type of a file using xdg-mime. If you don't have xdg-mime in your path or you'd prefer frm use a different program for some reason, set the FRM_CHECK_COMMAND variable to an alternative command.

# Example command is only for demonstration purposes, not recommended
function check-type {
	file -i $1 | rg --only-matching '\w+\/\w+'
}
export -f check-type
FRM_CHECK_COMMAND='check-type' frm

Custom Preview File Location

frm saves the generated HTML files to /tmp/markdown-previews by default. If you'd prefer frm use a different location, specify it using the FRM_PREVIEWS_LOCATION variable.

FRM_PREVIEWS_LOCATION="$HOME/my-markdown-previews" frm README.md

Contributing

See CONTRIBUTING.md