Pages & Front Matter

Every page on your site is a plain text file with an .md extension. The file has two parts: a front matter block at the top (metadata about the page) and the content below it (what people actually read). Understanding this structure gives you control over how every page looks, how it appears in navigation, and how it connects to the rest of your site.

Adding a new page

In GitHub’s browser editor (press . on your repository page):

1. Right-click in the file tree and choose “New File”
2. Name it ending in .md (e.g. my-new-page.md)
3. Add front matter at the top:

   ---
   title: My New Page
   layout: default
   ---
   

4. Write your content below the front matter
5. Commit and sync

The page is live at /my-new-page once GitHub rebuilds. To put it in a menu, see Navigation.

The front matter block

Front matter is the section between two lines of triple dashes at the very top of a file. It uses YAML syntax—simple key: value pairs that tell Jekyll how to handle the page.

---
title: My Page Title
layout: default
date: 2026-01-15
---

Without this block, Jekyll won’t recognize the file as a page. The three dashes on their own lines are required.

Front matter fields

Essential fields

Every page should have these:

Common fields

Header image fields

Add a full-width header image to any page. The header-tier controls visual weight; header-filter transforms how the image appears.

Navigation and organization fields

Geographic fields

For pages that should appear on an interactive map:

Full example

---
title: Acequia Landscapes
layout: default
date: 2026-01-20
author: Carlos Medina
summary: How community irrigation systems shaped settlement patterns in the Rio Grande Valley.
header-image: /assets/images/acequia.jpg
header-tier: section
header-filter: photo
header-title: Acequia Landscapes
header-position: center right
tags: [landscape, water, community]
geo: [34.52, -105.97]
placename: Manzano
---

Layouts

The layout field determines how the page renders. Xanthan includes several:

Most pages use xanthan. The other layouts are documented in Navigation and ScrollStories.

Writing content with Markdown

Below the front matter, you write content in Markdown—a lightweight syntax that’s far simpler than HTML but produces the same results. A few essentials:

# Heading 1
## Heading 2
### Heading 3

Regular paragraph text. **Bold** and *italic* work as you'd expect.

- Bulleted list item
- Another item

1. Numbered list
2. Second item

[Link text](https://example.com)

> Blockquote for quoted material

Markdown was designed to be readable even as raw text, which means you’re never fighting with tags or angle brackets. If you’re new to it, the Markdown Tutorial takes about ten minutes. The Markdown Cheat Sheet is a useful reference to keep open while writing.

File naming

Page filenames become URLs. A file at projects/river-survey.md becomes yoursite.com/projects/river-survey. Some guidelines:

• Use lowercase and hyphens (not spaces or underscores): my-page.md
• Keep names short but descriptive: acequia-landscapes.md not my-essay-about-acequias-in-new-mexico-final-v2.md
• Use index.md for the default page in a folder: projects/index.md becomes yoursite.com/projects/

Special content: includes

Xanthan extends Markdown with “includes”—reusable components you can drop into any page for images, alerts, audio players, and more. They use a Liquid tag syntax:

{% include images/figure.html
  image-width="40%"
  image-path="/assets/images/photo.jpg"
  caption="A descriptive caption"
%}

See the Component Library for every available include with parameters and examples.

Next steps

• Images — placing and formatting images on your pages
• Typography — text formatting, lists, and block elements
• Navigation — how pages connect through menus, cards, and sidebars