Getting Started

1. Installation

1.1. Via Melpa

The simplest and recommended way to install weblorg is via MELPA. You must have something along these lines on your Emacs configuration for that to work:

 '("melpa" . "http://melpa.org/packages/"))

Then run M-x package-install RET weblorg RET. Notice that you might need to run M-x package-refresh-contents RET if you haven't done that in a while.

1.2. Manually

If you don't want to use any package installer, you can just clone the repository somewhere on your computer, let's say $HOME/src/weblorg. Then add that directory to your Emacs configuration so the library can be found by require.

(add-to-list 'load-path "~/src/weblorg")

2. Setup a website

Weblorg is an Emacs-Lisp API rather than a command line tool. The use of the API becomes the description of a pipeline that takes lists of Org-Mode files as input, templatize them and generate HTML files as an output. Although it can be used just like any other Emacs Lisp API, there are some conventions for creating a weblorg.

2.1. Directory structure

Here's an example of a directory structure that is known to work well:

├── posts/
│   ├── how-far-can-spiders-see.org
│   ├── what-music-do-sloths-like.org
│   └── which-computers-would-crickets-use.org
├── pages/
│   ├── index.org
│   ├── about.org
│   └── faq.org
├── theme/
│   ├── static/
│   │   └── main.css
│   └── templates/
│       ├── layout.html
│       ├── blog.html
│       ├── post.html
│       └── page.html
└── publish.el

Note that the theme directory is only needed if you're creating your own theme or overriding a file of a theme that you're inherinting from.

The publish.el file is where we describe our routes and execute to generate our website.

2.2. Publish script

The publish.el file is where we configure the routes and execute the export. Let's look at an example of script that could be used to generate a blog with the above directory structure.

(require 'weblorg)

;; route for rendering each post
 :name "posts"
 :input-pattern "posts/*.org"
 :template "post.html"
 :output "output/posts/{{ slug }}.html"
 :url "/posts/{{ slug }}.html")

;; route for rendering the index page of the blog
 :name "blog"
 :input-pattern "posts/*.org"
 :input-aggregate #'weblorg-input-aggregate-all-desc
 :template "blog.html"
 :output "output/index.html"
 :url "/")

;; route for rendering each page
 :name "pages"
 :input-pattern "pages/*.org"
 :template "page.html"
 :output "output/{{ slug }}.html"
 :url "/{{ slug }}.html")

;; route for static assets that also copies files to output directory
 :output "static/{{ file }}"
 :url "/static/{{ file }}")

;; fire the engine and export all the files declared in the routes above

Weblorg supports site global variables. The default theme optionally uses these 3 variables. Make sure to set these before calling weblorg-route.

 :template-vars '(("site_name" . "weblorg website")
                  ("site_owner" . "owner@mail.com (owner)")
                  ("site_description" . "owner's personal blog.")))

To generate your blog touched by the unicorn, just run the following shell command:

emacs --script publish.el

To go further and explore what's possible, take a look at the API documentation. It explains every single flag that weblorg-route and all other public functions take.