go-grip

go-grip

Render your markdown files local
- with the look of GitHub

Table of Contents

• Table of Contents
• ❓ About
• :twisted_rightwards_arrows: Fork status
• ✨ Differences from upstream
• ⚡ Features
• 🚀 Getting started
  • Download a prebuilt binary
  • Install with Go
• 📦 Releasing
• 🔨 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.

🔀 Fork status

This repository is a fork of chrishrb/go-grip.

The main purpose of this fork is to add extra Markdown preview support for cases where a single-file preview is not enough. These changes are intended to make local documentation folders easier to browse and use, especially when working with multiple Markdown files or long documents.

At the moment, this fork is maintained as a separate modified version and does not plan to open a pull request against the upstream repository.

✨ Differences from upstream

Compared with the upstream repository, this fork focuses on local documentation browsing and smoother long-document navigation.

Additional documentation browsing support:

• Directory mode: running go-grip or go-grip . opens a documentation view for all Markdown files in the current directory.
• Multi-file navigation: directory mode adds an article sidebar so related Markdown files can be opened without restarting the server.
• Custom directory targets: running go-grip docs opens Markdown files from another directory.
• The article sidebar title uses the selected directory name, making it easier to identify the active documentation folder.
• The article sidebar sorts directories before files at each level, then sorts entries by name.
• Recursive directory navigation is available with -r or --recursive, showing nested Markdown files as a collapsible tree.
• Directory mode adds previous/next article navigation and supports the left/right arrow keys for moving between articles.

Additional table-of-contents support:

• Each rendered article gets its own table of contents.
• The active TOC item updates while scrolling through the article.
• Long TOCs automatically scroll to keep the active item visible.
• Clicking a TOC item keeps that item stable while the article scrolls to the target heading, avoiding jumpy TOC movement.
• When the page reaches the bottom, the final TOC entry can become active even if the last heading cannot scroll to the top marker.

Additional server behavior:

• If the default port is busy, go-grip automatically tries the next available port.
• If a port is explicitly set with -p, go-grip treats that port as strict and reports an error when it is unavailable.
• --no-reload disables automatic browser reload on file changes.

Additional editor support:

• In-browser Markdown editing with save-to-disk: click the Edit button on any Markdown page to open a split-screen editor.
• Split-screen live preview renders the compiled Markdown in real time as you type (powered by marked.js).
• Scroll synchronization keeps the editor textarea and preview panel aligned by scroll percentage.
• Custom .md-only file watcher (replaces aarol/reload) with WebSocket-based hot reload, exponential backoff reconnection, and debounced change events.
• Keyboard shortcuts: Ctrl+S saves and reloads the browser, Ctrl+Enter saves and stays in the editor, Ctrl+P toggles the preview panel.

Distribution changes:

• This fork uses the module path github.com/showgp/go-grip.
• GitHub Releases publish prebuilt macOS, Linux, and Windows binaries.
• Release archives include checksums for download verification.

⚡ Features

• ⚡ Written in Go 👍
• 📄 Render markdown to HTML and view it in your browser
• Browse all Markdown files in a directory from a local documentation sidebar
• Multi-file Markdown preview with article navigation
• Optional recursive directory sidebar with -r
• Directory sidebar titles show the active directory name
• Directory-first sidebar sorting for mixed folder/file lists
• Previous/next article links with left/right keyboard navigation
• Per-page table of contents for rendered documents
• Active table-of-contents highlighting while scrolling
• 📱 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
• In-browser Markdown editing with save-to-disk (Edit/Save/Cancel workflow)
• Split-screen live preview with real-time Markdown rendering
• Scroll synchronization between editor and preview panels
• Custom polling detects external file changes while editing, with prompt to reload or keep edits
• Ctrl+S save-and-reload, Ctrl+Enter save-and-stay, Ctrl+P toggle preview
• Draggable split divider to resize editor/preview panels (persisted in sessionStorage)
• Preview panel toggle button for distraction-free editing
• Custom .md-only file watcher with WebSocket hot-reload and exponential backoff reconnection
• Debounced rendering (150ms default, scales to 300ms for 5000+ line documents)
• automatic fallback to the next available port when the default port is busy
• strict explicit port handling with -p
• optional automatic browser reload control with --no-reload

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/showgp/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

Download a prebuilt binary

The easiest way to install go-grip is to download the archive for your operating system from the latest release.

Available release builds:

• macOS: go-grip_<version>_darwin_amd64.tar.gz or go-grip_<version>_darwin_arm64.tar.gz
• Linux: go-grip_<version>_linux_amd64.tar.gz or go-grip_<version>_linux_arm64.tar.gz
• Windows: go-grip_<version>_windows_amd64.zip or go-grip_<version>_windows_arm64.zip

For macOS and Linux:

tar -xzf go-grip_<version>_<os>_<arch>.tar.gz
chmod +x go-grip
./go-grip --help

For Windows, unzip the downloaded archive and run:

.\go-grip.exe --help

Install with Go

If you have Go installed, you can also build and install directly from this fork:

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

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

📦 Releasing

This fork publishes release archives automatically when a version tag is pushed.

git tag v0.1.0
git push github v0.1.0

The release workflow runs tests, builds macOS/Linux/Windows binaries, uploads archives to GitHub Releases, and includes checksums.txt for verification.

[!IMPORTANT] Push release tags one at a time. Do not use git push --tags for releases: if multiple tags are created in one push, GitHub may skip creating tag push events, so the release workflow will not run.

🔨 Usage

To render a single Markdown file, execute:

go-grip README.md

Single-file mode renders only the selected article and adds a table of contents for the current page.

To browse all Markdown files in the current directory, execute:

go-grip
# or
go-grip .

Directory mode opens a local documentation view with a sidebar that links to each Markdown file in the directory. The sidebar title shows the selected directory name. When folders and Markdown files appear at the same level, folders are shown first and entries are sorted by name. The selected article is rendered in the main area with its own table of contents and previous/next article navigation.

You can also open another directory:

go-grip docs

To include Markdown files from subdirectories and show them as a nested sidebar tree:

go-grip -r docs
# or
go-grip --recursive docs

The recursive sidebar is collapsible and keeps the active article visible while browsing nested documents. Previous/next navigation follows the same order as the sidebar, and the left/right arrow keys can move between articles when the page focus is not inside an editable field.

The browser will automatically open on http://localhost:6419. If that default port is already in use, go-grip will automatically try the next available port. You can disable opening the browser with the -b=false option.

You can specify a strict port:

go-grip -p 8080 README.md

When a port is specified explicitly, go-grip will report an error if that port is unavailable.

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

go-grip --no-reload README.md

To terminate the current server simply press CTRL-C.

Editor mode

When viewing a Markdown file, click the Edit button in the toolbar to open the built-in editor. The page switches to a split-screen layout: a textarea on the left for Markdown source and a live preview on the right.

Use the toolbar buttons to:

• Save — writes the content to disk and refreshes the browser preview.
• Cancel / Done — exits edit mode; shows "Cancel" when there are unsaved changes and "Done" when the content matches the saved file.
• Preview — toggles the preview panel on/off for distraction-free editing.
• The split divider between editor and preview is draggable; the position is remembered across sessions.

Keyboard shortcuts while editing:

If the Markdown file changes on disk while the editor is open (e.g., by another program or git pull), go-grip detects the change and shows a dialog: OK reloads the latest content into the editor, Cancel keeps your edits and suppresses further prompts until the next save.

The browser will reload automatically when a .md file changes on disk, unless --no-reload is used.

📝 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.