Workbench

A Bash Alias For Viewing READMEs From the Command Line

It occurred to me that it would be nice to be able to display the contents of a README file in the terminal without knowing the file format or whether it's upper/lower case, and some yak-shaving ensued.

This is a bash alias that:

  1. Makes a temp directory
  2. Looks for any file in the current directory whose name begins with readme
  3. Uses pandoc to convert the first README found into a section 1 man page in the temp directory
  4. Uses sed to add a .TH topic line at the top of the man page, as pandoc does not seem to do this on its own
  5. Displays the man page using the linux-specific -l option (This alias will not work on MacOS)

Prerequisites

  • man
  • pandoc
  • mktemp
  • sed
  • xargs

The Alias

Add the following at the end of your ~/.bash_aliases file:

alias readme="RMDIR=`mktemp -d -p ${TMPDIR-/tmp} readme-XXXXXX`; find . -iname 'readme.*' -maxdepth 1 | head -n 1 | xargs  -I {} pandoc {} -o $RMDIR/readme.1;sed -i '1s/^/.TH README 1\n/' $RMDIR/readme.1; man -l $RMDIR/readme.1"

Then either close and reopen your terminal, or type source ~/.bash_aliases.

Now you should be able to cd to a directory containing a README (or Readme.md, or ReadMe.rst, etc) file and type:

readme

to quickly view it.

Tue Jul 22 2025 20:00:00 GMT-0400 (Eastern Daylight Time)