Content

The internal content model of Hagen is based on JSON structures. This is coming from the fact that Hagen uses various technologies, like Handlebars and JSON path, which are all based around JSON. And while you still can create complex objects in JSON, the content model is still limited to the JSON primitive types (string, number, boolean, …).

When building, Hagen it will load all content from the content directory in the root of the project. It will iterate through the directory structure, and build a single model out of all information it can find, and understand. Including the directories themselves.

Different content types

The content loader will iterate through the content directory, and start loading all files and directory entries. The initial entry in the content tree will be the content directory itself.

The basic structure of a content entry is:

metadata:
  name: index         # The basename of the file
  parent: /about      # The parent directory, relative to the content root
  type: md            # The content type
  filename: index.md  # The name of the source file
frontMatter:          # A map of all front matter, may be an empty map '{}'
  title: About
content:              # The section specific to the content type

Directory

A directory will load the content section with a map of all files and directories it can find an parse:

content:
  file-1: {}
  file-2: {}
  directory: {}

It will also iterate through all sub-directories, and load them into the map as well, so a more populated directory might look like this:

metadata:
  name: about
  type: directory
  parent: /
  filename: about
content:
  index:
    metadata:
      name: index
      type: md
      parent: /about
      filename: index.md
    frontMatter:
      title: About
    content: "## About\n\nAbout this site..."
  help:
    metadata:
      name: help
      type: directory
      parent: /about
      filename: help
    frontMatter: {}
    content:
      index:
        metadata:
          name: index
          type: md
          parent: /about/help
          filename: index.md
        frontMatter:
          title: Getting help
        content: "## Help\n\nContact us..."

Plain text

A plain text file will simply load the content of the file into the content section:

metadata:
  name: robots
  parent: /
  type: txt
  filename: robots.txt
frontMatter: {}
content: "Sitemap: {{ absolute_url "/sitemap.xml" }}"

Front matter will be loaded as described in Front matter.

YAML

YAML files are parsed and the content loaded as content section. Assuming you have a file site.yaml like this:

title: My Site
language: en-US
menu:
  - label: About
    url: /about/

The the content will be:

metadata:
  name: site
  parent: /
  type: yaml
  filename: site.yaml
frontMatter: {}
content:
  title: My Site
  language: en-US
  menu:
    - label: About
      url: /about/

Markdown

Markdown is similar to plain text, as the mark down content will be parsed later on, using a helper function named markdownify. So a simple markdown file named index.md like this:

---
title: About
---
# About

About this site...

Would translate into:

metadata:
  name: index
  parent: /about
  type: md
  filename: index.md
frontMatter:
  title: About
content: "#About\n\nAbout this site..."

Front matter

Front matter is additional information, metadata, which can be attached to a page. It is not content, which is should render as part of the normal content, but used elsewhere, like a publishing timestamp, additional information for Twitter, the author, …

Text files (like md files), allow to prefix the main content, with front matter like this:

---
foo: bar
---
Actual content

The first line of the file must be --- (three normal dashes). Everything after this line, until the next occurrence of --- will be parsed as YAML, and set into the front matter field.

If the YAML cannot be parsed, Hagen will abort. If the front matter section is missing, then the front matter section will simply be empty.

Different representations

In addition to the full data model, Hagen also transforms this into a compact form, which might be handy in some scenarios. The compact format is generated from the complete one by only using the content sections.

The following full model:

metadata:
  name: content
  parent: /path/to/root
  filename: content
  type: directory
frontMatter: {}
content:
  about:
    metadata:
      name: about
      parent: /
      filename: about
      type: directory
    frontMatter: {}
    content:
      index:
        metadata:
          name: index
          parent: /about
          filename: index.md
          type: md
        frontMatter:
          title: About
          layout: default
        content: "## About\n\nSome more content"
  site:
    metadata:
      name: site
      parent: /
      filename: site.yaml
      type: yaml
    frontMatter: {}
    content:
      title: My Site
      language: en-US
      menu:
        - label: Home
          url: /
        - label: About
          url: /about/

Would be translated into the compact model as:

about:
  index: "## About\n\nSome more content"
site:
  title: My Site
  language: en-US
  menu:
    - label: Home
      url: /
    - label: About
      url: /about/

So instead of using .full.content.site.content.title you could also use the shorter form .compact.site.title.

Dumping

In order to better understand how the content directory translates into the content model and to make it easier to debug, you can output the internal content model as a YAML structure by passing -D or --dump as a command line argument. This will generate the files content.yaml and compact.yaml in the output directory.