Quickstart

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 PATH, type aoife version from the Terminal to verify everything’s good. You should see this (maybe a different version number):

$ 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 ls:

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:

assets

Anything you put in here will be copied to /assets in your final site. This is good place to store images or global javascript files for example.

config.json

Every website must have a configuration file at its root in JSON format. The settings within 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.

content

As the name suggests, this is where you store the content of your website. Inside 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 content titled post, review, 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 content folder too if you wish.

themes

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 here).

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 page in /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 (/content/Hello World.md), you’ll see an example of (optional) frontmatter which looks like this:

;;;
"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 folder to themes in the site root and set the theme value in config.json 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:

$ 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.

Modified: Dec 17, 2016 at 19:44:55

Aoife v0.9.0 documentation