Sunday·10·March·2013
Rendering Markdown, Asciidoc and Friends automatically while Editing //at 15:41 //by abe
Partially because of Markdown being Github’s markup format of choice, I enjoy writing documents in simple markup formats more and more.
There’s though one common annoyance with these formats compared to writing plain HTML…
The Annoyance
They need to be rendered (i.e. more or less compiled) before you can view your outpourings rendered, e.g. in the web browser. So the workflow usually is:
- Saving the current file in your favourite editor
- Switch to terminal with commandline
- Cursor up, Enter
- Switch to your favourite web browser
- Hit the reload button
Using a Specialized Editor with Live Preview
One choice would be to use a specific editor with live rendering. The one I know in Debian (from Wheezy on) is ReText (Debian package retext). It supports Markdown and reStructuredText.
But as with most simple GUI editors, I miss there many of the advanced editing commands possible with Emacs.
Using Emacs’ Markdown Mode
Then there is the Markdown Mode
for Emacs (part of Debian’s emacs-goodies-el package), where
you can get a “preview” by pressing C-c C-c p
. But for
some reason this takes several seconds, opens a new buffer
and window with the rendered HTML code and then starts
(hardcoded) Firefox (which is not my preferred web browser). And if you do that a
second time without closing Firefox first, it won’t just reload the
file but will open a new tab. You might think that just hitting reload
should suffice. But no, the new tab has a different file name, so
reload doesn’t help. Additionally it may not use my preferred Markdown
implementation. Meh.
Well, I probably could fix all those issues with Markdown Mode, it’s only Emacs Lisp. Heck, the called command is even configurable. But fixing at least four issues to fix one workflow annoyance? Maybe some other time, but not as long there are other nice choices…
Using inotifywait to Render on Write
So everytime you save the currently edited file, you immediately want to rerender the same HTML file from it. This can be easily automated by using Linux’ inotify kernel subsystem which notices changes to the filesystem, and reports those to applications which ask for it.
One such tool is inotifywait
which can either output all
or just specific events, or just exit if the first requested event
occurs. With the latter it’s easy to write a while loop on the
commandline which regenerates a file after every write access. I use
either Pandoc or Asciidoc for that since both generate full HTML pages
including header and footer, but you can use that also with Markdown
to render just the HTML body. Most browsers render it correctly
anyway:
while inotifywait -q -e modify index.md; do pandoc -s -f markdown -t html -o index.html index.md; done while inotifywait -q -e modify index.txt; do asciidoc index.txt; done while inotifywait -q -e modify index.md; do markdown index.md > index.html; done
This solution is even editor- and build-system-agnostic (But not operating-system-agnostic.)
inotifywait is part of inotify-tools, a useful set of commandline tools to interface with inotify. They’re packaged in Debian as inotify-tools, too.
Using mdpress for Markdown plus Impress.js based Slides
The ruby-written mdpress is a special case of the previous case. It’s
a commandline tool to convert Markdown into Impress.js based slide
shows and it has an option named --automatic
which causes
it to keep running and automatically update the presentation as soon
as changes are made to the Markdown file.
mdpress is not yet in Debian, but there’s an ITP for it and
Impress.js itself recently entered Debian as libjs-impress.
Nevertheless, two dependencies (highlight.js,
ITP‘ed, ruby-launchy, ITP‘ed) are still missing in Debian.
Tagged as: Asciidoc, Emacs, emacs-goodies-el, GitHub, HTML, Impress.js, inotify, inotify-tools, inotifywait, ITP, Major-Mode, Markdown, mdpress, oneliner, Pandoc, reST, ReText, Ruby, slides, Wheezy
6 comments // write a comment // comments off
Related stories
Comments
Re: Rendering Markdown, Asciidoc and Friends automatically while Editing
Posted by: rul Website: Time: Sun, 10 Mar 2013 17:49 Thanks for the tip, I was also annoyed with the five-steps workflow.
Re: Rendering Markdown, Asciidoc and Friends automatically while Editing
Posted by: azhag Website: Time: Mon, 11 Mar 2013 14:11 > But for some reason this takes several seconds,
You can improve performance by using discount (available in Debian), which is reimplementation of Markdown in C *way* faster than Perl/Python. And instead of C-c C-c p, you can use C-c C-c e (saves document with .html suffix, you can open it in any browser and use F5 on each save ) or C-c C-c m (opens buffer with HTML code, doesn't open browser).
Re: Rendering Markdown, Asciidoc and Friends automatically while Editing
Posted by: Jep Website: Time: Fri, 15 Mar 2013 02:32 You could just write a shell script that monitors your file's modification time, and when it detects change, it compiles your file and switches (with wmctrl) to epiphany's window (which has your html file opened).
Epiphany (or whatever it is called nowadays) has a nice auto-reload feature. Don't really know how it works but it just reloads my local files whenever they're changed. Neat. :)
Re: Rendering Markdown, Asciidoc and Friends automatically while Editing
Posted by: Jack William Website: https://www.google.com Time: Tue, 29 Sep 2020 10:21 great work...
Re: Rendering Markdown, Asciidoc and Friends automatically while Editing
Posted by: helllo Website: mailto:anurag22 Time: Sat, 20 Feb 2021 17:27 343 angel number Thank you for sharing this information with us in a simple language I'm also a blogger and write meaningful content. I got this inspiration of writing through blogs posts like this website. 911 angel number
Your Comment
Spam Protection: To post a comment, you'll have to answer the following question: What is 42 minus 19?
Re: Rendering Markdown, Asciidoc and Friends automatically while Editing
I use this Makefile target: auto: iwatch -c 'make $(AUTO_TARGET)' -e close_write -t '.*\.(mkd|tex)$$'
Reply