Working with content

Let's take the concept of "configuration, not code" further. In this next step, we'll illustrate the ability to modify your site's content, and have those changes reflect globally across all pages in your site. These changes will illustrate the following abilities:

• generating menus automatically,
• specifying multiple context-specific titles for a document (e.g. a page title and a menu title),
• changing URLs and having those changes be reflected universally.

"Separation of content and presentation" is a foundational best practice in web content management. Grow maintains this best practice by allowing you to store all of your content (and structure) in the config files in the /content/ directory of your pod, and not mixing them up with your HTML in /views/.

Content anatomy

Here's the anatomy of a pod's file-based content management. This is where your site's content is defined and stored. Collections and documents are identified internally by their file paths within a pod, so you should generally avoid changing the internal file paths of content files.

Changing content and properties

Now we'll go through an exercise where we change a piece of content and some of its properties. Let's open up the files /content/pages/_blueprint.yaml and /content/pages/team.md. This is the blueprint for content in the pages collection, and the file where the content and config for the team page is stored, respectively. Here's what they look like (with comments explaining each line).

And the content file in the pages collection.

How it works

To build your web site, Grow looks through all of the pod's collections and documents. From each piece of content's configuration, Grow derives both the URL to serve the page at and the template used to render the page. Again, no code determines URLs or templates – just configs – which means you can manage the entire architecture of your site by changing your site configs.

Built-ins and custom fields

Why do some fields start with $? Field names prefixed with $ in YAML front matter are built-in fields. All fields that do not have a $ are custom, user-defined fields. You can reference any field in templates using doc.<field name>. In the above example, you can reference the list of people by using {{doc.people}}.

Tagged fields

Why do some fields end with @? This indicates that they are tagged for message extraction. When you translate your web site, Grow walks all the configs and templates in your pod, searching for tagged strings. Grow extracts all the tagged strings into a message catalog, which can then be translated either by a translator or a translation provider. Ending a field name in @ indicates that you want that field value to be translated – that's all there is to it!

URLs

The ability to easily change URLs (both during and after the development phase of projects) is an important feature and also a good example of the "configuration, not code" philosophy. URLs are defined by a mix of definitions in podspec.yaml, a collection's _blueprint.yaml, and each individual content document.

Currently, the "The Team" page inherits its URL from its blueprint (/content/pages/_blueprint.yaml). Let's override the URL for this page. In team.md, add the following line to the top of the document's YAML front matter.

$path: /custom-team-path/

This causes the "The Team" page to be served at /custom-team-path/. You can verify this by opening http://localhost:8080/custom-team-path/ in your browser. Immediately, all links to the "The Team" page will be updated to point to the page's new URL.

Cascading configs

The above example changes the URL for just the "The Team" page, but what if you wanted to change the URLs for all pages in the /content/pages/ collection? You do that in the collection's blueprint (/content/pages/_blueprint.yaml). Configs cascade from the document-level to the blueprint-level. Any configs present in a document's YAML front matter will override configs from the collection's blueprint.

Changing templates

Just like URL path formats, documents inherit templates from their blueprint too. If you have five pages in a "pages" collection, but need to override the template for just one of the pages (like we do for the "The Team" page), you can do that by specifying the $view field in the document's config.