weblorg
weblorg

Theming

One of the central ideas behind Weblorg is to allow web developers to leverage their skills to deliver content with the experience they can build with familiar tools like HTML and CSS. Weblorg defines a convention for packaging a file

It's highly recommended to have read the Getting Started document; this write up assumes that you understand the gist of how to declare routes that point to Org-Mode files and how to execute the publish.el script to generate the static website. That being said, there's enough context in the examples that illustrate this article to allow anyone to follow it.

1 Builtin Themes

The Weblorg melpa package currently ships with two themes: default and autodoc. Unsurprisingly, if no other theme is informed, default is picked.

In order to use a theme that's shipped with Weblorg, use the following on your site configuration (this goes anywhere before declaring the routes):

(weblorg-site
 :theme #'weblorg-theme-autodoc)

2 Disable the default theme

The default theme's function is weblorg-theme-default. If you need to unset the default theme, you can set :theme to nil e.g.:

(weblorg-site :theme nil)

Disabling the default theme might be useful if you want to build your own theme from scratch and want to use weblorg-copy-static to copy your own assets and not include any builtin theme's asset in the copy list.

3 The theme directory

When a directory named theme exists within the root of the website (same level as the publish.el script), then weblorg-route will prioritize looking up templates within theme/templates. And weblorg-copy-static will include theme/assets within it's search for resources to copy.

This is useful for either creating a theme from scratch or overriding a single piece of a theme you're inheriting from. For example, if you only want to override the index template of a theme, create a file named theme/templates/index.html and weblorg will use your file instead of the index.html file from whatever theme you have selected via the :theme option in weblorg-site.

4 Syntax Highlight of source code blocks

For properly generating syntax highlight for Org-Mode source code blocks, the package for such mode must be installed and configured at the time of the HTML generation.

When the HTML generation happens automatically, for example on a continuous integration scenario, that can go within the publish.el template. E.g.:

;; We need this to produce proper syntax highlight if any blog
;; posts include Clojure code in source code blocks.  Notice that
;; built-in modes don't require this.
(require 'clojure-mode)

;; This is not required, but might be desired.  It configures the
;; library that Org-Mode uses to generate syntax highlight with CSS
;; classes instead of HTML font properties.
(require 'htmlize)
(setq org-html-htmlize-output-type 'css)

(weblorg-route
 :name "posts"
 :input-pattern "./posts/*.org"
 :template "post.html"
 :output "./posts/{{ slug }}.html"
 :url "/posts/{{ slug }}.html")

(weblorg-export)