https://github.com/brege/ghrm-hugo
A NeoVim plugin and Hugo server for previewing GitHub-flavored README's in a browser
https://github.com/brege/ghrm-hugo
github-flavored-markdown github-readme hugo lua markdown neovim nvim readme theme
Last synced: 14 days ago
JSON representation
A NeoVim plugin and Hugo server for previewing GitHub-flavored README's in a browser
- Host: GitHub
- URL: https://github.com/brege/ghrm-hugo
- Owner: brege
- Created: 2026-03-30T07:55:04.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-20T00:27:40.000Z (about 2 months ago)
- Last Synced: 2026-04-21T07:23:45.558Z (about 2 months ago)
- Topics: github-flavored-markdown, github-readme, hugo, lua, markdown, neovim, nvim, readme, theme
- Language: Python
- Homepage:
- Size: 110 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ghrm
> [!IMPORTANT]
> This project has been superseded by [brege/ghrm](https://github.com/brege/ghrm), based on Rust.
> This implementation, which is based on Hugo with Python wrappers, has reached its architectural limit.
Preview GitHub-flavored Markdown locally using Hugo. Renders admonitions, Mermaid diagrams, KaTeX math, GeoJSON/TopoJSON maps, and light/dark theme toggling all whilst matching GitHub's README style.
## Ethos
People who lose internet and power often: this tool is for you. It renders Markdown the exact same way as GitHub would. If you are offline and still need to make meaningful contributions, focusing on documentation is often the cromulent choice (no coding agents, no Wikipedia/GitHub available, etc).
The point of this tool is **offline preview**. Install once, then keep working with no network connection when power, internet, or both are unreliable.
## Requirements
- [Hugo](https://gohugo.io/) >= 0.132
- [uv](https://docs.astral.sh/uv/)
## Install
```bash
git clone https://github.com/brege/ghrm.git
cd ghrm
make install
```
## Usage
```bash
# one file
ghrm README.md
# multiple files, recursively
ghrm .
```
Opens a live-reloading preview in your browser. Edits to the file are reflected automatically.
## Neovim
Add to your lazy.nvim config:
```lua
{ "brege/ghrm", ft = "markdown", config = function() require("ghrm").setup() end }
```
Commands: `:Ghrm` to start, `:GhrmStop` to stop, or just exit nvim.
## Supported Features
- **Works offline**
- GitHub alert admonitions (`[!NOTE]`, `[!TIP]`, `[!WARNING]`, etc.)
- Collapsible `` sections and normal Markdown formatting and highlighting
- Mermaid diagrams
- KaTeX math (inline, display, and fenced `math` blocks)
- GeoJSON and TopoJSON maps
- Light/dark theme toggle
### Examples
- [Basics](test/basics.md)
- [Diagrams](test/diagrams.md)
```bash
ghrm README.md
ghrm test/basics.md
ghrm test/diagrams.md
ghrm .
```
## Uninstall
```bash
make uninstall
make clean
```
## License
[GPL-3.0](LICENSE)