@hackage muon0.1.0.7

Static blog generator

muon

Muon is a static blog generator, meaning that it takes files written in convenient markup and converts it to HTML and CSS ready to deploy to a web server.

Installing from Darcs

First, install the package by getting the darcs repo.

$ git clone https://code.kaashif.co.uk/kaashif/muon.git

You can install it using cabal, which you should have installed.

$ cd muon
$ cabal install

After that, assuming you have configured cabal and/or your PATH correctly, muon should be usable. Here are some things you may want to do:

Installing from Hackage

Installing from Hackage using Cabal is as simple as:

$ cabal install muon

Bear in mind this may not be the most up-to-date version, but it will be a stable version.

Using Muon

Initialising a blog:

$ mkdir new-blog
$ cd new-blog
$ muon init

Writing a post:

$ vi posts/new.post

Regenerating the site, creating a tree of files in the ./site directory.

$ muon generate

Previewng the site locally:

$ muon serve

Uploading site to server:

$ muon upload

Multiple commands in sequence:

$ muon init generate upload
$ muon generate serve

Configuring Muon

After "muon init" is run, a file called "config.ini" is created. This is where you configure the blog. By default, it should look like this:

[site]
title=Default site
author=Your Name
tagline=Something descriptive
style=/style.css

[remote]
user=root
server=webserver
dir=/var/www/htdocs/

The [site] section needs little explanation - you can preview the site yourself and see where those strings go. The "style" option denotes the location of a custom CSS file.

The [remote] section is to configure the command run by Muon to upload the site. The command is "rsync -a --delete site/ user@server:dir", with the key words replaced with your SSH credentials on a server. If you're not sure if the configuration is correct, remember: the directory must end in a slash!

Extra Pages

Aside from a homepage, archive, and posts, you might want some extra pages on your site, like "example.com/recipes" or "example.com/laptop". You can add such pages to your site simply by creating a file with the right name in the "pages/" directory of your blog.

For example, if your blog is at "myblog.com" and you want a page at "myblog.com/mypage", edit the file "pages/mypage" and fill it with HTML. Bear in mind, this content will go in between the "header" and "footer" templates, so you don't need to include <body> or <html> tags. Here's how you might do that:

$ cat >> pages/mypage <<EOF
<h2>My Custom Page</h2>
<p>This is a page I made!</p>
EOF

And that's that! Next time you "muon generate upload", the pages will be accessible at "myblog.com/mypage".

Writing Posts

To add a new post, create a new file in the "posts/" directory with the suffix ".post".

When writing posts, make sure you put the title on the first line, the date on the second, and a short description (for the archive) on the third line. The rest should be valid Markdown. See the "posts/" directory after site initialisation for some examples.

In the archive, posts are ordered lexicographically, not by date. This means "aaa.post" will always come above "bbb.post", regardless of the date contained in the file itself. This allows you to decide the order of your posts yourself, if you want to separate tutorials and rants, for example.