2009-05-21

writing and blogging with org-mode

Already in some previous entry I sang the praises about org-mode, the emacs-mode that is such a nice, flexible way to organize your life. There is so much in org-mode that it's quite hard to fit in here, but thankfully org-mode is documented very well; there's not only the reference manual, there is also a lot of user-provided documentation about how they use org-mode. A nice recent example of that is Bernt Hansen's Org Mode - Organize Your Life In Plain Text!.

I use org-mode for time-management too - I'm using it in a rather simple fashion compared to Bernt Hansen, but find it very useful. I also use org-mode for writing webpages and blogs (like this one), and that is what I'd like to discuss here.

Actually the first time I heard about this org-mode-thing people were raving about, it was for taking notes. Curious as I am, the next time I needed to take notes, I uttered M-x org-mode to try it out, and found how easy and natural it is to write structured, semi-rich-text with org-mode. Some examples:

Markup

I can write headings by starting lines with some stars, the number of stars determining the heading level:

* level 1 heading
  some text
** level 2 heading
   some more text
*** level 3 heading
    even more

org-mode helpfully gives them some different colors; by pressing TAB when I am on a heading, I can hide/show the lower levels and the contents. Nice!

It's also easy to get all the basic markup by decorating your words a bit:

This is *bold* /italics/ _underline_ [[http:/emacs-fu.blogspot.com][Emacs-Fu]]

In org-mode it looks like:

This is *bold* /italics/ _underline_ Emacs-Fu

There are many more things; for example, there's the table editor; I simply type |country|capital|<Enter>|-<Tab> and I get:

| country | capital |
|---------+---------|
|         |         |

Now, I fill in the names in the colums, ending each line with <Alt><Enter> (or M-RET), and org-mode takes care of making everything fit, so we get:

| country     | capital   |
|-------------+-----------|
| finland     | helsinki  |
| netherlands | amsterdam |

You can even insert formulae in the cells, turning this into a simple kind of spreadsheet. Haven't used that yet though.

Blogging

Now, one of the things I use org-mode for is blogging; for that, I need to convert the org-text into HTML; this is simple org-export-as-html (or C-c C-e). I can then copy the HTML into blogger.com or whatever (that might be automatable). You can also export to plain-text, LaTex and other formats.

I found that it makes me a much more productive blogger if can use org-mode; it's so much more convenient to write the mark-up than to write raw HTML. Now, sometimes I might want still want to write some raw HTML, but that can be easily done:

#+BEGIN_HTML
   <button onclick="alert('you are!');">I feel lucky!</button> 
#+END_HTML

in the export HTML this will become: How cool is that?!

However, I only found out about the nicest trick very recently from the org-mailing list.

In this blog, I often use blurbs of code; I'd like to show those blurbs with the syntax-highlighting that emacs gives me. For that, I use the htmlize-package. For example, when showing some Emacs-Lisp code, I would copy that to an Emacs-Lisp buffer, then run htmlize-region on the code, and finally copy the result back in a raw-html block (like the one for the <button>).

I wondered - could I not do that automatically? I could mark code in org-mode as being 'Emacs-Lisp'-code (or Perl, or Python, or …), and when I'd export the html, org-mode would go through the trouble of calling htmlize-region on it and use that in its output. Sounded like a nice idea, I asked for some advise on how to do it.

Five minutes after asking, I got a reply – 'just use #+BEGIN_SRC/#+END_SRC'. Wow – it was already there in org-mode, it's even documented, but somehow I missed that. So, now I can write:

#+BEGIN_SRC perl
   for (my $i = 0; $i != 10; ++i) {
        print "hello, world!\n";
   }
#+END_SRC
#+BEGIN_SRC c++
  for (int i = 0; i != 10; ++i)
        std::cout << "hello, world!" << std::endl;
#+END_SRC

and in the export HTML, this will look like:

for (my $i = 0; $i != 10; ++i) {
      print "hello, world!\n";
}
for (int i = 0; i != 10; ++i)
      std::cout << "hello, world!" << std::endl;

I am impressed.

These were just some of the things I've discovered in the last few months of using org-mode, and I am only scratching the surface. Feel free to share your org-mode-writing tips in the comments :-)

23 comments:

Alex Ott said...

There is also blorg package that allows to create blog from .org files - both xml and html output of data, including labels, etc.

Mekk said...

I use org-mode to plan and write my blog articles, and I like it. Still, I am not 100% happy with the workflow.

Because I don't like to export HTML.

I am used to publish my blog articles using Markdown (my blog engine has an appropriate filter to convert them at runtime). The big benefit is that the text is clearly readable and easily editable. And I happen to refine/revise/patch my articles at least a few times after the publication. Currently I resolve this by using a few editor macros (turn ** into ## in particular) but that's not a great solution.

So, I'd be really happy if org could export markdown (or ReST, or Textile, or something similar).

Less crucial problem is that of splitting an article into the introduction and the remaining text.

djcb said...

@Mekk: this 'blorg' thing mentioned by Alex Ott mentioned could help there (have not tried that myself).

I edit articles as .org's, and only when I'm happy with them, I export them to html. When I have later changes, I can just edit the org and re-export.

I've heard people say it's not *so* hard to write a new export for org, so you might give it a try. The org-community is very helpful with such things at least.

The only small imperfection I now have is that I have to copy the right blob of html from the generated page -- I don't need the head-section, the postambles and the top header (copying to blogger.com). But I'm sure that can be fixed somehow...

Jared said...

Hi,

Have you considered using muse instead of org? I use org to organise myself and I know that recent versions have gained functionality such as syntax highlighting but I think it still lags behind as a convenient way to generate HTML. I could be wrong, I haven't looked into it in any great detail.

djcb said...

@Jared: and I haven't looked into Muse into great detail, so I don't really know what I am missing.

I guess Muse's meaning of life is in creating html, while in Org it's more of an add-on.

But I don't know of any particular feature I am missing right now. Maybe you should write a little article about it? :-)

Alex Ott said...

2gcjb: Yes, Muse is more suitable for creation of sites, while Org-mode is more close to blogs.
My site is created using Muse, but i use blorg to provide RSS with news from my site

netcasper said...

@djcb, the fifth parameter of function org-export-as-html is body-only.

From manual,

When body-only is set, don't produce
the file header and footer, simply return the content of
< body >...< /body >, without even the body tags themselves.

djcb said...

@netcasper: thanks. org-mode rarely disappoints :-)

