Skip to content

Instant Github-flavored Markdown/Org preview using grip

License

Notifications You must be signed in to change notification settings

seagle0128/grip-mode

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

grip-mode

Build Status Release Tag License MELPA MELPA Stable

Table of Contents

Instant Github-flavored Markdown/Org preview using Grip (GitHub Readme Instant Preview), mdopen or go-grip.

Prerequisite

Alternative markdown preview without accessing GitHub API

  • mdopen: cargo install mdopen
  • go-grip: go install github.com/chrishrb/go-grip@latest

Install

Manual

From melpa, M-x package-install RET grip-mode RET.

;; 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

;; Use keybindings
(use-package grip-mode
  :ensure t
  :config (setq grip-command 'auto) ;; auto, grip, go-grip or mdopen
  :bind (:map markdown-mode-command-map
         ("g" . grip-mode)))

;; Or using hooks
(use-package grip-mode
  :ensure t
  :config (setq grip-command 'go-grip) ;; auto, grip, go-grip or mdopen
  :hook ((markdown-mode org-mode) . grip-mode))

⚠️ NOTE: mdopen opens markdown preview in default browser, and doesn't support emacs webkit preview. ⚠️

⚠️ NOTE: go-grips runs locally, does not use the github API, and supports 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 is optional, but it brings better rendering for org files.

Enjoy! 😄

Customize

Run M-x customize-group RET grip RET or set the variables.

;; Command: auto, grip, go-grip or mdopen
(setq grip-command 'auto)

;; Theme choice
(setq grip-theme 'auto)

;; Use embedded webkit to preview
;; This requires GNU/Emacs version >= 26 and built with the `--with-xwidgets` option.
;; mdopen doesn't support webkit preview.
(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.
;; Only available for `grip'.
(setq grip-github-api-url "")

;; A GitHub username for API authentication
;; Only available for `grip'.
(setq grip-github-user "")

;; A GitHub password or auth token for API auth
;; Only available for `grip'.
(setq grip-github-password "")

;; Preview hostname
;; Only available for `grip'.
(setq grip-preview-host "localhost")

;; When nil, update the preview after file saves only, instead of also
;; after every text change
(setq grip-update-after-change nil)

;; Sleep seconds to ensure the server starts
(setq grip-sleep-time 2)

If you don't set them you may have limitation to access Github APIs. Please visit Grip Access for details.

You can get the user name and password from ~/.authinfo like this.

(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

xwidget_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 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! 😄

Alipay      Wechat Pay

PayPal      Buy Me A Coffee
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy