Locally preview how GitHub will render your Markdown files.

---

MEREAD is a command-line tool for previewing Markdown files as they will be presented on GitHub, all completely locally and offline.

Motivation

I was surprised to find no simple tool that would allow me to preview Markdown files as they would be rendered on GitHub.

I wanted a tool that is:

• shipped as a single binary
• fast
• accurate to GitHub's rendering
• offline

There are other tools that get the job done, better or worse, but they all have some drawbacks that I wanted to avoid:

Tool	Written in	Biggest drawback
grip	Python	Uses GitHub's markdown API to render Markdown files, causing unnecessary usage of web requests.
gh markdown-preview	Go	Is meant to be used as extension in gh, GitHub's CLI.
markdown-preview.nvim	Typescript	Requires Neovim.

Usage

preview github flavored markdown locally

Usage: meread [OPTIONS] [PATH]

Arguments:
  [PATH]  Path to markdown file or directory containing README.md [default: .]

Options:
  -e, --export-dir <EXPORT_DIR>  If supplied, will export the markdown file to HTML in the specified
                                 directory
  -f, --force                    Whether to overwrite the export directory if it exists
  -a, --address <ADDRESS>        Address to bind the server to [default: localhost:3000]
  -o, --open                     Whether to open the browser on serve
  -l, --light-mode               Render page in light-mode style
      --generate-manpage         Print manpage to stdout and exit
  -h, --help                     Print help
  -V, --version                  Print version

Installation

From prebuilt binaries

For each version, prebuilt binaries are automatically built for Linux, MacOS and Windows.

• You can download and unpack the latest release from the releases page.

• Using cargo-binstall:

  cargo binstall meread

• Using ubi:

  ubi -p sermuns/meread

• Using mise:

  # `ubi` under the hood
  mise use -g ubi:sermuns/meread

  # `cargo-binstall` under the hood
  mise use -g cargo:meread

• Using nix flakes (one-off):

  nix run github:sermuns/meread

• Using nix flakes:

  1. Add MEREAD to your system flake.nix's inputs

     {
       inputs = {
         nixpkgs.url = "github:NixOS/nixpkgs/unstable";
         meread = {
           url = "github:sermuns/meread";
           inputs.nixpkgs.follows = "nixpkgs";
         };
       };
     }

  2. Add the MEREAD package to your environment.systemPackages list

     {
       pkgs,
       inputs,
     }: {
       environment.systemPackages = [
         inputs.meread.packages.${pkgs.stdenv.hostPlatform.system}.default
       ];
     }

  3. Rebuild your system with nixos-rebuild (or darwin-rebuild on MacOS)

From source

• cargo install meread

• git clone https://github.com/sermuns/meread
  cd meread
  cargo install

Manpages

Can be installed by

mkdir -p ~/.local/share/man/man1/
meread --generate-manpage > ~/.local/share/man/man1/meread.1