Front Matter

Front matter optionally starts your file. It contains instructions for things Markdown can't do for you, for example, choosing a theme, inserting Javascript or new style tags into your document, and ensuring each page can have a unique <title> tag.

It is technically a different document from your Markdown article, and it's in a format called YAML.

Here's an example of a page with a title defined in the front matter.

---
title: Who doesn't love static site generators?
---
# My life is now perfect

Thanks to exercise, diet, and mostly, PocoCMS.

This page gives you a somewhat technical overview of front matter, then explains all the front matter options PocoCMS provides.

Formatting rules
Front matter basics

Alphabetical list of front matter options

aside
author
burger
description
footer
header
hide
keywords
lang
nav
pagetheme
robots
sidebar
skip
styles
stylesheets
theme
title

Return to top

Front Matter basics

The simplest PocoCMS Markdown document looks something like this:

hello, world.

It generates the following HTML document:

<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>Powered by PocoCMS</title>
</header>
	<article id="article-poco">
  <p>hello, world.</p>
	</article>
</div><!-- content-wrap -->
	</div><!-- page-container -->
</body>
</html>

You will normally see a more complex structure, with nonprinting commands that start the file:

---
title: "Introducing PocoCMS"
keywords: "static site generator, jamstack, cms"
---
hello, world.

The text between the two --- lines is considered a separate document with no direct relation to the remainder of the file, which is the Markdown portion. It's called front matter by convention, but what lies between the bracketing --- characters is essentially a database in YAML format. This data is used to control the format and output of the HTML files PocoCMS produces.

Here's what happens when PocoCMS generates HTML for the previous example:

<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>Introducing PocoCMS</title>
  <meta name="keywords" content="static site generator, jamstack, cms">
</header>
	<article id="article-poco">
  <p>hello, world.</p>
	</article>
</div><!-- content-wrap -->
	</div><!-- page-container -->
</body>
</html>

In the first example PocoCMS inserted this shamelessly self-promoting <title> tag:

<title>Powered by PocoCMS</title>

That's because an HTML file is not considered valid without a title. As you've already surmised, this portion of the front matter

---
title: "Introducing PocoCMS"
---

Is responsible for this line of HTML:

<title>Introducing PocoCMS</title>

And obviously this line of front matter

---
keywords: static site generator, jamstack, cms
---

Caused a keywords metatag to be inserted into the file:

<meta name="keywords" content="static site generator, jamstack, cms">

Return to top

Formatting rules

The front matter always starts with a dashed line consisting solely of 3 hyphens: ---
The first line of front matter must be the very first line of the Markdown file. Blank lines before the front matter aren't allowed. (If there's no front matter, blank lines are permitted)
The front matter always ends with a line consisting solely of 3 dashes: ---
The dashed lines demarcate YAML front matter but do not include it. That is, the YAML begins after the first dashed line and end before the second dashed line.
Front matter consists of key/value pairs, where the key precedes a colon and the value comes after the colon.
The key name (on the left side, behind the colon) is case sensitive. So while this will create a <title> tag in your HTML document:

---
title: PocoCMS makes cry out with joy
---

This will not:

---
Title: I'm totally invisible
---

YAML documents usually can't be empty. Don't start a file with empty front matter like this:

---
---

aside

Asides appear next to the article content: Anatomy.

When given a filename, use the contents of that file instead of the value supplied by the theme.

---
aside: new-aside.md
---

Filename: new-aside.md

Announcement soon. Check the [news](news.html) page tomorrow!

HTML aside file

You can also use an HTML file. If so, remember to start with an HTML <aside> tag end end with a </aside>. The file extension must be .html.

Filename: aside.html

<aside style="font-size:2em;font-weight:900;padding:0;margin:0;padding-bottom:2em;margin-top:4em;width:auto;-webkit-transform: rotateZ(-90deg);-ms-transform: rotateZ(-90deg);transform: rotateZ(-90deg);">WHAT'S UP?</aside>

Theme README.md vs. individual page

