Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/seagle0128/grip-mode
Instant Github-flavored Markdown/Org preview using grip
https://github.com/seagle0128/grip-mode
Last synced: 4 days ago
JSON representation
Instant Github-flavored Markdown/Org preview using grip
- Host: GitHub
- URL: https://github.com/seagle0128/grip-mode
- Owner: seagle0128
- License: gpl-3.0
- Created: 2019-08-13T17:53:03.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-10-27T13:20:44.000Z (15 days ago)
- Last Synced: 2024-10-27T14:59:50.803Z (15 days ago)
- Language: Emacs Lisp
- Homepage:
- Size: 96.7 KB
- Stars: 274
- Watchers: 7
- Forks: 7
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# grip-mode
[![Build Status](https://github.com/seagle0128/grip-mode/workflows/CI/badge.svg?branch=master)](https://github.com/seagle0128/grip-mode/actions)
[![Release Tag](https://img.shields.io/github/tag/seagle0128/grip-mode.svg?label=releases)](https://github.com/seagle0128/grip-mode/releases)
[![License](http://img.shields.io/:License-GPL3-blue.svg)](License)
[![MELPA](https://melpa.org/packages/grip-mode-badge.svg)](https://melpa.org/#/grip-mode)
[![MELPA Stable](https://stable.melpa.org/packages/grip-mode-badge.svg)](https://stable.melpa.org/#/grip-mode)## Table of Contents
- [Prerequisite](#prerequisite)
- [Install](#install)
- [Manual](#manual)
- [Use-package](#use-package)
- [Customize](#customize)
- [Screenshots](#screenshots)
- [Limitations](#limitations)
- [FAQ](#faq)
- [Donate](#donate)Instant Github-flavored Markdown/Org preview using [Grip](https://github.com/joeyespo/grip)
(GitHub Readme Instant Preview) or [mdopen](https://github.com/immanelg/mdopen).## Prerequisite
- [Python](https://www.python.org/)
- [Grip](https://github.com/joeyespo/grip): `pip install grip`### Alternative markdown preview without accessing GitHub API
- [mdopen](https://github.com/immanelg/mdopen): `cargo install mdopen`## Install
### Manual
From melpa, `M-x package-install RET grip-mode RET`.
```emacs-lisp
;; Make a keybinding: `C-c C-c g'
(define-key markdown-mode-command-map (kbd "g") #'grip-mode);; Or start grip when opening a markdown/org buffer
(add-hook 'markdown-mode-hook #'grip-mode)
(add-hook 'org-mode-hook #'grip-mode)
```### Use-package
```emacs-lisp
;; Use keybindings
(use-package grip-mode
:ensure t
:config (setq grip-use-mdopen t) ;; to use `mdopen` instead of `grip`
:bind (:map markdown-mode-command-map
("g" . grip-mode)));; Or using hooks
(use-package grip-mode
:ensure t
:config (setq grip-use-mdopen t) ;; to use `mdopen` instead of `grip`
:hook ((markdown-mode org-mode) . grip-mode))
```⚠️ NOTE: `mdopen` opens `markdown` preview in default browser, and doesn't support emacs webkit preview. ⚠️
Run `M-x grip-mode` to preview the markdown and org buffers in the embedded
webkit browser if Emacs supports (built with `--with-xwidgets`), or in the
default browser (Chrome, Firefox, etc.).[ox-gfm](https://github.com/larstvei/ox-gfm) is optional, but it brings better
rendering for org files.Enjoy! :smile:
## Customize
Run `M-x customize-group RET grip RET` or set the variables.
```emacs-lisp
;; Path to the grip binary
(setq grip-binary-path "/path/to/grip");; Use embedded webkit to preview
;; This requires GNU/Emacs version >= 26 and built with the `--with-xwidgets` option.
(setq grip-preview-use-webkit t);; You can use this variable to define another browser
;; to use when loading previews. By default this value is `nil`
;; meaning use default browser defined by your system.
;; It respects `grip-preview-use-webkit'.
(setq grip-url-browser "custom_browser");; If you want to pass arguements to your custom browser then use
(setq grip-url-args '("arg1" "arg2" "etc"));; A base URL to another GitHub API.
(setq grip-github-api-url "");; A GitHub username for API authentication
(setq grip-github-user "");; A GitHub password or auth token for API auth
(setq grip-github-password "");; When nil, update the preview after file saves only, instead of also
;; after every text change
(setq grip-update-after-change nil);; Preview hostname
(setq grip-preview-host "localhost");; Sleep seconds to ensure the server starts
(setq grip-sleep-time 2);; Choose theme
(setq grip-theme 'dark)
```If you don't set them you may have limitation to access Github APIs. Please
visit [Grip Access](https://github.com/joeyespo/grip#access) for details.You can get the user name and password from `~/.authinfo` like this.
```emacs-lisp
(require 'auth-source)
(let ((credential (auth-source-user-and-password "api.github.com")))
(setq grip-github-user (car credential)
grip-github-password (cadr credential)))
```## Screenshots
![default_browser](https://user-images.githubusercontent.com/140797/62999172-28333480-bea0-11e9-86a3-10ef1be54c16.png "Preview in browser")
![xwidget_webkit](https://user-images.githubusercontent.com/140797/72371426-52369e80-373f-11ea-920a-5b6154852c57.png "Preview in embedded webkit")
## Limitations
- Need to save to preview org buffers due to the performance trade-off.
## FAQ
1. How to resolve the issue: "GitHub Rate Limit Reached"?
You need to set your GitHub username to `grip-github-user`, then
[Creating a personal access token for the command
line](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line)
and set the new token to `grip-github-password`.## Donate
If you think the it's helpful for you, please consider paying a cup of coffee
for me. Thank you! :smile: