How to add a Portfolio Photo

Candy is ready out-of-the-box to create a simple portfolio of photos. Using Nunjuck layout templates and front matter (with logical defaults) in Markdown files, we can add and tag photos with ease.

Candy Photo Layout

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

The photo.njk template defines a page with full width header (inluding menu) and footer. The rest of the content, including the image is presented in a container powered by a Bootstrap grid.

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 - portfolio.json

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

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

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

Level 3 Front Matter - template yaml

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

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

The following table describes the data elements:

Level 4 Front Matter - photo item yaml

At the highest level, we have front matter defined in the photo item Markdown file itself. Front matter defined here will override any lower level settings, like in the template or portfolio.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, a mainImageFilename, and a date ... or be more involved like this:

---
title: How to add a Portfolio Photo
headTitlePre: "Target Keyword |"
headTitlePost: "| Candy"
date: 2019-03-09
mainImageFilename: candy-eggs
mainImageExt: png
mainImageTitle: Eggs over Candy
mainImageAltText: Candy eggs lying on a pile of candy
metaDescription: This is the meta description of a candy egg photo
tags:
    - candy
    - eggs
---

The following table describes the data elements:

Pulling It All Together ...

The above is a lot of information, but creating a new portfolio photo entry can be super easy. Let's imagine we want to add a new photo file, "my_new_photo.jpg" as a portfolio item. Here is what we need to do:

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

---
title: My New Photo
date: 2019-03-09
mainImageFilename: my_new_photo
tags:
    - newphoto
---

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

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