How to add a Blog Post

Candy makes it easy to create a blog. Using a combination of Nunjuck layout templates, front matter (with logical defaults) and Markdown, your workflow from idea to publish is simple.

Candy Post Layout

By default, blog posts added to the site\blog folder use the layouts\post.njk nunjuck template. The post.njk template extends layouts\base.njk template which defines the basic structure of a Candy page.

The post.njk template defines a page with full width header (inluding menu) and footer. The rest of the content, including the main image, article and widgets (similar posts, favourite posts, tags listing) are presented in a container powered by a Bootstrap grid. You can choose to use the post-rsidebar.njk layout to add a right-side sidebar to larger screens holding the favourite posts and tag listing widgets.

Candy Front Matter

Like any Eleventy based project, Candy uses a series of files to set front matter for use in generation of web pages. The front matter is defined in a heirarchy where each successive level can override the values.

Level 1 Front Matter - metadata.json

The file site\_data\metadata.json defines a series of values that are be used site-wide and available to the generation of all pages. The sample file looks like this:

{
  "title": "Candy",
  "url": "https://candy-11ty.netlify.com/",
  "sitemap": "https://candy-11ty.netlify.com/sitemap.xml",
  "twitter": "@wernersiemens",
  "feed": {
    "subtitle": "Candy is a quick-start scaffold for building sites. It's Eleventy with sugar on top.",
    "filename": "feed.xml",
    "path": "/feed.xml",
    "url": "https://candy-11ty.netlify.com/feed.xml",
    "id": "https://candy-11ty.netlify.com/"
  },
  "author": {
    "name": "Werner Siemens",
    "email": "stickhandle@gmail.com",
    "twitter": "@wernersiemens"
  }
}

The individual data items are self-explanatory. Obviously, you will want to update this file with your own site and user values. The values from this file are used in the HEAD of the generated HTML documents to define metadata for seo and open graph.

Level 2 Front Matter - blog.json

All files generated from the site\blog folder have access to site\blog\blog.json data. The Candy sample looks like this:

{
  "layout" : "layouts/post.njk",
  "tags" : ["untagged"],
  "mainImageExt" : "jpg",
  "mainImageSize" : "1600",
  "medImageSize" : "800",
  "thumbImageSize" : "400",
  "tinyImageSize" : "200",
  "excerpt": "auto",
  "similarScore" : 0
}

The blog.json file provide a sane set of default front matter for all the Markdown files in the blog folder. The following table defines the elements:

Defining the Excerpt

The excerpt element can have the following possible values:

Level 3 Front Matter - template yaml

Eleventy allows us to define front matter variables as yaml in the template heirarchy. Since all blog post items are defined in blog.json to use the post.njk template, the attributes are defined:

---
layout: layouts/base.njk
bodyClass: candy-post
templateEngineOverride: njk, md
contentContainerClass: container
---

The following table describes the data elements:

Level 4 Front Matter - blog item yaml

At the highest level, we have front matter defined in the blog item Markdown file itself. Front matter defined here will override any lower level settings, like in the template or blog.json files. In addition, a handful of variables are only defined here since they would be specific only to this one file. The item front matter could be as simple as defining a title and a date, or be more involved like this:

---
layout: layouts/post-rsidebar.njk
title: How to add Blog Posts
headTitlePre: "Target Keyword |"
headTitlePost: "| Candy"
date: 2019-03-09
mainImageFilename: candy_assorted2
mainImageExt: png
mainImageTitle: Assortment of Candies
mainImageAltText: An assortment of hard candies
excerpt: custom
customExcerpt: This is the custom excerpt
metaDescription: This is the meta description
tags:
    - config
    - layouts
    - frontmatter
---

The following table describes the data elements:

Pulling It All Together ...

The above is a lot of information, but creating a new post can be super easy. Let's imagine we want a new post called "My New Post". We also have a hero image file (my_hero_image.jpg) to go along with it. Here is what we need to do:

1. Create a new file in the src\site\blog folder called my-new-post.md.
2. Add the my_hero_image.jpg image file to the src\images folder.
3. Open my-new-post.md and add the following front matter:

---
title: My New Post
date: 2019-03-09
mainImageFilename: my_hero_image
---

4. Add content to my-new-post.md in Markdown format after the front matter.

---
title: My New Post
date: 2019-03-09
mainImageFilename: my_hero_image
tags:
    - newblogpost
---
Here we add our post content in Markdown format.
## An H2 Subtitle
...

5. Build with Eleventy (yarn run build) and serve (yarn run serve). Profit! 😃

The new post will be added to the http://localhost:8080/blog/ page, http://localhost:8080/tags/#newblogpost page, and its own page at http://localhost:8080/portfolio/my-new-post/.