vinhdizzo said...

hi djcb,

can you describe your workflow of blogging in more details? this is how i currently understand your workflow:

1. create a new org file, with the file name being your post's name.
2. write your post, and then C-c C-e to export into html. Copy and paste the body of the html into blogger, that is, go into a web browser click new post, paste your html, and enter in the name and tags.

do you automate going from org into blogger? if so, can u share your method?

also, suppose you decide to update a post a few months down the line. i'm guessing you would edit your org file as opposed to editing the post in blogger. do u just find the file by hand, edit and export, and then look for the post in blogger by hand, and re-paste the code? or do u have some process to do this?

i blog in blogger, but i would like to do everything in org-mode. however, i'm struggling finding a way to integrate the workflow into blogger.

that 'blorg' package that alex ott mentioned seems GREAT! exactly what i am looking for, to have ONE main blog file and add a new post with a new "*" heading. it also publish feeds. however, there is no "commenting" system, and some features that i would like in a blogging platform.

let me know, thanks.

djcb said...

@vinhdizzo: I think you describe my workflow pretty well. I keep org files in git (new ones and slowly moving old ones there). And indeed, I do the manual copy/pasting of the html. There are some ways to automate that (there is some blogging package for emacs), but I don't fully trust them. Maybe I should look into them once more... I'm sure to blog about it if it works!

erikR said...

Hey, I came up with basically the same workflow as you, but integrated Sweave for R with it. I wrote up my findings at
http://blogisticreflections.wordpress.com/2009/09/20/welcome-to-blogistic-reflections/

djcb said...

@erikR: ah, interesting read! note, the recently added org-babel can be used to execute inline code: http://orgmode.org/worg/org-contrib/babel/org-babel.php, apparently even allowing you to include charts from R. Haven't tried it yet though.

Hendy said...

Hey -- what format do you use when you copy/paste the html? I'm trying to do this as well but org-mode or html pasting preserves the line breaks that are inserted by running in fill minor mode and so I end up having to do TONS of fixing after the export.

Do you not have this problem?

I know one can turn of interpreting newlines as
's, but this also jumbles existing posts. Have you been doing this since you started or just let old posts go to crap or do you have another trick up your sleeve? :)

Thanks!

djcb said...

@Hendy: with blogger at least in the 'Post options' (below the editor box) you can tell it to use the literal html.

I simply paste it there, and that seems to work.

punchagan said...

You may want to try the org2blogger blogging client.

I haven't tried it myself, but I guess your workflow will be much smoother.

http://emacspeak.googlecode.com/svn/trunk/lisp/g-client/org2blogger.el

djcb said...

punchagan: thanks, will give that a try.

Sacha Chua said...

I really like my new workflow with org2blog, which lets me publish subtrees directly from Emacs to Wordpress (http://sachachua.com/blog/2010/09/new-note-taking-workflow-with-emacs-org-mode/). You're on Blogger, though, which might need a different protocol. =)

djcb said...

@Sacha Chua: for blogger, there's org-googlecl; I haven't tried that yet though. Hopefully soon...

elliot said...

This post is pretty old, but apparently I'm not the only one leaving comments in Oct 2010. :)

I recently decided to start a blog and I was excited to see how easy source code formatting could be in org-mode. At least - it's easy now that I have it installed correctly.

I'm on debian and the org-mode package installed htmlize to /usr/share/org-mode/lisp, which wasn't on my load-path. Adding it fixed things (after about an hour of trying to figure out that that was actually the problem). Or, install the emacs-goodies package, which puts htmlize somewhere already on the load-path (at least it did for me).

Thanks for the post.

-e :)

tj said...

I just finished my first emacs related post on blogger (http://tinyurl.com/5s9w6tj) using orgmode html-export and the more simple copy&past approach you described here.

When I do C-c C-e b (export and open in browser) in orgmode the result looks exzellent. But when I copy the html into blogger, there are wide gaps between the paragraphs and a lot of blank lines, which is really unacceptable. I have to edit the text (not the html) by hand and delete all that blank lines, whats really annoying. I tried to delete all blank lines in the orgmode buffer before the export, but the result was basically the same.

Did you experience that kind of problems? How can I conserve the beauty of the org output when copying to blogger?

I did not see any difference when I copied the html with or without the css and js parts. I tried to copy those parts into the design template - still no difference.

Otherwise its great to write in org and simply export, how easy that is.

Paraita said...

nice article, thank to you I just discovered org-mode ! so useful :D

waiting for...what said...

Just gave it a try but it seems the markup of the source code is not exactly like yours.

Actually, I wrote some c++ code but finally found out only comments and string literals are colored. I updated org-mode and htmlize with the latest version but it remained so. :(

Any suggestion? Thanks!!

djcb said...

@waiting for...what: probably best to check the generated html, and see if the corresponding css is defined.