Building a simple blog
This quick tutorial will get you up and started with a simple blog in no time. Our blog will list posts on the home page and contain just a single page.
Step 1: Install Aoife
Download the latest version of Aoife for your operating system. On macOS, Linux
and 32-bit Windows systems, Aoife comprises two components, an executable file
(aoife or aoife.exe on Windows) and a library folder. On 64-bit Windows systems,
Aoife also comprises a number of required DLLs. Copy all the files in the
download to somewhere in your
PATH. More complete instructions can be found in
the Installing Aoife section.
This quick start is written on a Mac but the commands are identical on any platform.
Once you’ve copied Aoife to your
aoife version from the Terminal
to verify everything’s good. You should see this (maybe a different version
$ aoife version Aoife, a static site generator. Version: 0.8.9
Step 2: Create the basic site framework
Aoife has a simple command for creating a new site that will create all the required files/folders for you to get working. Navigate the filesystem to where you want your site to be stored and execute the following command:
$ aoife create site my-blog
If everything is well, you should see something like the following:
Success ✓ Your new site was created in /Users/garry/Desktop/my-site A single post and a simple page have been created in /content. A simple default theme called 'primary' has been created for you in /themes. Feel free to create your own with aoife create theme [name].
You can check out the contents of your new site with
assets config.json content themes
As you can see, an Aoife site has a very simple basic structure: three folders and one configuration file. Let’s look at them one-by-one:
Anything you put in here will be copied to
/assets in your final site. This is
Every website must have a configuration file at its root in JSON format. The
config.json apply to the whole site. Required and valid options
are detailed in the Configuration section. Additionally, you
can provide site-wide data accessible from themes in this file.
As the name suggests, this is where you store the content of your website.
content you create folders for different sections. Let’s suppose our
blog has three types of content: posts, reviews and tutorials. You would then
create three folders in
tutorial (note I’ve
used the singular form of the word as it looks better in the resultant URLs). The
name of the section is important as it affects not only the final URL but also
the styling applied to the page by the theme (as themes can style sections
differently from one another if you wish). A simple blog doesn’t require any
sections, you can just place Markdown files in the root of the
too if you wish.
This is the folder to place themes you have created or downloaded. They are then
applied by specifying their name in
config.json (read more about themes
Step 3: Add content
Helpfully, when creating a new site, Aoife also creates some dummy content for us.
Aoife creates a post called
Hello World.md in
/content and a simple about
/content/about. You can keep and edit these or delete them and add your
own content. Just use your favourite editor (I use Atom).
If you open up the sample post created by Aoife (
you’ll see an example of (optional) frontmatter which looks like
;;; "title": "Hello World!" ;;;
Note the flanking three semicolons in the frontmatter which separate it from your post content.
Step 4: Set theme
Every site needs a theme and Aoife supports a comprehensive theming system. You
can either create your own or download one made by our community. Helpfully,
Aoife provides a very simple theme for all new sites called
primary that is
based on the lightweight Simple Grid CSS framework. Aoife sets
this as your site’s theme. Using a different theme is easy - just copy the theme
themes in the site root and set the
theme value in
to the theme name. You can read more about this here.
Step 5: Build the site
Building your site is quick and easy. Just navigate to the root of the site
folder in Terminal and type
$ aoife build Success ✓ Site built in 50 ms
Step 6: Upload your site
Simply copy the
/public folder created by the
build command to the root of
your web host and your site is live.