YAML Front Matter

by typora.io

The YAML front matter must be the first thing in the file and must be valid YAML, set between triple-dashed lines. For example, the following markdown file uses YAML front matter to define meta data like title, category, tags, etc.

---
title: YAML Front Matter
category: how-to
author: typora.io
tags: [YAML, metadata, tags]
typora-root-url: ../../
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Using the Variables on Export

Summary

The meta data will be used in export. For example, when exporting markdown file above into HTML format, typora will output <title>YAML Front Matter</title> into HTML <head> Element. And author will be added as meta data when exported to PDF or pub format.

Using Custom Content in Exported HTML

You can add custom contents in Append in <head /> and Append in <body />, which will be inserted into <head /> part and <body /> part in the exported html.

Variables like ${title} or ${author} in <title> and <meta> tag will be replaced by corresponding variables defined in [YAML Front Matter][yaml].

For example, you can insert additional <meta> data or custom <style> into exported html using those options, e.g:

<meta charset="UTF-8">
<meta name="author" content="${author}">
<meta name="description" content="${description}">

To use those variables somewhere else, you can add some javascript in Append in <body />, to read target meta tag, and modify exported content as you want.

Using metadata in Exported PDF

You can add metadata to exported PDF file via [YAML Front Matter][yaml]. The following are the supported PDF metadata:

---
title: Export in Typora
author: John Snow
creator: Typora inc.
subject: Tutorial
keywords: [Pandoc, Tutorial, Export]
---

Note: when “keywords” are absent, typora will also use “tags”, and you can use the YAML indentation to represent an array, for instance:

---
tags:
    - Pandoc
    - Tutorial
    - Export
---

You could also use custom meta tag by adding <meta> tags and custom scripts in Append Extra Content field using same approach as HTML export.

You could also use custom meta tag in header and footer for exported PDF.

Using in Pandoc-based Export

Pandoc also supports certain meta data options, similar to LaTeX export. The following will be added in the exported LaTeX file:

---
header-includes: |
    \usepackage{fancyhdr}
    \pagestyle{fancy}
    \fancyhead[CO,CE]{This is fancy}
    \fancyfoot[CO,CE]{So is this}
    \fancyfoot[LE,RO]{\thepage}
---

You could find more in https://pandoc.org/MANUAL.html#variables

Using as Variables / Settings on 3rd Party Tools

More commonly, YAML front matter will be in 3rd party tools, like static website generators or blog systems based on markdown files. For example, Jekyll uses YAML Front Matter this way.

Use in per-document configuration

Images

key Description
typora-root-url The base path for image resources, see detail.
typora-copy-images-to Actions when user insert or drag & drop images into Typora, see detail.

Export

Since the markdown file may be created by others, for security reasons, native supported formats (PDF / HTML) require “Read and overwrite export settings from YAML front matter” to be enabled in export preferences panel, then settings in YAML front matter can be used and overwrite global export settings.

key description
header
typora-header		 Header part of PDF export, see detail.
footer
typora-footer		 Footer part of PDF export, see detail.
sidebar
typora-sidebar		 true | false
Whether to include sidebar or not in exported HTML. (Not supported in HTML (without style))
append-head
typora-append-head		 Data that will be inserted into <head> tag, after HTML export, see detail.
append-body
typora-append-body		 Data that will be inserted into <body> tag, after HTML export, see detail.
append-head-extra
typora-append-head-extra		 Data that will be inserted into <head> tag, in addition of the global append-head setting, after HTML / PDF export, see detail.
append-body-extra
typora-append-body-extra		 Data that will be inserted into <body> tag, in addition of the global append-body setting, after HTML / PDF export, see detail.
Others For pandoc export formats, some other settings will be parse from yaml meta data, like header-includes:, see pandoc manual for details.

YAML Basics

Rules to notice in YAML:

List

tags: [typora, basic, export]
contacts:
  - hi@typora.io
  - feedback@typora.io

Multiple Lines

header-includes: |
    \usepackage{fancyhdr}
    \pagestyle{fancy}
    \fancyhead[CO,CE]{This is fancy}
    \fancyfoot[CO,CE]{So is this}
    \fancyfoot[LE,RO]{\thepage}

Object

creator:
- role: author
  text: John Smith
- role: editor
  text: Sarah Jones
host: |
  {ip: 1.1.1.1, port:90}