Installation And Configuration

Download

The prebuilt binary download is here.

Build From Source

If you want to build from source you need some build tools as prerequisites:

1. you need git to checkout the source (alternative you may download the source tar-ball from GitHub)
2. for compiling the sources you need Java 7 JDK or newer
3. also you need Maven 3 as build tool

First clone the repository:

$ git clone https://github.com/Weltraumschaf/JUberblog.git

Then build the project:

$ cd JUberblog
$ mvn clean install

This will install the final binary (juberblog.jar) in the bin/ directory.

Create the Scaffold

JUberblog requires a particular directory layout as storage place of your blog content. You may configure this in various ways. But for the first steps you should use the defaults. To create this structure JUberblog provides the install sub command.

Create the initial scaffold directory for your blog data:

$ mkdir -p /where/you/want/to/store/your/blog
$ juberblog install -l /where/you/want/to/store/your/blog
$ cd /where/you/want/to/store/your/blog

An optional step is making this directory a version controlled repository. If you set up your blog only on a single machine (everything is done on this machine), then this is not necessary. But I recommend it because this gives you the “feature” of versioning of your content. In the examples here Git is used. You may use other tools like Subversion, Mercurial, Darcs etc.

(optional) Make the blog storage directory a repository:

$ git init
$ git add -A
$ git commit -m "Initial commit."

Overview Of The Directory Layout

The scaffolded directory layout consists of four directories:

1. configuration: Here you find an example configuration file. You may put this to any place you want. The JUberblog commands which need this need the path to it anyway.
2. data: This is the directory where you put your blog content. Blog articles goes into the data/posts directory and sites into data/sites. Drafts go into data/drafts. There are also two directories: posts and sites. You get the idea.
3. public: This directory will be the target of the generated and static files served by the web server. The sub directories css, img, and js are only a suggestion. You may change them, but then you have to adapt the templates! The generated files will go into this directory (index.html, feed.xml, and sitemap.xml) and sub directories according to the structure in data.
4. templates: Here are the Freemarker templates used to generate the static HTML.

More information about a particular directory may be found in a README.md in that directory.

Configuration

IMPORTANT: The configuration.properties must be encoded in iso-8859-1, unless umlauts and other special characters will be screwed.

The configuration file has two kinds of options: Some are basic options for the generated content such as the blog title and description etc. And some which tells JUBerblog where to find the directories where the Markdown files, the template files and the published files are.

Templates

JUberblog brings some very basic templates to generate the static content. You can change them to adopt the static generated content to your own custom theme.

+--------------------+
|  laout.ftl         |
|  +--------------+  |
|  |  index.ftl/  |  |
|  |  post.ftl/   |  |
|  |  site.ftl    |  |
|  +--------------+  |
+--------------------+

Markdown Templates

Make Custom Style With SASS

Of course you can style your blog with simple CSS. You only have to put the CSS files somewhere in your public folder served by the web server. Recommended and default is public/css. If you prefer another location you must change the link in the layout.ftl.

But you can also use SASS. For this use case there is a directory called sass in the freshly created scaffold data directory. It also brings a a [normalizer][normalizer] script which sets some sane defaults for all browser. To generate CSS you need SASS installed and use this command from your scaffold dir:

$ sassls sassc sass/main.scss public/css/main.css

Create Posts

TODO

Create Sites

TODO

Preprocessor Directives

The content files for posts and sites support a preprocessor directive to add some meta data:

<?juberblog
    navigation:  some navigation
    description: some description.
    keywords:    some, keywords
?>

The syntax is the same as for XML preprocessor directives. So to start it use <?juberblog and to end the directive use ?>. The directive for JUberblog supports simple key-value pairs. The key must not contain any characters but letters and numbers. The value may contain any character but a colon or newline. The key and the value are separated by a colon. A key value pair is separated by newline. Also obviously you can’t use newlines in the value. The key values will be assigned to the layout template. Description and Keywords are used for the meta tags by default.

The three keys shown in the example above are also used internally for the content generation, but JUberblog will choose sane defaults if you don’t have them in your file.