Docs home Getting Started Configuration Markdown Custom Build Script Theming Support This project is in development. Expect there to be bugs and difficulties. Visit the support page for help.

Themes

Pre-made themes

Building your own theme

The file structure

.
├── build.js
├── includes
│   ├── footer.ejs
│   ├── head.ejs
│   └── header.ejs
├── layouts
│   ├── home.ejs
│   └── post.ejs
├── static
│   ├── logomark.png
│   ├── logomark_sm.png
│   └── search_data.json
└── styles
    └── main.less

build.js custom build commands. Your custom code will be executed on npm run build
includes/ where you should put files you are including (template head, headers, footers, and anything else).
layouts/ where you should put template files. Follow naming scheme layout-name.ejs, where layout-name is what you specified in the layout attribute in your document’s frontmatter.
static anything static in your project. Images, imported stylesheets (like bootstrap), necessary javascript files, or data files should be here. This folder is automatically copied to assets/static/ for use in your templates.
styles/ should include only main.less. Right now, there is not support for includes, and the stylesheet must always be less.

Variables

Alchemy will pass a set of variables to your templates that you can use with ejs syntax.

Frontmatter from each file (the yaml content specified between the ---'s in the top of the markdown) is passed as page and is used as a Javascript Object.
All variables from config.yaml will be passed as the site variable and can be used as a Javascript Object.
The parsed markdown content in the file will be passed as the content variable and is a Javascript string.
The path variable is the relative path of the current page (ending in .html). Path is a string
The filemap variable is an array of every page in a site. It is an array of objects. Each object follows the following syntax:

[{
  fname: 'The name of the file',
  mdpath: 'Path to the markdown source for this page',
  path: 'HTML path of the current page',
  frontmatter: {} // Parsed frontmatter from page
}]

If you are confused about a variable or struggling to implement it, we recommend printing the JSON to the page:

<p><%- JSON.stringify(page) %></p> <!-- or site, content, path, or filemap -->

Step-by-step

For an example, let’s create a super-simple blog theme.

Create the file structure following the tree diagram:

.
├── about.md
├── app.js
├── config.yaml
├── package.json
├── readme.md
├── posts
│   └── hello-world.md
└── theme
    ├── includes
    │   ├── footer.ejs
    │   ├── head.ejs
    │   └── header.ejs
    ├── layouts
    │   ├── home.ejs
    │   └── post.ejs
    ├── static
    │   └── logomark.png
    └── styles
        └── main.less

Create the config.yaml

In config.yaml, paste and edit the following markdown:

# Path to your site (if it is in a subfolder of your server)
root: ''

# Your information:
author:
  name: Jack Crane
  email: jack@jackcrane.rocks

Create a post (for testing)

In posts/hello-world.md, paste the following markdown:

---
layout: post
title: Post Title
---

# Hello World Blog post

This is a blog post

Create the post layout

Copy and paste the following code into layouts/post.ejs:

<html>
  <head>
    <title><%- page.title %></title>
  </head>
  <body>
    <%- content %>
    <a href="mailto:<%- site.author.email %>">Email me</a>
  </body>
</html>