Readme for muon-0.1.0.4
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.
$ darcs get http://repos.kaashif.co.uk/muon
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.