For the last couple of years, taking notes on a variety of subjects was driving me nuts: I tried it on single sheets of paper (almost no organization and easily lost), within a paper notebook¹ (hard to edit once a page is full) and I tried a combination of web-based tools such as delicious, Asana, Evernote and several others I cannot remember anymore. The drawback of the latter is apparent: once you are disconnected you are out of luck.

Due to this mess, I began to write down new notes in the format to rule them all: Markdown; one file covering a single subject. Although I could serve and edit the Markdown files with Nodewiki, I decided to generate a single, static HTML page with Pandoc to review my notes.

Rendering Markdown content with Pandoc

Pandoc is a document conversion tool that accepts “markdown, reStructuredText, textile, HTML, DocBook, or LaTeX” and outputs amongst others HTML (normal pages and slide shows), EPUB and the mentioned markup formats.

Multiple input files can be passed to Pandoc, thus generating a single HTML file is as simple as

pandoc -s *.md > foo.html

Because the default Pandoc HTML output left everything to be desired, I wrote an HTML template with a toggable table of contents, a style sheet that is easy on the eyes and a Makefile that takes care of generating the final HTML page and pushing it to my server.

UPDATE: I abandonded that repository for a slightly more generic approach that I describe here.

Initially, I also tried Gouda to generate one HTML page per Markdown file. But I didn’t like the rigid structure of the final result and hence sticked with this setup. However, should something more suitable arrive on the scene, I will be prepared with my plain text Markdown notes.

Synchronization with Bitpocket

Instead of using Git, I store the notes in a plain directory and synchronize it with Bitpocket across all machines:

In short, Bitpocket is a small but smart bash script that does two-way directory synchronization resembling Dropbox sync. Simply it just uses rsync to make the actual sync. It runs rsync twice: first syncing from remote to local machine, then from local to remote machine. This way all new files that appeared on remote are fetched to local machine and all new locally created files are replicated on remote machine.

Although, I lose the ability to go back to a previous state as with Git, I don’t have to do the “add, write comment, commit and push” dance, to update a simple note. Until now, I haven’t yet had any problems with Bitpocket in terms of stability or lost data. Knockin’ on wood …