Content Guide for Field Guide for Philanthropy & Civic Action

This guide explains how the Field Guide website uses YAML frontmatter in markdown files to control page rendering through Liquid templates. The architecture separates content (frontmatter + markdown) from presentation (Liquid templates), enabling consistent, maintainable page structures.

Table of Contents

Overview

The Field Guide website uses a content-driven architecture where:

  1. Content lives in Markdown files with YAML frontmatter
  2. Structure is defined by specialized Liquid templates (_layouts/*.html)
  3. Navigation is controlled by _data/nav.yml
  4. Dynamic components are auto-populated from data files in _data/

This separation allows:

Architecture

File Structure

catalytic-funding/
└── planning-preparing/
    ├── program-design.md       # Content (frontmatter + markdown)
    └── fundraising.md

community-building/
├── experiences/
│   └── ideation.md
├── techniques/
└── voices-from-the-field/
    └── adam-kenney.md

_layouts/
├── default.html                # Base HTML structure
├── docs.html                   # Main documentation pages
├── experiences.html            # Community building events
├── techniques.html             # Facilitation techniques
└── voices-from-the-field.html  # Biography pages

_includes/
├── navbar.html, footer.html
├── sidebar.html, toc.html
└── docs/                       # Doc-specific includes
    ├── thinking-questions.html
    ├── templates-downloads.html
    └── related-external-links.html

_data/
├── nav.yml                     # Site navigation
├── templates-downloads/        # Downloadable resources
├── related-external-links/     # External resources
└── checklists/                 # Task lists

Layout Hierarchy

All layouts extend default.html, which provides the base HTML structure:

default.html (base structure)
├── docs.html (documentation pages)
├── experiences.html (event guides)
├── techniques.html (facilitation methods)
├── voices-from-the-field.html (biographies)
├── home.html (homepage)
└── templates-downloads.html (resource pages)

Layouts Reference

1. docs.html

Purpose: Main documentation layout for guides and how-to content

Use for: Catalytic funding guides, community building guides, general documentation

Features:

Required frontmatter:

layout: docs
title: "Page Title"
subtitle: "Brief description"
description: "Full SEO description"
section: catalytic-funding | community-building
group: planning-preparing | cultivating-applicants | making-decisions | managing-funded-projects | sustaining-sunsetting | campaigns | experiences | techniques

Optional frontmatter:

toc: true | false                # Show table of contents (default: false)
redirect_from:                   # Legacy URL redirects
  - /old-url
  - /another-old-url

Template location: _layouts/docs.html

2. experiences.html

Purpose: Community building event guides with specialized formatting

Use for: Event types (ideation, showcase, knowledge-sharing, etc.)

Features:

Required frontmatter:

layout: experiences
icon: 💡                         # Emoji icon for the experience
title: "Experience Name"
subtitle: "Brief description"
description: "SEO description"
section: community-building
group: experiences
experience: "Experience Name"    # Must match key in community-building-experiences.yml

Optional frontmatter:

toc: true | false

Template location: _layouts/experiences.html

Note: The actual content is pulled from _data/community-building-experiences.yml, not from the markdown file body.

3. techniques.html

Purpose: Facilitation technique documentation

Use for: Generate, prioritize, reflect techniques

Features:

Required frontmatter:

layout: techniques
title: "Technique Name"
subtitle: "Brief description"
description: "SEO description"
section: community-building
group: techniques
technique: "Technique Name"     # Must match key in community-building-techniques.yml

Template location: _layouts/techniques.html

Note: Like experiences, content is pulled from data files, not markdown body.

4. voices-from-the-field.html

Purpose: Practitioner biography pages

Use for: Featured contributor profiles and perspectives

Features:

Required frontmatter:

layout: voices-from-the-field
title: "Person Name"
subtitle: "Role/Organization"
section: community-building
group: voices-from-the-field

Optional frontmatter:

voices-learn-more:
  text: "Learn more about..."
  email: "[email protected]"
  twitter: "handle"              # Without @ symbol
  website: "https://url.com"

Template location: _layouts/voices-from-the-field.html

Note: Content is written in the markdown body, not pulled from data files.

5. home.html

Purpose: Homepage layout

Template location: _layouts/home.html

6. templates-downloads.html

Purpose: Template and resource download pages

Template location: _layouts/templates-downloads.html

Frontmatter Fields

Universal Fields

These fields are used across all layouts:

layout: [layout-name]           # Required: Which layout to use
title: "Page Title"             # Required: Main heading
subtitle: "Brief description"   # Optional: Subheading
description: "Full description" # Optional but recommended: SEO meta description
section: catalytic-funding | community-building  # Required: Top-level section
group: [group-name]             # Required: Sub-section grouping

Control where the page appears in site navigation:

section: catalytic-funding | community-building    # Primary section
group: planning-preparing | cultivating-applicants | making-decisions |
       managing-funded-projects | sustaining-sunsetting |
       campaigns | experiences | techniques | voices-from-the-field

The combination of section and group determines:

Display Options

toc: true | false               # Show table of contents (docs, experiences, techniques)
icon: 💡                        # Emoji icon (experiences only)

Redirects

redirect_from:                  # Legacy URL redirects (jekyll-redirect-from plugin)
  - /old-url-1
  - /old-url-2
  - /old-url-3

Experience/Technique Specific

experience: "Experience Name"   # For experiences layout - must match data file key
technique: "Technique Name"     # For techniques layout - must match data file key

Voices from the Field Specific

voices-learn-more:
  text: "Custom learn more text"
  email: "[email protected]"
  twitter: "twitterhandle"      # Without @ symbol
  website: "https://url.com"

Specialized Includes

thinking-questions.html

Purpose: Display styled alert box with reflection questions

Usage:


<div class="alert alert-secondary bd-thinking-questions">
<h3 id="thinking-questions">Thinking Questions</h3>

<ul>
  <li>What are your goals for the program?</li>
  <li>Who is your target audience?</li>
  <li>What resources do you have available?</li>
</ul>
</div>

Renders: Bootstrap alert box with custom styling

Template location: _includes/docs/thinking-questions.html

templates-downloads.html

Purpose: Auto-populate downloadable resources for the current page

Usage:

How it works:

Template location: _includes/docs/templates-downloads.html

Data structure: See DATA.md for details

Purpose: Auto-populate external resource links for the current page

Usage:

How it works:

Template location: _includes/docs/related-external-links.html

checklist.html

Purpose: Render structured task lists from data files

Usage:

<div class="row">
  <div class="col-6">
    <div class="list-group" id="checklist--items" role="tablist"></div>
  </div>
  <div class="col-6">
    <div class="tab-content" id="checklist--tabs"></div>
  </div>
</div>

Template location: _includes/docs/checklist.html

Data structure: See DATA.md for details

example.html

Purpose: Render styled example boxes

Template location: _includes/docs/example.html

sidebar.html

Purpose: Render left sidebar navigation

How it works:

Template location: _includes/sidebar.html

toc.html

Purpose: Render table of contents from page headings

How it works:

Template location: _includes/toc.html

Content Organization

URL Structure

Pages use Jekyll’s pretty permalinks:

Production:  https://fieldguide.sproutfund.org/section/group/page-name/
Development: http://localhost:4000/field-guide/section/group/page-name/

Examples:

Asset References

Always use `` for asset paths:

![Photo](/assets/img/photo.jpg)
<a href="/downloads/template.pdf">Download Template</a>

This ensures assets work in both development (/field-guide) and production (/) environments.

The site navigation is controlled by _data/nav.yml, which defines:

See DATA.md for complete navigation structure documentation.

Examples

Example 1: Documentation Page (docs layout)

File: catalytic-funding/planning-preparing/program-design.md

Frontmatter:

---
layout: docs
title: Program Design
subtitle: Comprehensive planning strategies to coordinate and inform the various funding program components.
description: An overview of areas to consider when designing a new funding program...
section: catalytic-funding
group: planning-preparing
redirect_from: /catalytic-funding/planning-preparing/
toc: true
---

Content features:

Example 2: Voices from the Field (biography)

File: community-building/voices-from-the-field/adam-kenney.md

Frontmatter:

---
layout: voices-from-the-field
title: Adam Kenney
subtitle: Crafting Businesses, Supporting Makers
section: community-building
group: voices-from-the-field
voices-learn-more:
  text: "Learn more about Adam and Monmade"
  email: "[email protected]"
  twitter: "monmadepgh"
  website: "http://monmade.org"
---

Content: Biography written in markdown body

Features:

Example 3: Experience Page

File: community-building/experiences/ideation.md

Frontmatter:

---
layout: experiences
icon: 💡
title: "Ideation"
subtitle: "Develop ideas for new projects and programs."
description:
section: community-building
group: experiences
experience: Ideation
toc: true
---

Note: Content is empty or minimal in the markdown file. Actual content is pulled from _data/community-building-experiences.yml based on the experience: Ideation key.

Creating New Pages

Step-by-Step Guide

  1. Choose the appropriate layout:
    • docs - For guides, how-tos, general documentation
    • experiences - For community building event guides (requires data file entry)
    • techniques - For facilitation methods (requires data file entry)
    • voices-from-the-field - For practitioner biographies
  2. Create markdown file in appropriate directory: 
    catalytic-funding/[group]/page-name.md
community-building/[group]/page-name.md
  3. Add minimal frontmatter: 
    ---
layout: docs
title: "Page Title"
subtitle: "Brief description"
description: "Full SEO description"
section: catalytic-funding
group: planning-preparing
toc: true
---
  4. Write content in Markdown: 
    ## Section Heading

Content goes here...

### Subsection

More content...
  5. Add to navigation (if needed):
    • Edit _data/nav.yml
    • Add page to appropriate section/group
    • Order determines menu position
  6. Build and preview: 
    bundle exec jekyll serve --config "_config.yml,_config_dev.yml" --livereload
  7. View at: http://localhost:4000/field-guide/section/group/page-name/

Tips

Common Patterns

Documentation page with thinking questions:

---
layout: docs
title: "Guide Title"
subtitle: "Brief description"
section: catalytic-funding
group: planning-preparing
toc: true
---

## Overview

Introduction to the topic...


<div class="alert alert-secondary bd-thinking-questions">
<h3 id="thinking-questions">Thinking Questions</h3>

<ul>
  <li>Question 1?</li>
  <li>Question 2?</li>
</ul>
</div>


## Main Content

Rest of the guide...

Biography page:

---
layout: voices-from-the-field
title: "Person Name"
subtitle: "Role/Organization"
section: community-building
group: voices-from-the-field
voices-learn-more:
  text: "Learn more about their work"
  email: "[email protected]"
  twitter: "handle"
  website: "https://url.com"
---

Biography content in markdown format...

Page with legacy redirects:

---
layout: docs
title: "Page Title"
redirect_from:
  - /old-url
  - /another-old-url
  - /catalytic-funding/old-section/page
---

Troubleshooting

Common Issues

Frontmatter not rendering:

Page not appearing in navigation:

Assets not loading:

Table of contents not showing:

Templates/downloads not appearing:

Experience/technique content not showing:

Debugging Tips

  1. Check Jekyll build output: 
    bundle exec jekyll build --config "_config.yml,_config_dev.yml" --verbose
  2. Validate frontmatter: 
    ruby -ryaml -e "puts YAML.load_file('path/to/file.md')"
  3. View generated HTML: 
    open _site/section/group/page-name/index.html
  4. Check navigation data: 
    ruby -ryaml -e "puts YAML.load_file('_data/nav.yml')"

Additional Resources

Summary

The Field Guide’s content system provides:

By understanding frontmatter fields and layout options, you can create rich, well-structured documentation pages without writing HTML.