Preview GitHub flavored markdown offline

---

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.

The Neovim plugin, meread-nvim

meread-nvim-demo-trim.mp4

Installation

For example, using vim.pack:

vim.pack.add {
	{
		src = 'https://github.com/sermuns/MEREAD',
		version = vim.version.range('1'),
	},
}

Then, you have to run the setup to get the functions loaded. It is also useful to bind the preview action to some keybind.

Advisably, you would do this in a ftplugin for markdown by creating the file under ~/.config/nvim/ftplugin/markdown.lua:

require('meread').setup {}

-- start preview by pressing F10
vim.keymap.set(
	'n',
	'<F10>',
	function()
		vim.cmd "MereadPreview"
	end
)

The command-line tool, meread

meread-cli-demo-trim.mp4

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