BiPandoc is a document synchroniser, a generalisation of document converters such as pandoc: A converter takes one file as input and outputs it in another format, whereas a document synchroniser takes two files (in two formats) as input, one source file and one destination file, and transfers the contents (parts that are meaningful in both formats) from the source file to the destination file. Additionally, when synchronising it tries to keep parts in the destination file that are only meaningful in its own format untouched as much as possible. For example, a markdown-to-html synchroniser transfers the contents of a markdown file into an html file and tries to keep the preexisting comments, attributes, spaces, etc. in the html unchanged. A synchroniser can be used as a converter by taking the destination file to be the semantically empty file of the format.
A typical application of document synchronisers is collaborative writing: Sometimes one author favours writing in format A, say markdown, while another prefers writing in html to do more styling with css. With a synchroniser, they can share their essential contents while writing freely in their own prefered formats.
This project BiPandoc is a synchroniser written with Haskell and the bidirectional programming language BiGUL. As a consequence of programming in BiGUL, BiPandoc is guaranteed to have the roundtrip property: synchronising from B to A immediately after synchronising from A to B leaves A unchanged.
DISCLAIMER: the tool was written by Zirun Zhu and me many years ago and never maintained. Neither can it handle the full syntax of html and markdown. I eventually put it on github because I realised the idea of building document synchronisers is worth some spreading.
The recommended way to build BiPandoc is with stack: Simply running
$ stack setup
$ stack installwill prepare the needed Haskell toolchain for the project and build the tool.
$ bipandoc -f FORMAT_1 -t FORMAT_2 SRC_FILE [-o OUTPUT_FILE] [-d DST_FILE]takes SRC_FILE as input and synchronisers into DST_FILE, and the result is written to OUTPUT_FILE (which is usually the same as DST_FILE).
If DST_FILE is not given, bipandoc simply converts SRC_FILE into FORMAT_2.
FORMAT_1 and FORMAT_2 can be markdown, html and html-body.
The difference between html and html-body is that the former must contain a root <html>...</html> element while the latter shall contain
only the elements inside <body>...</body>.
See bipandoc --help for more options.
The bipandoc.vim subdirectory is a useful vim interface for BiPandoc.
After installing it with your favourite vim plugin manager (like vim-plug and vim-pathogen), call :BiPandocBindThisHTML and :BiPandocBindThisMD at the appropriate vim window/buffer/tab to let the BiPandoc plugin associate two markdown/html files.
Then call :BiPandocStartSync and after this whenever you save one of the files, the change will be propagated to the other file through bipandoc.
The following variables can be configured in your .vimrc:
| Variable | Description |
|---|---|
| g:bipandoc_path | The path to the bipandoc executable if it cannot be found by default |
| g:bipandoc_log | If this is non-empty, the output of bipandoc is written to this path |
| g:bipandoc_html_body_only_mode | If 1, the html file only contains contents inside the body tag. Otherwise, the html file must have an html root tag. |
The following gif demonstrates a running:
