More about the front matter

I know, it’s been awhile since the last time I posted the last step. But also, I did mention from the past before that I like to break things down into a few pieces so that it’s easier to understand and follow. Therefore, we’re finally here, going back to Hugo once more, now that we’ve got our entire main theme for CBLW completed, content, and everything else.

In this next step, I’m going to have a slight deeper focus on the core component of every static site generator existing today. We call this core component the front matter. Hugo, Jekyll, Octopress, and all those other static site generators will not be able to produce and generate the pages you’ve created via Markdown without this premiere component.

We have already touched base a bit on Hugo’s front matter back on Prep 2, right at the end. It took me a long while to start updating this LBP because I had to watch my class videos and re-read the documentation and other tutorials on Hugo to understand more about handling the front matter component.

And so, let’s get started!

What the heck is a “front matter”?

I’m not very good with giving a direct definition of a front matter, but I can give you an example.

Imagine yourself holding a book in your hands right now. It could be a novel or a textbook, any printed material bound and sold in a bookstore. When you open the book, you’re going to see important pages before you can actually read the text content of that book. You would see the title page, copyright page, table of contents page, a preface or an introduction passage page (common with textbooks), any page in the beginning that would eventually lead you to the main meat of the book.

Those first set of pages from the first page until the page before the actual text content is what we call the front matter.

In the case of static site generators, the front matter will be in the form of a few lines of meta information or more. The static site generator’s core program will be reading these few lines in order to generate a post or a page that will eventually be uploaded to the web server. In every post file, page file, or even just the overall structure of the entire site, the heart of Hugo, Jekyll, and other static site generators would be those first few lines.

TOML, YAML, and JSON

Hugo’s front matter system supports three file types: TOML, YAML, and JSON. TOML is Hugo’s default front matter. You can use YAML or the more popular JSON as an option if you are more familiar or comfortable with them.

Here are three examples of how the front matter would look like in all three formats:

# TOML (Tom's Obvious Markup Language) format

+++
title = "Welcome to my awesome site!"
description = "An intro to CBLW powered by Hugo"
tags = [ "Cardcaptor Sakura", "Sakura Kinomoto", "Syaoran Li", "Intro" ]
date = "2016-06-16"
categories = [
  "General",
  "Random Stuff"
]
slug = "welcome"
+++

Your content (in Markdown) will be down here...

[View Gist @ GitHub]

# YAML (YAML Ain't Markup Language) format

---
title: "Welcome to my awesome site!"
description: "An intro to CBLW powered by Hugo"
tags: [ "Cardcaptor Sakura", "Sakura Kinomoto", "Syaoran Li", "Intro" ]
date: "2016-06-16"
categories:
- "General"
- "Random Stuff"
slug: "welcome"
---

Your content (in Markdown) will be down here...

[View Gist @ GitHub]

// JSON (Javascript Object Notation) format

{
    "title": "Welcome to my awesome site!",
    "description": "An intro to CBLW powered by Hugo",
    "tags": [ "Cardcaptor Sakura", "Sakura Kinomoto", "Syaoran Li", "Intro" ],
    "date": "2016-06-16",
    "categories": [
        "General",
        "Random Stuff"
    ],
    "slug": "welcome",
}

Your content (in Markdown) will be down here...

[View Gist @ GitHub]

We (and Hugo) can identify the formats of the three, not just by the file extension being used (for the config file), but for the Markdown-based files, we can tell which one is which by the following characters:

  • TOML +++
  • YAML ---
  • JSON {}

… as being used at the above examples.

Like I mentioned before on Prep 2 of the LBP: CBLW series, I will be using the default TOML format. I’ve learned a bit of the YAML format from learning Jekyll, and I’m unfamiliar with JSON. For first timers, it’s best you use the defaults first before you start going crazy with your own configurations and customizations.

Front Matter Variables

Read More: Configuring Hugo, Front Matter

There are two places where the front matter is required: Your config.toml (config.yaml, config.json) file and the top of ever Markdown file you create, such as your posts and your static content (the other pages of your site, etc.). Hugo is programmed to look for the variables used in the front matter when you start creating your Markdown-based files .md for your site.

Your config.toml (config.yaml, config.json) file

We already touched base on our configuration file from the last step, but once again, I’d like to go back here again. Because I already deleted the cblw folder from the other example and using my current working folder for this project, the config file that you saw from the other step will be different from the one we’ll be working on this section instead.

At this point, forget about the example that I used at Prep 2. I only used that for tutorial purposes. I will be using the actual files I’m working on for CBLW. The following example below is my current config.toml file, with all the required and optional/custom variables listed. This is tentative, as I may be making a few changes in the near future prior to launching.

Please read the comments in the snippet for explanations:

baseurl = "http://sakusyao.lets-volt.in/commentary" # (required variable) The loction where Hugo will be generating content. Since this is the only section that I want blog-type posts, I gave the direct URL instead of the entire URL of the site
title = "Cherry Blossom, Little Wolf" # (required variable) this section is still part of the CBLW site, therefore I'm keeping the same page/site title
contentdir = "content" # (optional variable) if you decide to use another folder to save your Markdown files to be generated
layoutdir = "layouts" # (optional variable) if you decide to use another folder to save your layouts in
publishdir = "public" # (optional variable) if you want to use another folder for Hugo to save all generated content
defaultExtension = "html" # (optional variable) it's good to add this in anyway, in case you want the "ugly URLs" (http://path.com/folder/bleh.html) instead of the SEO-friendly ones (http://path.com/folder/bleh) 

