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.
• Sidebar search box: type to filter articles in real time. Directories auto-expand when they contain matching files. Press Escape to clear, or use Ctrl+F / Cmd+F to jump to the search box.

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.
• In-editor image import: click the Import button in the editor toolbar to open an import dialog. Drag & drop images or folders, use the file picker, paste from clipboard, or enter a URL. Single-image imports are inserted directly at the cursor; batch imports go to a pending tray for selective placement.

Additional export support:

• HTML export: export any rendered Markdown file as a standalone HTML page via the toolbar Export HTML button. The exported file inlines all CSS (light theme, syntax highlighting, mermaid, mathjax, clipboard styles), embeds local images as base64 data URIs, and optionally includes MathJax/Mermaid JavaScript for dynamic rendering.
• PDF export: export any rendered Markdown file as a print-optimized PDF via the toolbar Export PDF button. PDF generation uses a headless Chrome/Chromium instance (chromedp) with A4 page layout, proper margins, and a stripped print CSS that removes URL annotations. Local images are embedded automatically. Requires Chrome or Chromium installed on the system.
• Image embedding: local image files referenced in Markdown are automatically converted to inline base64 data URIs in both HTML and PDF exports, making the exported files fully self-contained.

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
• Sidebar search box to filter articles by filename in real time
• 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
• In-editor image import: import images via drag-drop, file picker, clipboard paste, or URL. Single images insert directly at cursor; batches queue in a pending tray for selective placement. Images are copied to an images/ subdirectory next to the edited file with automatic dedup and rename.
• Custom .md-only file watcher with WebSocket hot-reload and exponential backoff reconnection
• Debounced rendering (150ms default, scales to 300ms for 5000+ line documents)
• Export HTML: download any rendered Markdown as a standalone HTML file (inline CSS, embedded images)
• Export PDF: download any rendered Markdown as a print-optimized PDF (A4 layout, headless Chrome/chromedp)
• Image embedding: local images are automatically base64-encoded and inlined in exported HTML/PDF
• 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. Use the search box above the sidebar to filter articles by filename — matching directories auto-expand, and a "No matching files" message appears when no results are found. 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.
• Import — opens the image import dialog. Drag & drop images or folders onto the dropzone, click to browse files, or switch to the URL tab to paste an external image link.
• The split divider between editor and preview is draggable; the position is remembered across sessions.

Keyboard shortcuts while editing:

Importing images

Click the Import button in the editor toolbar to open the image import dialog:

• Local File tab: drag & drop images or a folder (subdirectories are scanned recursively), or click the dropzone to select files. All images are imported to an images/ subdirectory next to the edited Markdown file. A single image can be inserted directly at the cursor; batch imports queue in a pending tray at the bottom of the editor. From the tray, click any thumbnail to insert it at the cursor, or use Insert All to place them all at once (one per line).
• URL tab: paste an external image URL and click Insert to place ![](url) at the cursor immediately.
• Drag & drop onto the textarea: single images are imported and inserted directly at the drop position; multiple images or folders go to the pending tray.
• Clipboard paste: pasting a screenshot or copied image from a file manager imports it automatically — single images are inserted directly, multiple images go to the pending tray.

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.

Export

When viewing a Markdown file, click the Export HTML or Export PDF button in the toolbar to download the rendered document.

• Export HTML downloads a standalone .html file with all CSS inlined (light theme, syntax highlighting, mermaid, mathjax, clipboard) and local images embedded as base64 data URIs. The exported page includes MathJax and Mermaid JavaScript for dynamic rendering.
• Export PDF downloads a print-optimized .pdf file using a headless Chrome/Chromium instance. The PDF uses A4 page dimensions, proper margins, and a print-tailored CSS that removes URL link annotations. Local images are embedded automatically.

[!NOTE] PDF export requires Chrome or Chromium installed on your system and available in PATH. The server lazy-initializes the PDF generator on the first export request.

📝 Examples

🐛 Known TODOs / Bugs

• Export rendered Markdown as standalone HTML
• Export rendered Markdown as PDF (requires Chrome/Chromium)

📌 Similar tools

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