DEV Community

loading...
Cover image for Write Effective Markdown in Emacs (with live preview)

Write Effective Markdown in Emacs (with live preview)

Rushan Khan
A full-stack developer that likes making stuff. Oh, and Red Bull.
・3 min read

Do you use Emacs and write a lot of markdown? Or are you interested in learning more about Emacs packages? If yes then this article is for you.

Today we are going to be talking about getting live preview while writing markdown in emacs. This was a problem that I used to face everyday, I couldn't write markdown in emacs because there was no preview, writing blind markdown and then copying pasting it in a web editor, fixing bugs/errors and doing the whole thing over wasn't really efficient and editing text directly in the web editor without evil was painful.

So I looked around and found a great, less popular emacs package called grip-mode which is basically an emacs integration for the command-line python application called grip. Grip starts a live server locally to render a project's README file using the GitHub Markdown API so you can get live preview before pushing to GitHub or using the web editor.
So enough talk let's see how we can make this work.



Installing Prerequisites

The only prerequisites required for this are:

  • Python ;and

  • Grip (just do pip install grip in your home directory)


Installing grip-mode

Grip is available on MELPA so installing it is as simple as doing:

M-x package-install RET grip-mode RET


Setting up grip mode

Now we configure grip mode. The following customizations are supposed to go in your .emacs file or your init.el file, whichever you use.

First we let Emacs know the exact location where the grip binary is installed:

;; Path to grip
(setq grip-binary-path "/absolute/path/to/grip")

;; in my case it is /home/rushan/.local/bin/grip

Enter fullscreen mode Exit fullscreen mode

Note: If you don't know where grip is installed on your system, you can easily check using ~$ which grip the output will be the absoulute path to grip.

Next, we add a hook to start grip mode autmatically when markdown-mode or org-mode is activated:

;; Start grip when opening a markdown/org buffer
(add-hook 'markdown-mode-hook #'grip-mode)
(add-hook 'org-mode-hook #'grip-mode)

Enter fullscreen mode Exit fullscreen mode

You can also specify a browser for the live preview:

;; set a browser for preview
(setq grip-url-browser "google-chrome")

Enter fullscreen mode Exit fullscreen mode

By default or when set to nil grip mode will open up in the system's default browser.

Note: While specifying a name, the name should be the name of the executable program, which means that if you execute the name in shell then that browser should launch.

Also, it is good to update the preview on save to optimize performance, you can do that by:

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

Enter fullscreen mode Exit fullscreen mode

This is the basic setup for grip-mode, other customizations can be found at grip's docs. But Wait! this is not all! If you tried to use grip-mode with this setup you'll notice that it works but it is extremely limited.

By default users which haven't authenticated themselves will only get a certain amount of requests to the GitHub APIs, which is, sadly, less than usable.

To remove this limitation we need to tell grip our username and password (personal access token) for API authentication:

;; GitHub username for API authentication
(setq grip-github-user "your_username")

;; GitHub password or auth token for API auth
(setq grip-github-password "your_personal_access_token")

Enter fullscreen mode Exit fullscreen mode

If you haven't generated a personal access token before, here is how you do it: GitHub Docs.

After this is done your limitation should now be removed, you would still be under a new limit though, but that limit is very generous and should be more than enough for normal usage.


Conclusion

I hope this article was helpful to you guys and please feel free to ask any questions in the comments.

You can also connect with me on other social media platforms :)

Fork me on GitHub

Connect with me on LinkedIn

Read my other stories on Hackernoon

Happy Coding!

Discussion (0)