[taxonomies] # They're just standard blog posts, so I only need two: categories and tags
  category = "categories" # (required variable)
  tag = "tags" # (required variable)
  
[params] # All of these are optional, but I want to add them so I can get some credit. Think of this as the meta tags in your HTML files at the top
  desc = "A 20th Anniversary Commemorative Shrine to Sakura Kinomoto & Syaoran Li of CLAMP's manga/anime series, Cardcaptor Sakura."
  author = "Adri M. P."
  authorURL = "http://lets-volt.in"
  TwitterUser = "adriculous"
  GitHubUser = "adriculous"
  CopyrightHTML = "© 2001, 2016 Adri. Card Captor Sakura © 1996, 2016 CLAMP/ST/Kodansha. Part of the Let's Volt IN! Network."

[permalinks] # How my links are going to look like when we see them on the URL address bar of our browser
     post = "/:year/:slug"

Hugo has a list of available variables that you can use for your front matter (your config file or your Markdown files). You can even make up your own variables too if needed. Read and bookmark here.

Your front matter on all your other files

The config.toml (config.yaml, config.json) file affects your entire site. In this case, it’s the entire Commentary section. You will also require front matter for your other files as well. For this instance, it will be my blog posts (commentaries). If I were building the static pages also using Hugo, I would also need the front matter on every single page as well. Because, as I mentioned before, I’m still new to Hugo, I’m going to make this as simple as I can. I’ll just update my other sections manually unless I’m able to master Hugo fully altogether.

Fortunately, Hugo makes adding front matter for every generated page is easy. We call these archetypes. That will be the next section that we’ll be going over.

Archetypes

Read More: Archetypes

If you can recall Prep 2 of this LBP, Hugo generates a whole entire site structure with its default folders when we tell Hugo to create a new site via the Command Line/Console. The first folder that you’ll see there is the archetypes folder.

In a nutshell, an archetype is an archetypal content file with pre-configured front matter that would populate through every single new content file you create using the hugo command. When we create our archetype files, we do them manually using our favorite text editor/IDE. All archetype files are in Markdown .md file format and are saved/stored in the archetypes folder.

In this LBP, I only care about my commentaries (blog entries) to have a date, title, the categories they belong to, keyword tags (optional), and the entry’s slug (for pretty URL purposes). We will be creating our default archetype folder with the necessary variables so that Hugo will know what variables will be generated on the final content file.

  1. Open up your text editor/IDE and create a new file.
  2. Save your file as default.md.
  3. Let’s create our front matter with the necessary variables. When we start creating our content files, Hugo will automatically generate the date and title variables (as Hugo will base the creation of the file on today’s date, for example), so we don’t need to add that. However, we will be adding three variables in our front matter: categories, tags, and slug. I am using the TOML format, but I added all three formats in one code block below:
  4. Save your file. You’re good to go.

Custom Archetypes

I haven’t quite decided yet on whether I would be adding any special posts in the Commentary section, but eventually, I will once the shrine begins to grow. I decided to get ahead of myself and introduce this section, now that we’re talking about archetypes.

Let’s say, I decided to write TV episode reviews of Card Captor Sakura (the upcoming sequel anime. We don’t know when that will be released… probably next year or so). For TV episode reviews, I want to have the following generated in these posts: episode number,  episode title, date aired, and my rating for that episode. I also want these episode reviews in its own category, TV Episode Reviews, and a slug variable for pretty URL purposes. I will have to create a new archetype file separate from the default.md file I just created.

  1. Open up your text editor/IDE and create a new file.
  2. Save your file as epreviews.md.
  3. Create our front matter. Keep in mind that Hugo generates the date and title when we create our post, so we need to add our own variables for our TV episode review post. The front matter should look like this:
    +++
    epNumber = ""
    epTitle = ""
    dateAired = ""
    categories = ["TV Episode Reviews"]
    slug = ""
    
    +++
    
  4. Save your file. Good to go.

You can create as many archetypes as you want, the possibilities and customizations are endless. This is very helpful if you have a very elaborate blog/content-heavy site. You can even create a special archetype for your static sections too (the non-blog pages) if you want them to look a lot different than your default posts.

Time for some action!

Let’s do a test run to be sure that our archetypes work properly. We will be creating our very first post. This time, you will need your CLI (command line interface)/console, just like how we used it when we first installed Hugo in our system in Prep 2. Just take a look at the screenshot below and its notes.

hugo_newfile

Next, open up your new welcome.md file in your text editor/IDE. It should be located in your content/post folder, like the one you see below:

hugo_samplefile

Your file should look like this, just as the way we set up in our default.md archetype file.

welcomemd_frontmatter

And from here, we can fill in the blanks and begin our post in Markdown, like so:

welcomemd_frontmatter2

Next …?

We’ve only just begun, and setting up our front matter files should always be the priority whenever we build a site with Hugo. The more complicated, difficult stuff is still up ahead.

Till next time!