Creating a Theme

Aoife can create a new theme for you in your /themes directory with the create theme command:

aoife create theme [theme-name]

This command will initialise all of the files and folders a basic theme requires. Aoife themes are written in the Disco templating language which is essentially HTML with a few Aoife-specific tags to inject content-related stuff.

Theme components

A theme comprises template files and static assets (such as CSS and javascript). Below are the files/folders required for a valid theme:

- theme.json
- assets/
- layouts/
--- partials/
--- 404.html
--- archive.html
--- archives.html
--- home.html
--- list.html
--- single.html

These are created by Aoife with the create theme command.

theme.json

This is the theme’s configuration file in JSON format. There are currently three variables within:

  • name The name of the theme
  • description A brief description of the theme
  • minVersion The minimum version of Aoife required to use the theme

assets/

This is where a theme should store all of its static assets - things like CSS, javascript and image files. After building, they will be copied to /public/theme/assets/. Files placed here are accesible from within a theme template file with the tag {{assets} }. For example, if your theme has a stylesheet called styles.css, you might want to organise it as follows:

- assets/
--- css/
------ styles.css

This would then be copied to public/theme/assets/css/styles.css. You can access it from your theme template files with {{assets} }/css/styles.css.

layouts/

This is the meat of the theme. The layouts/ folder contains the various template files which specify how certain pages are rendered. It contains a single folder, partials/ which contains template files (partial views) that can be injected into other template files. It also contains the seven template files listed below:

  • 404.html Detail on how to render the 404 page
  • archive.html Controls how the /archive/index.html page is rendered
  • archives.html Specifies how individual archive year and archive month pages are rendered
  • home.html If a static home page is required, this controls how it’s rendered
  • list.html How to display the default list of content
  • single Default rendering of an individual piece of content

Additionally, a theme can have folders within layouts/ named the same as sections in the site which specifiy how content in those sections is rendered. For example, suppose my content is structured as follows:

content
- index.md
- post
--- first-post.md
- review
--- Die Hard.md
- Another Post.md

I can easily style the appearance of a post and a review differently in a theme with the following structure

- theme.json
- assets/
- layouts/
--- partials/
--- post
------ single.html    // will style http://example.com/post/first-post.html
------ list.html      // will style http://example.com/post/
--- review
------ single.html    // will style http://example.com/review/die-hard.html
------ list.html      // will style http://example.com/review/
--- 404.html
--- archive.html
--- archives.html
--- home.html         // will style http://example.com/index.html
--- list.html
--- single.html       // will style http://example.com/another-post.html

I needn’t specify both a single.html and a list.html file for each section as, if not present, the default single.html and list.html files will be used.

Modified: Dec 7, 2016 at 15:54:18

Aoife v0.9.0 documentation