If you put this in the front matter of the theme README.md file, it will be used on every page of the site by default. If you put it in the front matter of an individual page, it will only affect that page.

author

Causes an author metatag to be inserted into the file.

Example

Using this Author declaration in the front matter:

---
author: "Tom Campbell"
---

Causes this metatag to be generated:

<meta name="author" content="Tom Campbell">

Return to top

burger

Defines the list of links used for the burger menu, a fallback menu meant to appears only in small screen formats. It's part of the theme README and is used an alternate to the header, which is often too large for a phone.

Its contents should only be in the form of a Markdown unordered list, like so:

- [Home](https://pococms.com)
- [Github](https://github.com/pococms/poco)
- [Demos](https://pococms.com/docs/theme-demos.html)

You can change what the burger menu icon (indicator) looks like. See burgericon.

Return to top

burgericon

Character or word representing the burger menu.

description

Causes a description metatag to be inserted into the file.

Example

Using this Description in the front matter:

---
description: "PocoCMS is the easiest static site generator available"
---

Causes this metatag to be generated:

<meta name="description" content="PocoCMS is the easiest static site generator available">

Return to top

Controls behavior of the footer, shown in Anatomy.

When given a filename, uses the contents of that file instead of the value supplied by the theme.

Filename: new-footer.md

---
footer: new-footer.md
---
Powered by PocoCMS!

You can also use an HTML file. If so, remember to start with an HTML <footer> tag end end with a </footer>. The file extension must be .html.

Filename: footer.html

<footer>Prices so good it looks like a <span style="padding:0 1em 0 1em;font-size:2rem;color:yellow;background-color:black;font-family:monospace">CRIME SCENE!</footer>

Theme README.md vs. individual page

Return to top

Controls behavior of the header, shown in Anatomy.

When given a filename, uses the contents of that file instead of the value supplied by the theme.

---
header: new-header.md
---

Filename: new-header.md

Powered by PocoCMS!

HTML header file

You can also use an HTML file. If so, remember to start with an HTML <header> tag end end with a </header>. The file extension must be .html.

Filename: header.html

<header style="font-size:3em;font-weight:900;background: #FF0000;background: linear-gradient(to left, #FF0000 76%, #ffff00 6%, #FF0000 100%); -webkit-background-clip: text; -webkit-text-fill-color: transparent;">FIRE!</header>

Theme README.md vs. individual page

Return to top

hide

Suppresses the header, nav, article, aside, or footer, shown in Anatomy.

To hide the aside and the footer, for example:

---
hide: aside, footer
---

Filename: new-header.md

Powered by PocoCMS!

Return to top

keywords

Takes a list of keywords to be used in the keywords metatag.

Example

---
keywords: static site generator, jamstack, cms
---

Generates this keywords metatag to be inserted into the file:

<meta name="keywords" content="static site generator, jamstack, cms">

Return to top

lang

Sets the code HTML uses for its html lang= tag. Defaults to en for English.

Example

Create a simple file with no Markdown at all, just this front matter, which changes the language to Icelandic:

---
lang: "is"
---

Run poco and then view source. You'll see this:

<html lang="en">

Return to top

nav

Controls behavior of the navbar, shown in Anatomy.

When given a filename, uses the contents of that file instead of the value supplied by the theme.

---
nav: new-navbar.md
---

Filename: new-navbar.md

Announcement soon. Check the [news](news.html) page tomorrow!

HTML nav file

You can also use an HTML file. If so, remember to start with an HTML <nav> tag end end with a </nav>. The file extension must be .html.

Filename: nav.html


<nav style="text-shadow: 0 0 30px white;line-height:2em;font-weight:900;font-size:2em;color:white;background:#1F6097;text-align:center;">FOGGY</nav>

Theme README.md vs. individual page

Return to top

header

Return to top

pagetheme

Defines a page theme to replace the global theme if any, on a per-page basis.

---
pagetheme: hero
---

Return to top

robots

Causes a robots metatag to be inserted into the file.

Example

Using this Robots entry in the front matter:

---
robots: "NoIndex"
---

Causes this metatag to be generated:

<meta name="robots" content="noindex">

NOTE

Be careful following this example! It tells search engines not to index your page, which is the opposite of what you normally want.

Return to top

An aside can often be on either the left or the right side of the page. That capability is built into the PocoCMS theme framework.

sidebar lets you choose which side it's on in the obvious way:

---
sidebar: left
---

The options are right or left. The theme will fail silently
if it doesn't support sidebar.

skip

skip lists files and directories you don't want to be published.

Remember that if a directory contains the files index.md, installation.md, and avatar.png, and 401K-info.xls, here's what will happen when you run PocoCMS:

index.md and installation.md will be converted to HTML document files named index.html and installation.html. The the HTML files will be published The Markdown files will not.
By design, all files other than than Markdown files get published. That's because they're assumed to be required for the site. In this example, it makes sense that avatar.png gets published but you may not want the personal spreadsheet with your 401K details published.
Likewise, you probably don't want directories like node_modules, .DS_Store, or .git published. .git is included here for good form but PocoCMS treats directories with that name starts with . as hidden and doesn't publish them.
The answer to these problems is to list what you don't want published in skip as shown below.

Example

---
skip:
- 401k-info.xls
- node_modules
- www
- .git
- .DS_Store
- .gitignore
---

Here are some common items to skip:

---
skip-publish:
- node_modules
- htdocs
- public_html
- www
- .git
- .DS_Store
- .gitignore
---

Return to top

stylesheets

Causes a stylesheet link to be inserted into the file for each file in the list.

Example

Using these stylesheets in the front matter:

---
stylesheets: 
- "../../css/layout.css"
- "https://cdn.jsdelivr.net/npm/@ajusa/lit@latest/src/lit.css"
---

Return to top

styles

Causes a <style> tag to be inserted into the file for each line in the list. Because they are inserted after Stylesheets they override whatever appears in the stylesheets for the current page. It's a good way to develop stylesheets slowly, or to override colors for a light them to make it dark, and vice versa.

Example

Using this styles entry in the front matter to color all your article text blue:

---
styles: 
- "article>p{color:blue;}"
---

HTML generated:

<style>
  article>p{color:blue;}
</style>

Return to top

theme

Defines a theme to be used as the default for all pages in the site. It's also called the global theme informally. It is optional but can only appear on the home page. The global theme can be overridden on a per-page basis using pagetheme.

---
theme: pocodocs
---

Global theme on every page but the home page

Suppose you want to use the same theme on every page but the home page. Take advantage of the way the home

Filename: index.md

---
theme: pocodocs
pagetheme: hero
---

Putting both of these on the home page is perfectly logical. The theme rule causes that theme to be used on every page in the site without your specifying it. The pagetheme rule causes the theme to be overridden for the selected page... which in this case is the home page.

This works only on the home page.

Return to top

title

The title key lets you set a title for your HTML page. This has a number of important benefits.

It will be used for browser tabs open to that page
It may influence search results
It assists screen readers for visually impaired users
It allows you to create a unique title for each page, which is considered table stakes for government accessibility requirements in the USA
It is one of the few tags required to make an HTML-conformant document

Example:

---
title: "Static generator overview"
---

# Static Site Generators

This page would have its title metatag set to Static generator overview.

Return to top

Front Matter

Alphabetical list of front matter options

Front Matter basics

Formatting rules

aside

Filename: new-aside.md

HTML aside file

Filename: aside.html

Theme README.md vs. individual page

author

Example

burger

burgericon

description

Example

footer

Filename: new-footer.md

HTML footer file

Filename: footer.html

Theme README.md vs. individual page

header

Filename: new-header.md

HTML header file

Filename: header.html

Theme README.md vs. individual page

hide

Filename: new-header.md

keywords

Example

lang

Example

nav

Filename: new-navbar.md

HTML nav file

Filename: nav.html

Theme README.md vs. individual page

header

pagetheme

robots

Example

sidebar

skip

Example

stylesheets

Example

styles

Example

HTML generated:

theme

Global theme on every page but the home page

Filename: index.md

title