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.
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.
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.
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.
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
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.
| 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. |
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. |
Rules to notice in YAML:
tags: [typora, basic, export]
contacts:
- [email protected]
- [email protected]
header-includes: |
\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhead[CO,CE]{This is fancy}
\fancyfoot[CO,CE]{So is this}
\fancyfoot[LE,RO]{\thepage}
creator:
- role: author
text: John Smith
- role: editor
text: Sarah Jones
host: |
{ip: 1.1.1.1, port:90}