From ca212da7c394ed0649b073650da2f5f08703ffec Mon Sep 17 00:00:00 2001
From: Matias Capeletto <matias.capeletto@gmail.com>
Date: Wed, 25 Nov 2020 00:16:02 +0100
Subject: [PATCH] docs: port formatter guide from vuepress

---
 docs/.vitepress/config.js |  1 +
 docs/guide/frontmatter.md | 90 +++++++++++++++++++++++++++++++++++++++
 docs/guide/markdown.md    |  2 +
 3 files changed, 93 insertions(+)
 create mode 100644 docs/guide/frontmatter.md

diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
index d8df91f0..e0ab0c17 100644
--- a/docs/.vitepress/config.js
+++ b/docs/.vitepress/config.js
@@ -38,6 +38,7 @@ function getGuideSidebar() {
         { text: 'Configuration', link: '/guide/configuration' },
         { text: 'Markdown Extensions', link: '/guide/markdown' },
         { text: 'Customization', link: '/guide/customization' },
+        { text: 'Frontmatter', link: '/guide/frontmatter' },
         { text: 'Deploying', link: '/guide/deploy' }
       ]
     }
diff --git a/docs/guide/frontmatter.md b/docs/guide/frontmatter.md
new file mode 100644
index 00000000..ce360b74
--- /dev/null
+++ b/docs/guide/frontmatter.md
@@ -0,0 +1,90 @@
+# Frontmatter
+
+Any Markdown file that contains a YAML frontmatter block will be processed by [gray-matter](https://github.com/jonschlinkert/gray-matter). The frontmatter must be at the top of the Markdown file, and must take the form of valid YAML set between triple-dashed lines. Example:
+
+```markdown
+---
+title: Docs with VitePress
+editLink: true
+---
+```
+
+Between the triple-dashed lines, you can set [predefined variables](#predefined-variables), or even create custom ones of your own. These variables can be used via the <code>\$page.frontmatter</code> variable.
+
+Here’s an example of how you could use it in your Markdown file:
+
+```markdown
+---
+title: Docs with VitePress
+editLink: true
+---
+
+# {{ $page.frontmatter.title }}
+
+Guide content
+```
+
+## Alternative frontmatter Formats
+
+VuePress also supports JSON frontmatter syntax, starting and ending in curly braces:
+
+```
+---
+{
+  "title": "Blogging Like a Hacker",
+  "editLink": "true"
+}
+---
+```
+
+## Predefined Variables
+
+### title
+
+- Type: `string`
+- Default: `h1_title || siteData.title`
+
+Title of the current page.
+
+### head
+
+- Type: `array`
+- Default: `undefined`
+
+Specify extra head tags to be injected:
+
+```yaml
+---
+head:
+  - - meta
+    - name: description
+      content: hello
+  - - meta
+    - name: keywords
+      content: super duper SEO
+---
+
+```
+
+## Predefined Variables Powered By Default Theme
+
+### navbar
+
+- Type: `boolean`
+- Default: `undefined`
+
+You can disable the navbar on a specific page with `navbar: false`
+
+### sidebar
+
+- Type: `boolean|'auto'`
+- Default: `undefined`
+
+You can decide to show the sidebar on a specific page with `sidebar: auto` or disable it with `sidebar: false`
+
+### editLink
+
+- Type: `boolean`
+- Default: `siteData.editLinks`
+
+Define if this page should include an edit link.
diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md
index 53f48bfe..8245dbb6 100644
--- a/docs/guide/markdown.md
+++ b/docs/guide/markdown.md
@@ -60,6 +60,8 @@ lang: en-US
 
 This data will be available to the rest of the page, along with all custom and theming components.
 
+For more details, see [Frontmatter](./frontmatter.md).
+
 ## GitHub-Style Tables
 
 **Input**