orgmode

Compile org-mode markup into HTML using emacs.

To install, run nikola plugin -i orgmode

This plugin implements an Emacs Org-mode based compiler for Nikola.

Setup

If your emacs does not ship with org-mode (>=8.x), you will have to edit the init.el file supplied with this plugin, and load a newer version of org-mode.

You will also need to add the orgmode compiler to your list of compilers, and modify your POSTS & PAGES variables. (See the sample conf file provided.)

Syntax highlighting with pygments

By default, the plugin uses pygments for syntax highlighting. You can disable this by setting nikola-use-pygments to nil in init.el or conf.el (see Customization section below).

To get proper syntax highlighting, you will need to add custom CSS to your theme. You can generate this CSS using the pygmentize command as follows:

mkdir -p files/assets/css
pygmentize -S <PYGMENTS_STYLE> -a .highlight -f html >> files/assets/css/custom.css

and make sure that custom.css is included in your site by your theme. The various available style options for <PYGMENTS_STYLE> can be found using the command pygmentize -L style.

Customization

You can add any customization variables that you wish to add, to modify the output generated by org-mode to conf.el inside the plugin directory. This lets you have custom configuration, that doesn't get wiped out each time the plugin is updated.

Teasers

You may use teasers by enabling INDEX_TEASERS = True in conf.py, and use {{{TEASER_END}}} to generate <!-- TEASER_END --> in org posts.

Image URLs

The image url in ox-html is a little fuzzy. For example, [[/images/test.jpg]] will be generated as <img src="file:///images/test.jpg" alt="test.jpg"> because the path is considered as an absolute file path.

If you add inline images with built-in file scheme to see them on your Emacs orgmode, the references are resolved. For examples, you may refer with [[file:../images/test.jpg]] to review an image stored on images directory during writing, then it will be generated as <img src="images/test.jpg" alt="test.jpg">.

Alternatively, you may write [[img-url:/images/test.jpg]], and then it should be generated as <img src="/images/test.jpg" alt="test.jpg">.

Suggested Configuration:

# NOTE: Needs additional configuration in init.el file.

# Add the orgmode compiler to your COMPILERS dict.
COMPILERS["orgmode"] = ['.org']

# Add org files to your POSTS, PAGES
POSTS = POSTS + (("posts/*.org", "posts", "post.tmpl"),)
PAGES = PAGES + (("pages/*.org", "pages", "page.tmpl"),)

Requirements:

Issues? Questions?

You can report issues with this plugin and request help via GitHub Issues.