Here is the first post of what could easily become a series around Emacs, as I’ve recently began using it.

What is Org-Mode?

At its core, Org-Mode is an extension that adds todo capabilities to Emacs, but it is much more than that: an agenda, a tool to create slides for presentations, an outliner, a tool to take and organize notes. It also is an alternative to Markdown, as a markup language with its own impressive export functionalities.

Alas, like Emacs itself, Org-Mode is not the most user-friendly thing there is to learn, to put it mildly. Just getting used to the way Emacs works requires a lot of time, efforts and frustrastions. At least, that how the last couple of weeks felt to me. But, imo, it was worth the effort as one quickly discover a lesser-known aspect of Emacs: an editor that is entirely willing to work the way you want it or need it to work. Something that is hard to let-go once you get a taste of it.

Like Markdown, Org-Mode can be used to keep links to other files or to websites. Of course, it can contains links to images too, since images are only files. What’s great is that it can shows the images, instead of their link:

Illustration: an org file, with some text and an image An org files in Emacs, with some text and an image.

To create a link, you use square brackets, like this:

[[https://somewhere-over-the-rainbow][Text of the link]]

Unlike with Markdown, with Org-Mode one must put the link of the URL first, followed by the optional description/text.

The same goes to make a link to a file:

[[/Path/to/the/file][Some description]]

Those two links would be formated like this, without their optional description:

[[https://somewhere-over-the-rainbow]]
[[/Path/to/the/file]]

A links is created as soon as you close the final bracket. Simple.

If the link is to an image, by default it will show the text of the link, not the image. You need to clkick it to open the image in an external image viewer.

To see your images directly in org files, you need to tell Org-Mode to do it, using one of the following methods:

  • Use the keyboard ‘shortcut’ (shortcuts in Emacs rarely looks that short to a beginner’s eyes) C-c C-x C-v. If you are new to Emacs, the letter C stands for Ctrl, so it means: press Ctrl-c, then Ctrl-x and then Ctrl-v.
  • Unless you added a description to your link. Then, instead you should use the shortcut C-u C-c C-x C-v.
  • Oh, and you can also use the global command M-x org-display-inline-images. M stands for Alt, so it reads Alt-x followed by the command org-display-inline-images one is supposed to type (auto-completion is available, though).

WTF is wrong with me? Am I really suggesting that you should consider using this mess? Am I really using it myself? In fact, yes I am using it. As to decide whether you should use it or not, it’s up to you. I don’t C-u C-c C-x C-v every single image in my notes in order to see it. There is no way I would waste my time with that. The solution to avoid that is quite simple: I told Org-Mode to always display images when I open an Org-file, once and for all. And that’it, I now only use the C-u C-c C-x C-v thingy when I need to refresh a file, say after I added a link to a new images — and even for that there probably is some shortcut or setting I’m not aware of.

Note that if I needed too, I could also tell it to always display images only in specific files.

Let’s see how both options work.

Always display inline images in all Org files

Add this line to your Emacs configuration file. It tells Emacs that each time you open an Org file it must display the images instead of its link.

(setq org-startup-with-inline-images t)

If you use this setting and don’t want to see images in a specific file, add this at the top of the org files that are not to display images:

#+STARTUP: noinlineimages

Display inline images in selected Org files only

On the contrary, if you always want to see images save in specific org files:

  1. Don’t add the setq instruction we just saw
  2. Add this line at the top of each file for which you want Emacs to display its images:

#+STARTUP: inlineimages

Conclusion?

As I told you, I’ve only started scratching Emacs and Org-Mode possibilities. Both have a steep learning curve. Add to that Emacs is an old grumpy beast that by default isn’t really that welcoming, that certainly doesn’t help the new/beginning user to find its way around.

The last couple weeks have often been hair-pulling frustrating in that regard, but I also discovered an amazing tool. An editor that can trully be mine, that can look the way I want, that is more than capable to handle anything I throw at it, and that is more than willing to work the way I want it to work.

As far as Org-Mode goes, I’ve not yet commited myself to writing a full book using it — years of Markdown and Pandocs are there — but I’m slowly moving towards that. Meanwhile, I’m using it for note-taking (and as an agenda/todo) and so far it has been more than excellent at that.

More informations