Org-site is a very simple static site generator for Emacs org-mode files that doesn’t rely on Emacs for publishing.

At this moment, the org-site engine supports offline generation of content and git integration. For the first case, you run the generate script in your local machine and then upload the generated code. If you use git, you can keep your code in a repository and execute the generate script remotely via a post-update hook.

Create a template for a page, add any media such as stylesheets and images, create some pages in org-mode and run the orgsite script to produce HTML code. Then upload the code to your web server.

orgsite.py -c config -i /path/to/source -o /path/to/output

-c config

The site configuration file

-i input

The path of the site input files

-o output

The path of the generated HTML

The site configuration file is required when generating pages. All options have sensible defaults, but it is highly recommended that the main ones (site root, name, author…) are defined. The configuration file is a traditional python text file as understood by the ConfigParser library. The root (and only) section must be called [org-site], and it supports the following options:

root

The site’s root URL (default: /)

name

The site’s name

default_template

The name of the template file to use by default (default: default.html)

org

The name of the directory containing the org files (default: org)

media

Name of media directory (default: media)

templates

Name of templates directory (default: templates)

dateformat

The format used to represent dates with datetime filter (/default: “%d %b %Y at %H:%M”/)

fullname

Site author’s full name (default: Anonymous)

alias

Site author’s alias (defaul: anon)

hl_offset

Heading offset used by org-python parser (default: 1)

remove_empty_p

Whether org-python should remove empty paragraphs (default: True)

$ROOT/

• org/
• templates/
• media/

The org directory contains all input files, which can be in subdirectories. The templates dir has Jinja2 templates to control the appearance of the rendered html. Finally, the media folder contains static images, stylesheets that are copied as-is to the output destination.

The orgsite script will traverse each of the directories inside of the org folder. For each of them it will translate any .org file using a template file with the same name (and the .html extension). If pages are inside of a subfolder, then the script will try to use the template called foldername_pagename.html. If it cannot find a suitable template file for a page, it will default to page.html.

There are a number of pre-defined variables that can be used from templates:

page

Contains the information about the page being generated. Attributes for a page object are:

• title: The title of the page, from the #+TITLE property
• fname: The page filename
• date: The value of #+DATE, converted to a datetime
• html: The generated HTML code for the page
• url: The page’s full URL

site

It has a reference to all the pages in the site. Attributes:

• name: The site name
• author_alias: The author alias
• author_name: The author full name
• pages: Access to all pages / folders (e.g. site.pages.posts)

The site variable has access to all generated pages and subdirectories though site.pages. This attribute behaves differently to traverse pages or folders:

• If attributes of site.pages are accessed, they will return a reference to a subdir with the same name, if it exists. (e.g. site.pages.posts will return a reference to the /org/posts directory.
• If the contents of site.pages or any subdirectory are iterated over, a list of pages in the iterated directory will be returned. (e.g. [post.title for post in site.pages.posts] will return a list of page titles in the /org/posts directory.

New custom Jinja2 filters can be defined in filters.py by adding them to the Jinja2 environment in register_filters