Getting Started
This tutorial does not cover the installation of mulder. For information on how to install mulder, as well as .NET or Mono, check out the Installation page.
Mulder also requires a basic level of experience with C#. It is possible to use mulder with no C# knowledge, but to take full advantage of mulder, you’ll need to know C# well.
Mulder is a command-line application. This means that in order to use mulder, you have to type geeky commands into a terminal all day.
A mulder-powered site is a directory with a specific structure. In this tutorial, we’ll create a site named tutorial. To create this site, type into the terminal:
% mulder create site tutorial
If you did that right, you should see something like this in the terminal:
% mulder create site tutorial create config.yaml create Rules create layouts/default.html create content/index.html create content/stylesheet.css Created a blank mulder site at 'tutorial'. Enjoy! %
The mulder-powered site named tutorial has now been created. Go into the directory and list the files there. You should see something like this:
% cd tutorial tutorial% ls -l total 24 -rw-r--r-- 1 dale staff 692 Feb 17 14:44 Rules -rw-r--r-- 1 dale staff 100 Feb 17 14:44 config.yaml drwxr-xr-x 4 dale staff 136 Feb 17 14:44 content drwxr-xr-x 3 dale staff 102 Feb 17 14:44 layouts drwxr-xr-x 3 dale staff 102 Feb 17 14:44 lib tutorial%
What all those files and directories are for will all become clear soon.
Before doing anything else, make sure the current working directory is the site you just created. All mulder commands, except for create site, require the current working directory to be a mulder site. So, if you haven’t done it before:
% cd tutorial tutorial%
Every new mulder site already has a bit of content. It comes with one simple page with some simple "getting started" instructions. Before you can view the site, it needs to be compiled. To compile the site, do this:
tutorial% mulder compile
This is what’ll appear in the terminal while mulder is compiling:
tutorial% mulder compile Loading site data… Compiling site… create public/index.html create public/style.css Site compiled in 0.061s. tutorial%
A file named index.html and style.css have been created in the public directory. Add the site to a web server pointing the root to the public directory. If you're on a Mac, I like to use Pow to test my sites. In a future version of mulder, there are plans to run an internal web server to make viewing easier.
Now, open your web browser and navigate to the website based on how your web server works. What you’ll see is something like this:
You can also open the public/index.html file in your favourite text editor, where you’ll find that the file is just a normal HTML page.
The first step in getting to know how mulder really works will involve editing the content of the home page. First, though, a quick explanation of how uncompiled pages are stored.
The pages in a mulder site are stored in the content directory. Currently, that directory has only two files: index.html and stylesheet.css. The first file forms the home page, while the second file is the stylesheet. If you open the index.html file, you’ll notice a section containing metadata in YAML format at the top.
Let’s change the content of the home page. Open index.html and add a paragraph somewhere in the file. I recommend something like this:
<p>This is a brand new paragraph which I've just inserted into this file! Gosh, I can barely control my excitement!</p>To view the changes, the site must be recompiled first. So, run the compile command. You should see something like this:
tutorial% mulder compile Loading site data… Compiling site… create public/index.html create public/style.css Site compiled in 0.061s. tutorial%
Make sure that your web server is still running, reload the page in your browser, and verify that the page has indeed been updated.
In the same file, let’s change the page title from "Home" to something more interesting. Change the line that reads title: "Home" to something else. The file should now start with this:
---
title: "My New Home Page"
---The metadata section at the top of the file is formatted as YAML. All attributes are free-form; you can put anything you want in the attributes: the page title, keywords relevant to this page, the name of the page’s author, the language the page is written in, etc.
Recompile the site and once again reload the page in your browser. You will see that the browser’s title bar displays the page’s title now. If you’re wondering how exactly mulder knew that it had to update the stuff between the <title> and </title> tags: don’t worry. There’s no magic involved. It’ll all become crystal clear in a minute. (Take a peek at layouts/default.html if you’re curious.)
In mulder, pages are sometimes referred to as "items." This is because items don’t necessarily have to be pages: JavaScript and CSS files aren’t pages, but they are items.
To create a new page or item in the site, just create a file in the content directory. Let's create an about page in the content directory and name it about.html. Open the newly created file and put some text in it, like this:
First add the metadata section:
---
title: My Cool About Page
---
Now the html, making sure you have a newline between the above header and the html:
<h1>My cool "About" page</h1>
<p>This is the about page for my new mulder site.</p>Recompile the site, and notice that a file public/about/index.html has been created. With a web server running, open the about page in your browser and admire your brand new about page. Shiny!
By the way, if you don’t like having a metadata section at the top of every page (perhaps because it breaks syntax highlighting), you can put the metadata in a YAML file with the same name as the page itself. For example, the content/about.html page could have its metadata stored in content/about.yaml instead.
The default home page recommended editing the default layout, so let’s see what we can do there.
As you probably have noticed already, the page’s content files are not complete HTML files—they are partial HTML files. A page needs <html>, <head>, <body>, … elements before it’s valid HTML. This doesn’t mean you’ve been writing invalid HTML all along, though, because mulder layouts each page as a part of the compilation process.
Take a look at the default.html file in the layouts directory. Just like items, it contains a metadata section at the top of the file. Open it in your text editor. It almost looks like a HTML page, with the exception of this piece of code:
…
<div id="main">
{{ content }}
</div>
…The odd construct in the middle of that piece of code is an embedded Liquid instruction. The {{ content }} instruction will be replaced with the item’s compiled content by the Liquid filter when compiling. The Liquid filter is the default layout filter after creating a new mulder site. There are plans to add Razor support and the above will be replaced with razor syntax if you choose to use it.
If you are not familiar with Liquid, take a look at the dotliquid page.
The is another important piece of embedded Liquid code near the top of the file:
<title>Mulder Generated Site - {{ item.title }}</title>This is where the page’s title is put into the compiled document.
Every page can have arbitrary metadata associated with it. To demonstrate this, add the following line to the metadata section of the about page:
author: "John Doe"Now output the author name in the layout. Put this piece of code somewhere in your layout (somewhere between the <body> and </body> tags, please, or you won’t see a thing):
{% if item.author %}
<p>This page was written by {{ item.author }}.</p>
{% endif %}Recompile the site, and reload the about page in your browser. You’ll see that the about page has a line saying This page was written by John Doe, while the home page does not—as expected!
You don’t have to write pages in HTML. Sometimes, it is easier to use another language which can be converted to HTML instead. In this example, we’ll use Markdown to avoid having to write HTML. Mulder calls these text transformations filters. If you look at content/index.html you'll notice we're already using markdown.
To learn us some markdown, get rid of the content of the home page (content/index.html) and replace it with the following Markdown-formatted text (but leave the metadata section intact):
# A First Level Header
## A Second Level Header
Now is the time for all good men to come to
the aid of their country. This is just a
regular paragraph.
The quick brown fox jumped over the lazy
dog's back.
### Header 3
> This is a blockquote.
>
> This is the second paragraph in the blockquote.
>
> ## This is an H2 in a blockquoteTo tell mulder to format the home page as Markdown, let mulder run it through the markdown filter. For this, the Rules file is used. This file specifies all processing instructions for all items. It consists of a series of rules, which in turn consist of three parts:
rule type
: This can be compile (which specifies the filters and layouts to apply), route (which specifies where a compiled page should be written to) or layout (which specifies the filter to use for a given layout).
selector
: This determines what items or layouts the rule applies to. It can contain the * wildcard, which matches anything. The default rules file has three rules of each type, and they all apply to all items or layouts.
instructions
: This is the code inside the {…} block and specifies what exactly should be done with the items that match this rule.
These rules are quite powerful and are not fully explained in this tutorial. I recommend checking out the manual for a more in-depth explanation of the rules file.
Take a look at the default compilation rule (the compile '*' { … } one). This rule applies to all items due to the * wildcard. When this rule is applied to an item, the item will first be filtered through the markdown filter and will then be laid out using the default layout. This is how we're telling mulder to format the page through markdown.
Now that we’ve modified our home page and making sure still told mulder to filter this page using markdown, let’s recompile the site. The public/index.html page source should now contain this text (header and footer omited):
<h1>A First Level Header</h1>
<h2>A Second Level Header</h2>
<p>Now is the time for all good men to come to
the aid of their country. This is just a
regular paragraph.</p>
<p>The quick brown fox jumped over the lazy
dog's back.</p>
<h3>Header 3</h3>
<blockquote>
<p>This is a blockquote.</p>
<p>This is the second paragraph in the blockquote.</p>
<h2>This is an H2 in a blockquote</h2>
</blockquote>The markdown filter is not the only filter you can use—mulder currently supports Liquid, as mentioned before, and LESS. You can also write your own filters—tutorial coming soon.
This is the end of the tutorial. I hope that this tutorial both whet your appetite, and gave you enough information to get started with mulder.
There’s more reading material. It’s definitely worth checking out the following chapters; they’re rather big, but they contains everything you need to know about mulder.