go-grip

README

go-grip

Render your markdown files local
- with the look of GitHub

Table of Contents

• About
• Features
• Getting started
• Usage
• Examples
• Known TODOs / Bugs
• Similar tools

❓ About

go-grip is a lightweight, Go-based tool designed to render Markdown files locally, replicating GitHub's style. It offers features like syntax highlighting, dark mode, and support for mermaid diagrams, providing a seamless and visually consistent way to preview Markdown files in your browser.

This project is a reimplementation of the original Python-based grip, which uses GitHub's web API for rendering. By eliminating the reliance on external APIs, go-grip delivers similar functionality while being fully self-contained, faster, and more secure - perfect for offline use or privacy-conscious users.

⚡ Features

• ⚡ Written in Go 👍
• 📄 Render markdown to HTML and view it in your browser
• 📱 Dark and light theme
• 🎨 Syntax highlighting for code
• Todo list like the one on GitHub
• Support for github markdown emojis 👍
• Support for mermaid diagrams
• hashtag linking in page (see table of contents)
• math expressions (code, inline, block)
• gh issues and prs #46 and grafana/grafana#22
• toggle state is preserved in sessionStorage

This is an inline $\sqrt{3x-1}+(1+x)^2$ function.

$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$

\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

package main

import "github.com/nickfujita/go-grip/cmd"

func main() {
	fmt.Sprintln("Welcome to Grip! Use `go-grip --help` for more information.")
}

[!TIP] Support of blockquotes (note, tip, important, warning and caution) see here

[!IMPORTANT]

test

🚀 Getting started

Prebuilt release binary (no Go toolchain required)

Each tagged release publishes self-contained binaries for Linux AMD64 (go-grip-linux-amd64), Linux ARM64 (go-grip-linux-arm64), and macOS Apple Silicon (go-grip-darwin-arm64). Drop the Linux AMD64 binary into ~/.local/bin:

mkdir -p ~/.local/bin
curl -fsSL https://github.com/nickfujita/go-grip/releases/latest/download/go-grip-linux-amd64 -o ~/.local/bin/go-grip
chmod +x ~/.local/bin/go-grip
# make sure ~/.local/bin is on your PATH

For Linux ARM64, use go-grip-linux-arm64. For macOS Apple Silicon, use go-grip-darwin-arm64.

With the Go toolchain

go install github.com/nickfujita/go-grip@latest

[!TIP] You can also use nix flakes to install this plugin. More useful information here.

🔨 Usage

To render the README.md file simply execute:

go-grip README.md
# or
go-grip

The browser will automatically open on http://localhost:6419. You can disable this behaviour with the -b=false option.

You can also specify a port:

go-grip -p 80 README.md

or just open a file-tree with all available files in the current directory:

go-grip -r=false

It's also possible to activate the darkmode:

go-grip -d .

To disable automatic browser reload on file changes (useful for stable editing):

go-grip --no-reload README.md

To layer your own styling on top of the built-in theme, pass one or more stylesheets with --css. Each file is linked after the theme stylesheet, so its rules win the cascade. The flag is repeatable and files are applied in order:

go-grip --css brand.css README.md
# or stack several
go-grip --css base.css --css overrides.css README.md

A missing --css path fails immediately at startup with a clear error.

Built-in nightshade theme

nightshade is a dark theme compiled into the binary — a deep near-black canvas with muted violet headings/links, teal monospace code, and a warm amber blockquote accent. It needs no external file:

go-grip --theme nightshade README.md

Custom themes

Besides the built-in light, dark, auto, and nightshade themes, --theme accepts a custom theme name. A name that is not one of the built-ins resolves to a stylesheet in your themes directory:

$XDG_CONFIG_HOME/go-grip/themes/<name>.css   # defaults to ~/.config/go-grip/themes/<name>.css

For example, with ~/.config/go-grip/themes/nightshade.css in place:

go-grip --theme nightshade README.md

By default a custom theme layers on top of the built-in dark base, so you only need to write the overrides you care about. Change the base with an optional first-line directive:

/* go-grip-base: light */   /* layer on the light base instead */
/* go-grip-base: none */    /* no built-in base; your theme stands alone */

If the named theme file does not exist, startup fails with an error that lists the path it searched and the theme names that are available.

To terminate the current server simply press CTRL-C.

Running as a service

To keep a go-grip preview running in the background, install the systemd user unit shipped in contrib/. It runs go-grip -b=false --theme nightshade from your home directory:

mkdir -p ~/.config/systemd/user
cp contrib/gogrip.service ~/.config/systemd/user/
loginctl enable-linger "$USER"          # keep it running after you log out
systemctl --user enable --now gogrip.service

See contrib/README.md for details.

📝 Examples

🐛 Known TODOs / Bugs

• Make it possible to export the generated html

📌 Similar tools

This tool is a Go-based reimplementation of the original grip, offering the same functionality without relying on GitHub's web API.