---
title: "Give a document useful metadata."
description: "Combine YAML and Markdown, compare literal and folded text, and check a small schema."
canonical: https://editmd.app/learn/lessons/yaml-front-matter/
markdown: https://editmd.app/learn/lessons/yaml-front-matter.md
status: pre-release, waiting list open
generated: editmd-website
---

# Give a document useful metadata.

Lesson 08 of 12 in Markdown School. Combine YAML and Markdown, compare literal and folded text, and check a small schema.

## Put metadata before the document

Some tools read a YAML block at the beginning of a Markdown file as _front matter_. Astro is one example. Its delimiters and accepted fields are a tool convention, not a universal Markdown feature. Check the target tool before using them. [Astro Markdown front matter](https://docs.astro.build/en/guides/markdown-content/#frontmatter), [CommonMark specification](https://spec.commonmark.org/0.31.2/).

```markdown
---
title: Garden guide
draft: false
---

# Garden guide

A plan for a shared space.
```

In our exercise, the first block is metadata and the later heading is prose. A renderer that does not support front matter may show the delimiters or interpret them as Markdown. Metadata remains in the raw file even when a preview hides it.

## Preserve lines or fold them

```yaml
summary: |
  First line.
  Second line.
description: >
  A short
  garden guide.
```

The literal form `|` retains the line break between these ordinary lines. The folded form `>` turns that ordinary break into a space. Blank lines and more-indented lines have additional rules. This lesson uses the simple case; inspect the parser output rather than assuming every newline behaves identically. [YAML block scalars](https://yaml.org/spec/1.2.2/#81-block-scalar-styles).

For a postal address, preserving lines may be useful. For a description wrapped across source lines, folding may be useful. Neither choice improves factual accuracy.

## Check syntax, then the receiving tool's rules

Our fictional document contract requires `title` as text and `draft` as a boolean. The two descriptions are strings. The browser checks that contract and shows the parsed metadata separately from the Markdown body.

```yaml
draft: 'false' # Valid YAML; wrong type for this exercise.
```

Remove the quotes to supply a boolean. Notice that the syntax could be valid before and after the change. Similarly, a correct `draft` field does not universally hide a page: only a tool that implements that behavior can do so.

## Practice with a deliberate mistake

Repair the starter, add both block-scalar examples and retain a Markdown heading below the closing delimiter. Inspect the escaped `\n` characters in the parsed result. Then change `draft` back to a string and run the check. You should receive a field/type message rather than a syntax error.

For a real publishing system, check its schema and preview a disposable document before publishing. The exercise performs no publishing, file access or AI request.

Sources checked 17 September 2026. Host behavior can change; verify it against the linked documentation when using these examples.

## Exercise

Make title a nonempty string and draft a boolean. Include a literal summary, a folded description and a Markdown title below the closing delimiter.

## Takeaway

Valid YAML, valid metadata and accurate writing are three different checks.

Related guide: https://editmd.app/docs/writing/. All lessons: https://editmd.app/learn.md