docs: add formatter guide (#151)

Co-authored-by: Kia King Ishii <[email protected]>

docs/.vitepress/config.js

@@ -37,6 +37,7 @@ function getGuideSidebar() {
         { text: 'Getting Started', link: '/guide/getting-started' },
         { text: 'Configuration', link: '/guide/configuration' },
         { text: 'Markdown Extensions', link: '/guide/markdown' },
+        { text: 'Frontmatter', link: '/guide/frontmatter' },
         { text: 'Customization', link: '/guide/customization' },
         { text: 'Deploying', link: '/guide/deploy' }
       ]

docs/guide/frontmatter.md

@@ -0,0 +1,87 @@
+# 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:
+
+```md
+---
+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:
+
+```md
+---
+title: Docs with VitePress
+editLink: true
+---
+
+# {{ $page.frontmatter.title }}
+
+Guide content
+```
+
+## Alternative frontmatter Formats
+
+VitePress also supports JSON frontmatter syntax, starting and ending in curly braces:
+
+```json
+---
+{
+  "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
+---
+```
+
+### 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: `undefined`
+
+Define if this page should include an edit link.

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**