Asciidoctor support - review my config

Hello everyone!

I am trying to create a setup that allows me to edit asciidoctor files in a similar way to the Intellij plugin. The features I want are really based around “live preview” functionality, specifically I want the following:

  • Open up the live preview when I open an .adoc file
  • Automatically recompile the .adoc->html5 whenever I save
  • I want to “Auto save” whenever I am in insert mode
  • I want the live preview to “sync” or scroll with my cusor in both the live preview and normal mode.
  • I want to change my editor to colorscheme reeder

So, I have started on this config but it isn’t really working completely. Here is what I have so far:

 define-command asciidoc-start-watcher -override -docstring '
asciidoc-start-watcher: start an async process that looks for changes to the adoc file and compiles it to html5' \
   nop %sh{ {
        echo $PWD/${kak_bufname} | entr asciidoctor  $PWD/${kak_bufname} |
            kak -p ${kak_session}
    } > /dev/null 2>&1 < /dev/null & }

define-command asciidoc-preview -override -docstring '
asciidoc-preview: create a new window to preview compiled asciidoc file
All optional parameters are forwarded to the new window' \
    nop %sh{
        f=$(echo ${kak_bufname} | cut -f 1 -d '.')
        cmd="qutebrowser file:///$PWD/$f.html"
        kitty @ new-window --no-response --keep-focus --window-type $kak_opt_kitty_window_type --title asciidoc-preview $cmd

hook global WinSetOption filetype=asciidoctor %{
    colorscheme reeder
  1. asciidoc-start-watcher - I am thinking of using the CLI tool entr to watch for file changes then run the asciidoctor program to recompile. I don’t think this command works as the debug buffer says I have the wrong argument count. How do I need to write this command?
  2. asciidoc-preview - I am opening up a Kitty window next to my editor that opens up qutebrowser and looks for a local file (the compiled htm5 file). This works by itself.


  1. How can I get the asciidoc-start-watcher command to work?
  2. Can I get some help with my code? I know it is trash.
  3. Is there a better way of achieving my objective?
  4. How can I write the “autosave” command when in insert mode?
  5. How can I write a command that keeps the livepreview and the editor in sync?
  6. Is the WinsetOption filetype aware of asciidoctor?


entr is mostly useful for watching multiple files. Something like

find -type f -regex '.*\.asciidoc$' | entr asciidoctor

I’d just use NormalIdle and InsetIdle hooks to save and re-render the current buffer.

As for jumping to a specific location on the page that seems very difficult. Only way I can think of to do it automatically would be to render as PDF instead of HTML, open it in something like zathura (which has the added benefit of reloading when the pdf changes) and then using zathura’s dbus API (ExecuteCommand method) to try and scroll to the right chunk of text. Might be another tool out there for rendering html/PDF with a nicer API but that’s the best I could find from a quick google. Not going to be easy to jump to the right location because your asciidoc source isn’t 1-to-1 with the resulting document. Text search for the current line seems the best way.

Some of the things you want are easy, some of them are more difficult, some of them… maybe Kakoune isn’t the right layer to set these things up. I have something similar set up when I’m writing Markdown pages, and it works like this:

  • I open a terminal and run:

    echo src/ | entr pandoc src/ -o out/myfile.html

    to automatically reconvert the HTML file whenever I save the file in my editor.

    • actually, I often have a Makefile or similar build tool to build an entire website, not just a single document, but you get the idea
  • I open another terminal ard run:

    livereload out/

    to start a webserver that serves static HTML from the out/ directory, along with a JS blob that reloads the browser when the server notices the file on-disk has changed

    • livereload is a standalone Python tool; there’s some other tool that requires a special server and a browser plugin to do the same job, but this one is entirely self-contained
    • it’s important to keep the output files in a separate directory from the input files, otherwise livereload tends to trigger a reload when the source file changes (even though the source file isn’t displayed in the browser) and then when the target file changes it decides not to trigger a reload because it already did one recently.
  • The livereload tool prints the URL it’s serving on to stdout, I ctrl-click it and my browser opens displaying the page in question.

That’s a bit more involved than just “automatic”, but I usually need those terminals anyway to check for error messages if something doesn’t work. If I save those two commands to and then I can start everything up in seconds and I’m good to go for hours.

  • I want to “Auto save” whenever I am in insert mode

This would be an InsertIdle hook that just executes write.

  • I want to change my editor to colorscheme reeder

This would be a WinCreate hook that just executes colorscheme reeder, although that will change every editor window, not just the one editing the document.

  • I want the live preview to “sync” or scroll with my cusor in both the live preview and normal mode.

I’m not sure how to do this. I don’t know of any browser that provides an API to let an external tool scroll a webpage, except by sending synthetic scroll-wheel events, or adding a JS blob to the page that polls the webserver for commands (like how livereload sends reload commands), or with a browser plugin which would be a whole bunch of work.