Posts Tagged ‘markdown’

A simple Markdown journal in Emacs


I wanted to get into daily journaling since a long time. Keeping a journal makes it easy to find and go back to all kinds of things you have encountered and thus saves time. But more important is, I believe, that journaling structures your thoughts, like any kind of writing. You need to think clearly about something before you can write it down. Then, the act of writing it down anchors it more deeply in your memory.

Alas, all my previous attempts at journaling failed. Whatever the reason, whether on paper or on the computer, I never felt entirely at home with the solutions I tried. So what’s a hacker to do – write his own solution.

I know that there are already many ways to write a journal in Emacs. Well, here’s another one: simple-journal. It’s tiny and simple, it produces a Markdown format that I love, and having it written myself I feel more inclined to actually use it.

The journal looks like this:

### 2010-01-10

- **18:15** - "XML serializations should be hidden away from
  human view lest small children accidentally see them and become
  frightened." - from the paper *Representing disjunction and
  quantifiers in RDF*, McDermottDou02.pdf.

### 2010-01-17

- **14:45** - Set up a minimal Wicket application with Netbeans (a
  first for me, version 6.8) and Jetty. I want to try out working
  asynchronously with JSON using Wicket. Here are the steps to get the
  application running, serving up an empty page:

  - Start a plain Java SE project in Netbeans.
  - ... 

Being in Markdown, it’s very readable, and can readily be converted to well-formatted HTML. The format is completely hard-coded in the code for the moment. The goal was just to quickly get something simple and small working. Nevertheless, I’m always happy about feedback and ideas.

There’s one item on the TODO list that I’d really like to have, but I’m wondering about how to implement it a somewhat simple and efficient way: showing all entries that have “TODO” in them, or that start with “TODO”. Do I have to go through the buffer to collect them and show them in a temporary buffer? That would be a bit more programming than I feel is appropriate for such a task, and the temp buffer wouldn’t be in sync with the journal. Planet Emacs, ideas? ;-)


Announcing md-readme


You can find quite a few Emacs libraries on github these days. I only have one very small project there, wpmail, which I haven’t written about yet because I want to finish the Markdown support first… anyway: something I find really neat on github is the automatic display of the README file in the repository’s root directory, if it exists. Only, as we all know, writing READMEs is tedious and we’d rather spend our time programming. But wait: in the Emacs world, we’re actually writing a README for each project: the library headers. Their content and structure are rather clearly defined, and it’s expected for all Emacs libraries. So I had the idea of generating a nice, Markdown-formatted for github from these headers.

I just pushed the first version of md-readme that does just that. The README that you see on the github page is auto-generated from md-readme.el, with lists, code-block and everything.

The conversion to Markdown is of course pretty simple, but even so it’s pretty cool to see how little code I had to write. Emacs provides everything out of the box. (with-temp-file "" (do-it)) is just elegant.

Now, seeing that we have code that generates a nice README from our Lisp file, it’s natural to have it run automatically so we always have an up-to-date README. Here I was struggling for a while. I had lots of ideas, but none seemed to work out. My current solution is setting a per-directory local variable for each of your ELisp projects that triggers the conversion via an after-save-hook. Code is in the README. The problem with adding the after-save-hook to all modes is that it’s evaluated all the time, for each save. Kinda annoying, even if it’s just a single condition.

Does anyone have a better idea? Do it outside Emacs in a git pre-commit hook?

But even with the current solution it works, and that’s the important part. Please try it, and enjoy your new READMEs.