Getting Started
Table of Contents
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:
(package-initialize) (add-to-list 'package-archives '("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:
blog/ ├── 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 (weblorg-route :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 (weblorg-route :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 (weblorg-route :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 (weblorg-copy-static :output "static/{{ file }}" :url "/static/{{ file }}") ;; fire the engine and export all the files declared in the routes above (weblorg-export)
Weblorg supports site global variables. The default theme optionally uses these 3 variables. Make sure to set
these before calling weblorg-route.
(weblorg-site :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.
