README.md

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:

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";
    };
  };
}

Add the MEREAD package to your environment.systemPackages list

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

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