Valkertown Home

Setting up Muse to manage Valkertown

Introduction

Well, I choose muse over some others CMS that offers more fancy features than Emacs-muse, most of them offers dynamic websites and some of them offer plug-in architecture. Well I use Wordpress to manage the blog and most of the time it's too much a hassle to keep updated the software and it's meant to handle content which it's updated often and can handle visiting users interact with the content.

The main advantage of using muse over the other content management systems is that everything is handled within Emacs, also some of the fanciest features included in muse is the embedded language tags, which include in the output of snippets of code, these snippets are local and no global behaviour can be achieved without doing some work of your own.

The installing process is fairly simple and the setup process can be as complex as you want, I'm writing this how-to with the intent of having a complex website which produces a set of good looking pages.

Also in the end I'm going give it a try to setup muse for easy writing of my graduate theses.

Installing

Installing muse is no different as many other Emacs, it provides a Makefile for handling the byte-compile and system installation.

You should check now the official Emacs Muse page, you can get the package from there.

There's also another way to get muse other than the official release that's Git M.Wolson Repository. It has the most bleeding edge features and most of the time fixes to the bugs you may encounter.I use the git version for my Emacs.

Now, for preparing muse for installation:

$tar xfz muse-latest.tar.gz
$cd muse-[release]
$make

That will generate the byte compiled version of muse.

On Slackware, Emacs is installed on /usr and not in /usr/local, so I had to edit Makefile.defs and change it there.

I recommend to use checkinstall to manage the installation procedure :

 $ su -c "checkinstall --install"

Well, when using an git repository (it also happens on cvs, svn and others) checkinstall fails to identify some of the information it uses to create the package so pay special attention to the values it presents to you.

That's it, so for me it will copy the elisp and elisp byte-example to /usr/share/emacs/site-lisp/muse.

Preparing Emacs.

Now you have muse installed now it's time to make Emacs use it and become ready to use it.

I must point you to the Quick Start Guide there you will find most of this info and the all of the basic tags of muse. Keep at hand also the Muse Manual.

So for my page I want to use xhtml or html outputs. Also I want to handle everything from the muse-project interface:

So for the .emacs file append:

(require 'muse-mode)
(require 'muse-html)
(require 'muse-project)

Setting up style and project

Muse project uses muse-project-alist to hold all you projects. So for a single project example

(setq muse-project-alist
      '(
        ("valkertown"
         ("path/to/sources" :default "index")
         (:base "my-xhtml" :path "/ftp:user@remote:")
         (:base "my-xhtml" :path "path/to/local/"))
 ))

In the above example the project name is valkertown, the default editing file is the index and it's published with my-xhtml style in a remote and a local path.

So now to define my-xhtml you can do:

(muse-derive-style "my-xhtml" "xhtml"
                   :header "path/to/sources/header.html"
                   :footer "path/to/sources/footer.html")

The above setup will create the my-xhtml style from xhtml and sets the header and footer files that should be included unprocessed in every output file.

Key bindings.

Well I should recommend setting up some keybindings to handle the project, a example that can be reall useful is:

(global-set-key "\C-cf" #'muse-project-find-file)

Since you will be using it quite frecuently.

The rest of the key bindings of muse you can find them in the manual

At last...

Well after that everything is quite simple with muse, get used to the keybindings also explore a bit of the markup in the manuals and you will be writing and publishing incredibly fast.

Now you see how "simple" can be setting this up, you can explore the html output of valkertown to figure out what's in the header and what's in the footer.

How I did add the left menu.

I think there are several ways to do it, yet I did it this way:

On every file I write I put :

<include file="menu.muse">

And on that file you should complement the header and footer files so it will produce the opening and closing tags for divs, the layout should be done in the css file.

header.html: html heading and css including, open body, open content .
menu.muse: muse-parsable, open header, write menu, include contents muse-tag, close header, open main
footer: close main, close content, close body, open-close footer ,close (x)html

Well that's the idea of what I did in this setup. If you use emacs lisp and explore some advaced muse setting you can do something fancier.

This method had a MAJOR drawback that's when you modify menu.muse it will get published alone but not every file which includes the menu. Whe menu changes you should muse-project-delete-output-files before publishing, otherwise your menu will not be updated.

Updated: 2008-07-28 EOC