
# GIT Integration

If you are using git to manage your content, Front Matter can be used to sync your changes from and to your git repository.

![Sync your changes with GIT](/releases/v8.1.0/git-integration.png)

## Enable GIT integration

To enable this feature, you will need to set the `frontMatter.git.enabled` setting to `true`. 

## Change the commit message

The commit message can be customized via the `frontMatter.git.commitMessage` setting (default is `Synced by Front Matter`).

Git integration


# Introduction

## Overview

Front Matter is an integral Visual Studio Code extension that simplifies operating and managing your markdown articles. We created the extension to support several static-site generators and frameworks parallel to Hugo, Jekyll, Hexo, NextJs, Gatsby, and more which provides you the power and control of a full-blown Content Management System (CMS)

The extension brings CMS capabilities straight to Visual Studio Code. For example, you can keep a list of the used tags, categories, create content, and so much more.

![Welcome screen to configure your website](/releases/v7.2.0/welcome-screen-7.2.0.png)

Our main extension features are:

- Page dashboard in which you can get an overview of all of your markdown pages. You can use it to search, filter, type your contents.
- Site preview within Visual Studio Code
- SEO checks for title, description, and keywords
- Support for custom actions/scripts
- and many more

![Site preview](https://res.cloudinary.com/estruyf/image/upload/w_1256/v1631871148/frontmatter/preview-3.2.0.png)

## Why Front Matter?

Initially, the Front Matter extension was created when [Elio Struyf](https://twitter.com/eliostruyf) migrated from WordPress to Hugo (Static web site Generator). To make content management more straightforward, he began to develop the Front Matter extension and developed more options regularly, until eventually, it became a headless CMS that runs on Visual Studio Code.

## Advantages

We believe that Front Matter gives you the subsequent advantages:

### Speed

It simply runs on your machine. There are no servers/websites/APIs involved in the process. Nothing can beat this.

### Use it within Visual Studio Code

Don't jump from tool to tool. Use the tool that you like the most: of course, that's Visual Studio Code.

### Customizable

Almost all of the Front Matter features are customizable in its settings. These settings ensure that you can tweak Front Matter to your needs.

### Extensibility

We recognize that each website is different. That is why you can upload your custom scripts. These scripts will display as actions in the Front Matter panel and take your content material control to the next level. 

> **Example**: [Generate open graph preview image in Code with Front Matter](https://www.eliostruyf.com/generate-open-graph-preview-image-code-front-matter/)


Create, edit, and preview your pages within Visual Studio Code/GitPod/... Front Matter allows you to keep control of your static site without any external tools.

Introduction


# Getting started

## Overview

To get you started, you first need to install the extension in Visual Studio Code. 

## Installation

You can get the extension via:

- The VS Code marketplace: [VS Code Marketplace - Front Matter](https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-front-matter).
- The extension CLI: `ext install eliostruyf.vscode-front-matter`
- Or by clicking on the following link: <a href="" title="open extension in VS Code" data-vscode="vscode:extension/eliostruyf.vscode-front-matter">open extension in VS Code</a>

### Beta version

If you have the courage to test out the beta features, we made available a beta version as well. You can install this via:

- The VS Code marketplace: [VS Code Marketplace - Front Matter BETA](https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-front-matter-beta).
- The extension CLI: `ext install eliostruyf.vscode-front-matter-beta`
- Or by clicking on the following link: <a href="" title="open extension in VS Code" data-vscode="vscode:extension/eliostruyf.vscode-front-matter-beta">open extension in VS Code</a>

> **Info**: The BETA docs can be found on [beta.frontmatter.codes](https://beta.frontmatter.codes).

> **Important**: As there can only be one version running of the extension, you will need to uninstall the main version before installing the beta version.

## Welcome screen

Once installed, Front Matter will open the **welcome screen** the first time Visual Studio Code gets reloaded.

![Welcome screen to configure your website](/releases/v7.2.0/welcome-screen-7.2.0.png)

> **Important**: Front Matter supports light and dark mode. It will be automatically detected based on the theme you are using.

> **Info**: The welcome screen will also be shown when Front Matter is not yet fully configured.

## Required configuration

On the welcome screen, there are two tasks to complete before you can take full advantage of Front Matter. 

### Step 1: Initialize the project

In this step, a `.frontmatter/templates` folder and `article.md` file template will be created in the current project.

The `.frontmatter/templates` folder, is a folder that can be used to place all sort of Markdown templates. It will be used when you want to let Front Matter generate new pages/articles/...

### Step 2: Configure the site-generator or framework you use

In this step, you will need to configure the site-generator or framework you use. If your static-site-generator is known by Front Matter, it will automatically set some configuration options. If not, you will need to configure these settings manually. You can continue by selecting `other` from the dropdown.

### Step 3: Register content folder(s)

As Front Matter is created to support many (or all) static site generator, you will need to specify where your Markdown/content lives. From the moment you register a folder, it will be used on the dashboard to show an overview of all files.

Registering a folder can be done from the list of folders Front Matter has found that already contains supported files.

![Content folders](/releases/v7.2.0/content-list.png)

If one of your folders is not shown, you can register it by right-clicking on a folder name in the explorer panel from Visual Studio Code and selecting **Front Matter: Register folder**.

![Register a folder](/assets/register-folder.png)

> **Info**: Be default, the extension will include content from the current folder and its sub-folders. If you wish to exclude the sub-folders, you can do this by updating the [frontMatter.content.pageFolders](/docs/settings#frontmatter.content.pagefolders) configuration setting and specifying the `excludeSubDir` property with the value as `true`.

## Workspaces with multiple folders

If you are using workspaces with multiple folders in Visual Studio Code. Front Matter will try to figure out for which folder it needs to be activated. It does this by searching for the `frontmatter.json` file in the workspace folders.

When Front Matter cannot find a `frontmatter.json` file in any of your folders (means that it is not initiated yet), it will ask you to pick the folder.

![Select your workspace folder for Front Matter](/releases/v5.0.0/workspace-folder.png)

Once you selected the folder, it will create the `frontmatter.json` file and reload the workspace.

## Backers & supporters

If you are one of the Front Matter supporters/backers, you can hide the support links from the UI. We know it is not much, but we want to give something small back, and what is better than a bit of space? 🤓

By default, you'll see the following support links:

![Support links shown by default](/releases/v6.0.0/support-links.png)

When you log in via GitHub, you'll see the following:

![Hidden support links](/releases/v6.0.0/support-links-hidden.png)

Simply start by clicking on the **Accounts** button, and select **Sign in with GitHub to use Front Matter** or launch the same flow by using the `Front Matter: Authenticate` command.

![Sign in with GitHub for Front Matter](/releases/v6.0.0/signin-github.png)

Follow the proposed steps from Visual Studio Code.

## Enjoy using Front Matter

<iframe src="https://player.vimeo.com/video/630150787?h=9988cff4f0&amp;title=0&amp;byline=0&amp;portrait=0&amp;speed=0&amp;badge=0&amp;autopause=0&amp;player_id=0&amp;app_id=56727" width="100%" height="450" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen title="Front Matter - Installation"></iframe>


Getting started


# Content creation

## Overview

As each website is different, Front Matter allows you to create content by using content types or templates. 

When using content types or templates, Front Matter adapts the metadata fields shown in the editor panel to the corresponding fields in your content type or template.

Front Matter comes with a default content type and template definition which you can adapt to your needs or add your types next to it.

## Before you start

Front Matter supports both `md` and `mdx` files. If you use the templating functionality, the CMS will automatically use the file extension of the template.

When using content types, the CMS will create the new content based on the following rules:

1. The extension checks if the content type has the `fileType` property defined. If set, the CMS uses the file type set in the property.
2. If the content type has no `fileType` property defined, the CMS uses the default file type defined in the `frontMatter.content.defaultFileType` setting. By default, the CMS uses `md`. If you want to use `mdx`, you need to set the `frontMatter.content.defaultFileType` setting to `mdx`.

## How it works

Behind the scenes, Front Matter uses the `frontMatter.taxonomy.contentTypes` setting to understand which type of content you'll use for your website.

Our default content type consists of the following fields:

- title: `string`
- description: `string`
- date: `datetime`
- preview: `image`
- draft: `draft`
- tags: `tags`
- categories: `categories`

> **Info**: The default content type will create an individual Markdown file when creating content. If you want to use page bundles, make sure to specify this on the content type level.

We'll use the default one when you start writing your markdown content, and no other content type is defined.

![Default content type fields](/assets/default-contenttype.png)

Content creation


# Content types

## Changing the default content type

If you want to change the default content type, open your `frontmatter.json` and write an entry for the `frontMatter.taxonomy.contentTypes` setting. Visual Studio Code will automatically autocomplete it with the default content type fields.

If in some case it wouldn't do this, here is the default content type structure:

```json
"frontMatter.taxonomy.contentTypes": [
  {
    "name": "default",
    "previewPath": null,
    "pageBundle": false,
    "fields": [
      {
        "title": "Title",
        "name": "title",
        "type": "string"
      },
      {
        "title": "Description",
        "name": "description",
        "type": "string"
      },
      {
        "title": "Publishing date",
        "name": "date",
        "type": "datetime",
        "default": "{{now}}",
        "isPublishDate": true
      },
      {
        "title": "Article preview",
        "name": "preview",
        "type": "image"
      },
      {
        "title": "Is in draft",
        "name": "draft",
        "type": "draft"
      },
      {
        "title": "Tags",
        "name": "tags",
        "type": "tags"
      },
      {
        "title": "Categories",
        "name": "categories",
        "type": "categories"
      }
    ]
  }
]
```

Adapt the fields to your needs. For our documentation it looks as follows:

```json
"frontMatter.taxonomy.contentTypes": [
  {
    "name": "default",
    "previewPath": null,
    "pageBundle": false,
    "fields": [
      {
        "title": "Title",
        "name": "title",
        "type": "string"
      },
      {
        "title": "Description",
        "name": "description",
        "type": "string"
      },
      {
        "title": "Publishing date",
        "name": "date",
        "type": "datetime",
        "default": "{{now}}",
        "isPublishDate": true
      },
      {
        "title": "Last modified date",
        "name": "lastmod",
        "type": "datetime",
        "isModifiedDate": true
      },
      {
        "title": "Navigation weight",
        "name": "weight",
        "type": "number"
      }
    ]
  }
]
```

The metadata section on the editor panel will render the following fields:

![Adapted default content type fields](/assets/adapted-default-ct.png)

### Content type properties

For the content type you can configure the following properties:

| Property | Type | Description | Default value |
| --- | --- | --- | --- |
| `name` | `string` | Name of the content type | `""`  |
| `fields` | `array` | Check the [supported field types](/docs/content-creation/fields#supported-field-types) | `[]` |
| `fileType` | Enum: `md, mdx, markdown, <your choice>` | File type of for the content type you define. The type will be used to create the file when creating content. | `md` |
| `pageBundle` | `boolean` | If set to `true`, the content will be created as a page bundle (folder). | `false` |
| `previewPath` | `string` | Defines a custom preview path for the content type. When the preview path is not set, the value from the [frontMatter.preview.pathName](https://frontmatter.codes/docs/settings#frontmatter.preview.pathname) setting will be used. | `null` |
| `template` | `string` | Specify a path to a template file that will be used when creating new content with the content type. | `null` |
| `postScript` | `string` | An optional post script that can be used after new content creation. In order to use this, you will have to set the value to the ID of your [content script](/docs/custom-actions/#content-script). | `null` |

## Define your own type

In most cases, you'll work with multiple types of content where each type will have its defined set of fields. If this is the case for your website, you'll need to add another content type to the `frontMatter.taxonomy.contentTypes` setting.

Instead of overriding the default content type, you can also define a new content type. It requires you to specify the `name` and `fields`.

> **Important**: The `name` property value needs to be equal to the `type` value you set in your Markdown front matter. You best define it via a template so that it's always defined. A default template will be available when initializing Front Matter in your project in the `.frontmatter/templates` folder.

Sample:

```json
"frontMatter.taxonomy.contentTypes": [
  {
    "name": "default",
    "fields": [
      ...
    ]
  },
  {
    "name": "documentation",
    "fields": [
      ...
    ]
  }
]
```

In the sample, `documentation` is used as the content type name. This means that in your article, you'll need to add the `type: documentation` to your front matter to let the editor panel understand which fields to show.

```markdown
---
title: Content Types
slug: content-types
description: null
date: '2021-09-17T07:36:26.654Z'
lastmod: '2019-08-22T15:20:28.000Z'
weight: 4
type: documentation
---
```

> **Fields**: Check out the [fields](/docs/content-creation/fields) section to learn which fields are supported.


## Using a template with the content type

When creating content that requires a pre-defined structure, you can use the `template` property. The `template` property allows you to link a template file. On content creation, the contents of the template file will be used to create the new content.

You can use the `template` property on any of your content types, even on the default content type from Front Matter.

```json
{
  "frontMatter.taxonomy.contentTypes": [
    {
      "name": "default",
      "pageBundle": false,
      "template": "[[workspace]]/.frontmatter/templates/article.md",
      "fields": [...]
    }
}
```

## Run a script after your content is created

To run a custom script after your content is created, you can use the `postScript` property. The `postScript` property allows you to link a script file by referencing its `id`. The script will be executed after the content is created which gives you access to the whole front matter object.

```json
{
  "frontMatter.taxonomy.contentTypes": [
    {
      "name": "default",
      "pageBundle": false,
      "template": "[[workspace]]/.frontmatter/templates/article.md",
      "fields": [...],
      "postScript": "generate-social-image"
    }
  ]
}
```

In your custom script setting, you need to make sure that this script is available:

```json
{
  "frontMatter.custom.scripts": [
    {
      "id": "generate-social-image",
      "title": "Generate social image",
      "script": "./scripts/social-img.js",
    }
  ]
}
```

> **Info**: More information about custom scripts can be found in the [custom actions](/docs/custom-actions) section.

Content types


# Fields overview

## Supported field types

Front Matter supports the following fields to be used in the content-types:

- [string](#string)
- [number](#number)
- [datetime](#datetime)
- [boolean](#boolean)
- [image](#image)
- [file](#file)
- [choice](#choice)
- [list](#list)
- [draft](#draft)
- [tags](#tags)
- [categories](#categories)
- [taxonomy](#taxonomy)
- [fields](#fields)
- [block](#block)
- [dataFile](#data-file)
- [slug](#slug)

There are also the following section fields:

- [divider](#divider)
- [heading](#heading)

### Standard field properties

All fields share the following field properties:

| Property | Type | Description | Optional / Required |
| ----- | ----- | ----- | ----- |
| `name` | `string` | The name of your field, will be used to set in the front matter of your Markdown file. | **Required** |
| `type` | `string` | The type of the field. Use one of the supported field types. | **Required** |
| `title` | `string` | The title to show in the metadata section | *Optional* |
| `description` | `string` | The description to show underneath the field | *Optional* |
| `default` | `string` | Defines the default value for the field when creating the content type. You can also use placeholders like `{{title}}`, `{{slug}}` or `{{now}}`. Check for more information under [placeholders](/docs/content-creation/placeholders). | *Optional* |
| `required` | `boolean` | Defines if the field is required or not. If set to true, and the user does not define a value, a notification will appear. You can disable this notification with the [frontMatter.global.disabledNotifications](/docs/settings#frontmatter.global.disablednotifications) setting. | *Optional* |
| `hidden` | `boolean` | Specifies if you want to hide the field from the metadata section, but still have it available in Front Matter. | *Optional* |


## String

The `string` field type is used to store a single-line or multiline of text. For instance, you can use if for the title, description, or any other text field.

### Properties

- `single (boolean)`: When you picked the `string` field type, you can specify if it is a single line. By default it will render as a multiline field (optional).
- `wysiwyg (boolean)`: When you set this value to `true`, the field will be rendered as a WYSIWYG editor. The output of the WYSIWYG editor will be HTML.

![WYSIWYG controls](/releases/v7.2.0/wysiwyg-controls.png)

### Usage

```json
{
  "title": "Title",
  "name": "title",
  "type": "string",
  "single": true
}
```

### Outcome

```markdown
---
title: "My title"
---
```



## Number

The `number` field allows you to insert integer values, like for instance setting the weight of your content.

### Usage

```json
{
  "title": "Weight",
  "name": "weight",
  "type": "number"
}
```

### Outcome

```markdown
---
weight: 1
---
```



## Datetime

The `datetime` field allows you to add date fields. You can use it for publish, modified, and any other types of dates for you content.

### Properties

- `isPublishDate`: Specifies if the field is a publish date. When set to `true`, the field will be used to set the publish date for the content (this will be reflected on the content dashboard). 
- `isModifiedDate`: Specifies if the field is a modified date. When using the `frontMatter.content.autoUpdateDate` setting to automatically update the modified date of the article, this field will be used.

> The format of your date can be defined in the `frontMatter.taxonomy.dateFormat` setting. Check [date-fns formating](https://date-fns.org/v2.0.1/docs/format) for more information.

### Usage

```json
{
  "title": "Publishing date",
  "name": "date",
  "type": "datetime",
  "isPublishDate": true
},
{
  "title": "Last modified date",
  "name": "lastmod",
  "type": "datetime",
  "isModifiedDate": true
}
```

### Outcome

```markdown
---
date: 2022-03-14T08:42:21.626Z
lastmod: 2022-03-14T08:42:22.364Z
---
```


## Boolean

The `boolean` field can be used to set a value of `true` or `false` into your markdown. It will be rendered as a toggle.

### Usage

```json
{
  "title": "Published",
  "name": "isPublished",
  "type": "boolean"
}
```

### Outcome

```markdown
---
isPublished: true
---
```



## Choice

The `choice` field allows you to define a set of options.

### Properties

- `choices (string[] | { id: string; title: string; })`: When you picked the `choice` field type, you need to return an array of choices.
- `multiple (boolean)`: Define if you want to allow multiple choice selection. By default this is `false`.

### Usage

Example of using an array of string values:

```json
{
  "title": "Choice",
  "name": "choice",
  "type": "choice",
  "choices": [
    "",
    "Choice 1",
    "Choice 2",
    "Choice 3"
  ]
}
```

Example of using an array of { id: string; title: string; } objects:

```json
{
  "title": "Choice",
  "name": "choice",
  "type": "choice",
  "choices": [
    { "id": "1", "title": "Choice 1" },
    { "id": "2", "title": "Choice 2" },
    { "id": "3", "title": "Choice 3" }
  ]
}
```

### Outcome

Outcome when using string values:

```markdown
---
choice: "Choice 1"
---
```

Outcome when using id/title objects:

```markdown
---
choice: "1"
---
```



## List

The `list` field allows you to add multiple text values.

### Usage

Example of using the list field:

```json
{
  "title": "Alias",
  "name": "alias",
  "type": "list"
}
```

### Outcome

The previous example will give you the following outcome:

```markdown
---
alias:
  - release-notes-v8
  - changelog-v8
---
```



## Draft

The `draft` field defines the state of your content. This is used for the content dashboard as well. By default, the draft field is a boolean. If you want to use your own status values, you can configure it via the [frontmatter.content.draftfield](/docs/settings#frontmatter.content.draftfield) setting.

When using a custom draft status, the content dashboard will make use of it as well:

![Draft filters](/releases/v5.3.0/draft-status.png)

> **Important**: If you use Jekyll, you do not have to use the draft field, as Front Matter supports the `_drafts`, `_posts` folders and collections from Jekyll. If you use Jekyll, make sure to set the `frontMatter.framework.id` setting to `jekyll`.

### Example 1

#### Usage

```json
{
  "title": "Draft",
  "name": "draft",
  "type": "draft"
}
```

#### Outcome

Default draft field outcome:

```markdown
---
draft: true
---
```

### Example 2

#### Usage

In case you want to use a published field, instead of a draft field. You can invert the logic by setting the `invert` property to `true`:

```json
"frontMatter.content.draftField": {
  "name": "published",
  "type": "boolean",
  "invert": true
}
```

The field is configured as follows:

```json
{
  "title": "Published",
  "name": "published",
  "type": "draft"
}
```

#### Outcome

Default draft field outcome:

```markdown
---
published: false
---
```

### Example 3

#### Usage

If you want to use your own status values, you can define it by specifying these in the `frontMatter.content.draftField` setting:

```json
"frontMatter.content.draftField": {
  "name": "draft",
  "type": "choice",
  "choices": ["draft", "in progress", "published"]
}
```

The field is configured as follows:

```json
{
  "title": "Draft",
  "name": "draft",
  "type": "draft"
}
```

#### Outcome

When using your own status values:

```markdown
---
draft: "in progress"
---
```



## Image

The `image` field can be used to reference single or multiple images to your content.

### Properties

- `isPreviewImage (boolean)`: Allows you to specify a custom preview image for your article. When you set this to `true` for an image field in your content type, it will be adopted in the dashboard.
- `multiple (boolean)`: Define if you want to allow to select multiple images. By default this is `false`.

> **Important**: You can only set this on one image field per content type.

### Usage

```json
{
  "title": "Article preview",
  "name": "preview",
  "type": "image",
  "isPreviewImage": true
}
```

### Outcome

```markdown
---
preview: /social/400285cf-4928-4c07-8ca5-158f249a3bc1.png
---
```




## File

The `file` field can be used to reference single or multiple files to your content.

### Properties

- `multiple (boolean)`: Define if you want to allow to select multiple files. By default this is `false`.
- `fileExtensions (string array)`: Define the file extensions that are allowed to be selected. By default this is an empty array `[]`.

### Usage

```json
{
  "title": "Attachments",
  "name": "attachments",
  "type": "file",
  "multiple": true,
  "fileExtensions": ["pdf", "mp4", "wav"]
}
```

### Outcome

```markdown
---
attachments:
- /uploads/file1.pdf
- /uploads/file2.mp4
---
```




## Tags

The `tags` field allows you to create or use tags from your `frontMatter.taxonomy.tags` setting (by default, none existing). When adding a tag which does not yet exist, you will have the option to create it. 

![Add a new tag](/assets/tag-creation.png)

When the tag is created, you will be able to re-use it for other content.

> **Info**: You can add multiple tags at once by entering them as **comma-separated** values and pressing the **ENTER** key.

### Properties

- `taxonomyLimit`: Defines the maximum number of items that can be selected. By default set to `0` which allows unlimited items to be selected.

> **Info**: When a limit is defined, this will get reflected in the UI as well:

![Taxonomy limit](/assets/tags-limit.png)


### Usage

```json
{
  "title": "Tags",
  "name": "tags",
  "type": "tags"
}
```

### Outcome

```markdown
---
tags:
  - Development
  - GitHub
  - GraphQL
  - API
---
```



## Categories

The `categories` field is similar to the [tags](/docs/content-creation/fields#tags) field. The difference is that it uses the `frontMatter.taxonomy.categories` setting (by default, none existing).

### Properties

- `taxonomyLimit`: Defines the maximum number of items that can be selected. By default set to `0` which allows unlimited items to be selected.

### Usage

```json
{
  "title": "Categories",
  "name": "categories",
  "type": "categories"
}
```

### Outcome

```markdown
---
categories:
  - Development
---
```



## Taxonomy

The `taxonomy` is similar to the tags and categories field, but allows you to define your own taxonomy values and structure.

### Properties

- `taxonomyLimit`: Defines the maximum number of items that can be selected. By default set to `0` which allows unlimited items to be selected.
- `taxonomyId`: Set the id of your custom taxonomy definition defined in the `frontMatter.taxonomy.customTaxonomy` setting.

### Custom taxonomy

The `frontMatter.taxonomy.customTaxonomy` setting allows you to provide a list of custom taxonomy data. Each of the taxonomy data contains a `id` and an array of `options`.

Here is an example of the custom taxonomy setting definition:

```json
"frontMatter.taxonomy.customTaxonomy": [
  {
    "id": "customTaxonomy",
    "options": [
      "Option 1",
      "Option 2",
      "Option 3"
    ]
  }
]
```

### Usage

```json
{
  "title": "Custom taxonomy",
  "name": "customTags",
  "type": "taxonomy",
  "taxonomyId": "customTaxonomy"
}
```

### Outcome

```markdown
---
customTags:
  - custom-development
---
```



## Fields

The `fields` field, allows you to create multi-dimensional content type fields (sub-fields). This is useful when you want to create a complex content type. In case you want to define a list data, you will have to use the [block](/docs/content-creation/fields#block) field.

When you specify the field type as `fields`, you need to define sub-fields within the `fields` property.

### Properties

- `fields`: Define the sub-fields of your content type. All the above types are supported.

### Usage

```json
{
  "frontMatter.taxonomy.contentTypes": [
    {
      "name": "multi-dimensional",
      "pageBundle": false,
      "fields": [
        ...
        {
          "title": "Photo",
          "type": "fields",
          "name": "photo",
          "fields": [
            {
              "title": "Title",
              "name": "title",
              "type": "string"
            },
            {
              "title": "URL",
              "name": "url",
              "type": "image"
            }
          ]
        }
      ]
    }
  ]
}
```

### Outcome

![Multi-dimensional content type fields](/releases/v6.0.0/multi-dimensional-content-type-fields.png)

```markdown
---
photo:
  title: "Photo 1"
  url: /social/400285cf-4928-4c07-8ca5-158f249a3bc1.png
---
```


## Block

The `block` field type allows you to define a group of fields which can be used to create a list of data.

![Block field type rendering](/assets/block-field-type.png)

### Prerequisites

To work with the `block` field type, you need to define a field group (a set of fields for your data) in the `frontMatter.taxonomy.fieldGroups` setting.

```json
"frontMatter.taxonomy.fieldGroups": [
  {
    "id": "author",
    "labelField": "name",
    "fields": [
      {
        "title": "Author Name",
        "name": "name",
        "type": "string",
        "single": true
      },
      {
        "title": "Social link",
        "name": "social",
        "type": "string",
        "single": true
      }
    ]
  }
]
```

> **Info**: You can use the same field types as you would use in the regular content types.

### Properties

- `fieldGroup`: Define the field group(s) that will be used to create a list of data.

### Usage

```json
"frontMatter.taxonomy.contentTypes": [
  {
    "name": "page",
    "fields": [
      {
        "title": "Authors",
        "name": "authors",
        "type": "block",
        "fieldGroup": [
          "author"
        ]
      },
      ...
  }
]
```

> **Important**: If you want, you can also create field groupings within the field grouping. This is useful when you want to create sub-groups of data.

### Outcome

```markdown
---
authors:
  - name: Elio Struyf
    social: https://twitter.com/eliostruyf
    fieldGroup: author
---
```



## Data file

The `dataFile` field type allows you to use a data file to populate the field with a list of options. For instance, if you have a data file with all the authors of your site, you can use the `dataFile` field type to populate the `authors` field with the data from the authors data file.

![dataFile field](/releases/v7.3.0/datafile-field.png)

### Prerequisites

To use the `dataFile` field type, you need to have a definition for a data file in place. Here is an example of the authors sample:

```json
{
  "frontMatter.data.files": [{
    "id": "authors",
    "title": "Authors",
    "file": "[[workspace]]/data/authors.json", // Adapt to your needs
    "schema": {
      "title": "Author",
      "type": "object",
      "required": [
        "name",
        "url"
      ],
      "properties": {
        "slug": {
          "title": "slug",
          "type": "string"
        },
        "name": {
          "title": "name",
          "type": "string"
        },
        "url": {
          "title": "url",
          "type": "string"
        }
      }
    }
  }]
}
```

### Properties

- `dataFileId`: Specify the ID of the data file to use for this field (required).
- `dataFileKey`: Specify the key of the data file to use for this field (required).
- `dataFileValue`: Specify the property name that will be used to show the value for the field (optional).
- `multiple`: Specify if you want to select one or multiple records (optional).

### Usage

```json
"frontMatter.taxonomy.contentTypes": [
  {
    "name": "page",
    "fields": [
      {
        "title": "Author",
        "name": "author",
        "type": "dataFile",
        "dataFileId": "authors",
        "dataFileKey": "slug",
        "dataFileValue": "name",
        "multiple": true
      },
      ...
  }
]
```

### Outcome

```markdown
---
author:
  - dorothy-parker
---
```



## Slug

The `slug` field allows you to create/update the slug of the current page.

![Slug field](/releases/v8.0.0/slug-field.png)

### Properties

- `editable`: Specify if you allow manual changes, or if the slug is generated automatically (optional - default: `true`).


### Usage

The field is configured as follows:

```json
{
  "title": "Slug",
  "name": "slug",
  "type": "slug",
  "editable": true,
  "default": "{{slug}}"
}
```

### Outcome

The above configuration gives you the following outcome:

```markdown
---
slug: version-8-0-0-release-notes
---
```

> **Info**: The slug is generated based on the title of the page. More information about it can be found in the [generate slug](/docs/commands#generate-slug-based-on-content-title) command section.



## Divider

The `divider` field type allows you to add a divider to your content type. This is useful when you want to group fields together.

### Properties

You only need to specify the `type` property and name:

### Usage

```json
{
  "name": "divider",
  "type": "divider"
}
```

### Outcome

![Section divider field](/releases/v8.1.0/section-divider.png)



## Heading

The `heading` field type allows you to add a heading to your content type. This is useful when you want to group fields together.

### Usage

```json
{
  "title": "Section title",
  "name": "sectionTitleWithDescription",
  "description": "This is just a dummy description to test out the field description",
  "type": "heading"
},
{
  "title": "Section title without description",
  "name": "sectionTitleWithoutDescription",
  "type": "heading"
}
```

### Outcome

![Section heading field](/releases/v8.1.0/section-heading.png)

Fields


# Placeholders

Placeholders can be used in content type fields or templates. The placeholders allow you to automatically fill in values when creating a new content.

There are known placeholders from Front Matter:

- `{{title}}`: Title of the page
- `{{slug}}`: Slug of the page
- `{{now}}`: Current date formatted with the value defined in `frontMatter.taxonomy.dateFormat` or ISO string
- `{{year}}`: Current year
- `{{month}}`: Current month
- `{{day}}`: Current day

## Custom placeholders

You can define you own placeholders within the `frontMatter.content.placeholders` setting. There are two types of placeholders you can create:

- `static`: A static placeholder that will be replaced with a static value (you can use another placeholder in the value)
- `dynamic`: A dynamic placeholder that will use a script to generate the value

### Static placeholders

Here is an example of a static `permalink` placeholder:

```json
"frontMatter.content.placeholders": [
  {
    "id": "permalink",
    "value": "/blog/{{slug}}.html"
  }
]
```

> **Info**: The static placeholder's value is adding some text and it will also include the slug of the page. There is no extra logic that is executed to generate the value.

To use the `permalink` placeholder, you need to define the `{{permalink}}` value in your content type or template.

```json
{
  "title": "Permalink",
  "name": "permalink",
  "type": "string",
  "default": "{{permalink}}"
}
```

### Dynamic placeholders

Dynamic placeholders allow you to use custom scripts to generate the value. The difference with the static placeholder is that instead of specifying a value, you need to specify a `script` and `command` property.

#### Placeholder definition

Here is an example of a dynamic `uniqueId` placeholder:

```json
"frontMatter.content.placeholders": [
  {
    "id": "uniqueId",
    "script": "./scripts/uniqueId.js",
    "command": "~/.nvm/versions/node/v16.13.1/bin/node"
  }
]
```

#### Placeholder script

The base script looks like this:

```javascript
const arguments = process.argv;

if (arguments && arguments.length > 0) {
  const workspaceArg = arguments[2]; // The workspace path
  const filePath = arguments[3]; // The path of the file
  const title = arguments[4]; // Title of the page

  console.log(Math.random().toString(36).substring(2, 15));
}
```

> **Info**: Like the other content scripts, you can use other types of scripts like Python, Bash, and more.

The base script for a dynamic placeholder similar to the [content script](/docs/custom-actions/#content-script). The difference is that instead of retrieving the whole front matter object, you will receive the title. The reason is that the file is still not completely processed, and not all front matter fields are available.

> **Important**: In case you need to retrieve the whole front matter object, you can make use of the `postScript` property on your content type in combination with a [content script](/docs/custom-actions/#content-script).

#### Placeholder usage

To use the `ogImage` placeholder, you need to define the `{{ogImage}}` value in your field as follows:

```json
{
  "title": "Unique ID",
  "name": "uniqueId",
  "type": "string",
  "default": "{{uniqueId}}"
}
```

Placeholders


## Preview path

For more information on how to use the preview path, see the [preview configuration](/docs/site-preview#configuration) section.

## Page and leaf bundles

The page or leaf bundles, are a way to group your pages and resources together in a single folder.

```
content/
├── about
│   ├── index.md
├── posts
│   ├── leaf-bundle
│   │   ├── image1.jpg
│   │   ├── image2.png
│   │   └── index.md
│   └── leaf-bundle
│       └── index.md
│
└── another-section
    ├── ..
    └── leaf-bundle
        └── index.md
```

In the above section you can see the `leaf-bundle` folders. These bundles consist of a `index.md` file and possibly also the resouces related to it like images.

By default, Front Matter will create individual Markdown files, but you can also create a leaf bundle. In order to do so, you need to set the `pageBundle` property in your content type to `true`.

Here is an example of configuring the page bundles for the `default` content type:

```json
"frontMatter.taxonomy.contentTypes": [
  {
    "name": "default",
    "pageBundle": true,
    "fields": [
      ...
    ]
  }
]
```

## Creating a template

To make sure that your type of content is already defined when creating a new Markdown file. It will be easier to set the type of content within a template.

You can create Markdown templates in your project's `.frontmatter/templates` folder (or defined differently).

```markdown
---
title: 
slug: 
description: 
date: 2019-08-22T15:20:28.000Z
lastmod: 2019-08-22T15:20:28.000Z
weight: 1
type: documentation
---
```

If you already have an existing page, you can automatically create a template from it by running the `Front Matter: Create a template from the current file` command.

The create template command will ask you the template's name and if you want to include the content. The front matter data is included by default.

## Preserve casing of file names

When you create a new page, the file name will be created based on the sanitized `title` property. During the sanitization, the `title` property will be converted to lowercase and all spaces will be replaced with dashes.

If you want to preserve the casing of the file name, you can set the `frontMatter.file.preserveCasing` setting to `true`.

```json
{
  "frontMatter.file.preserveCasing": true
}
```

Additional configuration


# Dashboard

## Overview

Managing your Markdown pages/media has never been easier in VS Code. With the Front Matter dashboard, you will be able to view all your pages and media.

On the contents view, you can **search**, **filter**, **sort** your pages and much more.

![Dashboard - Contents view](/releases/v7.1.0/dashboard-7.1.0.png)

On the media view, you can quickly glance all the available media files in your project and perform quick actions like copying the relative path.

![Dashboard - Media view](/releases/v7.1.0/dashboard-media.png)

In order to start using the dashboard, you will have to let the extension know in which folder(s) it can find your pages. Be sure to follow our [getting started](/docs/getting-started) guide.

> **Important**: If your preview images are not loading, it might be that you need to configure the `publicFolder` where the extension can find them. For instance, in Hugo, this is the static folder. You can configure this by updating the `frontMatter.content.publicFolder` setting.

## Commands

There are the following commands to open the dashboards:

| Command title | Command id | Description |
| --- | --- | --- |
| Front matter: Open dashboard | `frontMatter.dashboard` | Opens the dashboard on the contents view. |
| Front matter: Open media dashboard | `frontMatter.dashboard.media` | Opens the dashboard on the media view. |
| Front matter: Open snippets dashboard | `frontMatter.dashboard.snippets` | Opens the dashboard on the snippets view. |
| Front matter: Open data dashboard | `frontMatter.dashboard.data` | Opens the dashboard on the data view. |
| Front matter: Open taxonomies dashboard | `frontMatter.dashboard.taxonomy` | Opens the dashboard on the taxonomies view. |

## Contents view

### Card tags

The tags underneath the content abstract/description is changable. By default, the card will show the value of the `tags` field, but you can update the field by specifying the value in the `frontMatter.dashboard.content.cardTags` setting.

![Card tags](/releases/v7.1.0/card-tags.png)

### Draft status navigation

By default, the contents view will show all your pages, and will you will be able to filter by **draft** and **published** pages.

![Draft filters](/releases/v7.1.0/draft-filters.png)

If you want to use other statuses, you can do so by specifying your own draft field and value.

> **Info**: [Set a custom draft field](/docs/content-creation/fields#draft).

![Draft filters](/releases/v5.3.0/draft-status.png)

### Supported filters

- Tag filter
- Category filter
- Content folder (when you have multiple registered)

### Supported sorting

- Last modified
- Filename (asc/desc)

> **Info**: You can define custom sorting options by specifying these within the [frontMatter.content.sorting](/docs/settings#frontmatter.content.sorting) setting.

You are also able to define your default sorting options by setting the `frontMatter.content.defaultSorting` setting for the content view, and the `frontMatter.media.defaultSorting` setting for the media view.

### Show on startup

If you want, you can check on the `Open on startup?` checkbox. This setting will allow the dashboard to automatically open when you launch the project in VS Code. It will only apply to the current project, not for all of them.

### Content pagination

By default, the content is paginated by 16 items. If you want, you can disable the pagination by setting the `frontMatter.dashboard.content.pagination` setting to `false`.

## Media view

The media view has been created to make it easier to look at all media files available for your articles. When you click on an image, it will show a lightbox, so that it is easier to glance at small images.

![Dashboard - Media view - Lightbox](/releases/v5.9.0/media-lightbox.png)

### Supported files

By default, the media dashboard supports audio, image, and video files to be displayed and uploaded (drag&drop).

If you want that the media dashboard supports additional file types, you can define these in the `frontMatter.media.supportedMimeTypes` setting.

```json
"frontMatter.media.supportedMimeTypes": [
  "image/*",
  "video/*",
  "audio/*"
]
```

### Media actions

On the image card, there are actions like setting metadata, copying the relative path, and deleting the media file.

**Setting metadata**

Setting metadata got introduced so that you can set the description and alt tag of your images. This functionality makes it easier to insert your images to your content.

![Dashboard - Setting metadata](/releases/v5.0.0/metadata-media.png)

> **Info**: Check the [Insert images section](/docs/markdown#insert-images) for more information.

> **Important**: Data is stored in a local JSON file which you can find under: `<project>/.frontmatter/content/mediaDb.json`. Please do not remove this file, or you will lose your metadata.

**Deleting a media file**

![Dashboard - Delete media file](/releases/v5.9.0/media-deletion.png)

**Custom media actions**

In version `5.6.0` of the extension, you can now define your own media actions. This extensibility option is very useful for adding your own optimizations, functionality, or anything else you want.

For instance, you can use it to optimize the image(s) size.

Custom actions for media files can be defined on two levels:

- File level: Single file action
- Folder level: Multiple files action

> **Info**: Check out [creating media scripts](/docs/custom-actions#creating-a-media-script) for more information.

### Drag and Drop

On the media view, we enabled drag and drop for your media files. You can easily drop any image from your explorer/finder window into one of your folders.

![Dashboard - Upload media file](/releases/v5.9.0/media-upload.png)

## Data files view

Data files/folders are pieces of content that do not belong to any markdown content, but live on their own. Most of the time, these data files are used to store additional information about your project/blog/website that will be used to render the content.

For example: navigation, social media links, contacts, etc.

The data files dashboard allows you to quickly manage your data files.

![Data files dashboard](/releases/v6.0.0/data-files-dashboard.png)

### Configuration

In order to use the data files dashboard, you will need to configure the extension with the following settings:

- `frontMatter.data.types`: This only defines the object and its fields. Use this setting, if you want to re-use a data type in various files/folders.
- `frontMatter.data.files`: Defines how a single data file.
- `frontMatter.data.folders`: Defines that all files of a folder need to be treated the same.

### Creating a data file

To create a data file, you can use the `frontMatter.data.files` setting. 

```json
"frontMatter.data.files": [
  {
    "id": "sponsors",
    "title": "Sponsors",
    "file": "[[workspace]]/data/sponsors.json",
    "fileType": "json",
    "labelField": "name",
    "schema": {
      "title": "Sponsors",
      "type": "object",
      "required": [
        "name",
        "url"
      ],
      "properties": {
        "name": {
          "type": "string",
          "title": "Name"
        },
        "url": {
          "type": "string",
          "title": "URL"
        },
        "description": {
          "type": "string",
          "title": "Description"
        }
      }
    }
  }
]
```

The above sample can be used to create a sponsor data file which contains an array of sponsor object with url, name, and description as properties.

![Data dashboard - Sponsor example](/releases/v6.0.0/data-dashboard-sample.png)

> **Info**: Use the `[[workspace]]` placeholder to define the workspace folder. The extension will automatically replace this with the workspace folder path.

> **Important**: In the `schema` property we use the [JSON Schema](https://json-schema.org/) standard to define the structure of the data file.

### Re-using a data type for files or folders

In some cases, you might want to re-use a data type for files or folders. You can do so by using the `frontMatter.data.types` setting in combination with the `frontMatter.data.files` and/or `frontMatter.data.folders` settings.

First the data type, this is an object containing the `id` and `schema` properties.

```json
"frontMatter.data.types": [
  {
    "id": "sponsors",
    "schema": {
      "title": "Sponsors",
      "type": "object",
      "required": [
        "name",
        "url"
      ],
      "properties": {
        "name": {
          "type": "string",
          "title": "Name"
        },
        "url": {
          "type": "string",
          "title": "URL"
        },
        "description": {
          "type": "string",
          "title": "Description"
        }
      }
    }
  }
]
```

In the `frontMatter.data.files` and/or `frontMatter.data.folders` settings, instead of defining the `schema` property, you can use the `type` property to reference the data type.

```json
"frontMatter.data.files": [
  {
    "title": "All sponsors",
    "id": "all-sponsors",
    "file": "[[workspace]]/data/sponsors",
    "labelField": "name",
    "type": "sponsors"
  }
]
```

> **Important**: when using data folders, the extension searches for `yml`, `yaml`, and `json` files in the folder.


## Taxonomies view

The taxonomies view is a powerful way to manage your taxonomy like categories, tags, or any other taxonomy. 

On the taxonomies view, you can create, edit, delete, and move taxonomy terms from one type to another.

![Taxonomies view](/releases/v8.1.0/taxonomies-view.png)

### Actions

![Taxonomy actions](/releases/v8.0.0/taxonomy-actions.png)

You can perform the following actions on the taxonomies view:

- **Add**: If a taxonomy value is not yet stored in your settings, the `+` add action is shown to allow you a quick way to store the value;
- **Edit**: Edit the taxonomy value in the settings + all the files where it is used;
- **Merge**: Merge two taxonomy values into one. For instance, if you have `dev` and `development` you can merge `dev` into `development` and it will update all the files where it is used;
- **Move**: Move a taxonomy value to another type. For instance, if you want to move a tag to a category;
- **Delete**: Delete a taxonomy value.

Dashboard


# Editor panel

## Overview

The Front Matter panel allows you to perform most of the extension actions by just a click on the button, and it shows the SEO statuses of your title, description, and more.

> **Info**: Initially, this panel was created to add tags and categories easily to your articles, as currently, VS Code multi-select is not optimal to use when having a lot of tags/categories.

To leverage most of the capabilities of the extension. SEO information and everyday actions like slug optimization, updating the date, and publish/drafting the article.

## Using the panel

Once you installed the extension, you will notice a Front Matter icon on the activity bar (by default on the left side). Clicking this icon will open the Front Matter panel.

![Activity bar action](/assets/activitybar-action.png)

## Global settings

In this section of the panel, you can modify a couple of the useful settings to have close to hand.

![Global settings](/releases/v6.0.0/local-server.png)

> **Info**: The global settings section will also be shown when you have the panel open on other types of files.

> **Local server command**: If you already defined your framework or SSG via the `frontMatter.framework.id` setting, we provide a default start command for you. You can override this by providing your own start command.

## SEO status

Search Engine Optimization or simply SEO is very important to any site. The extension shows you more information about how well your article is written.

Supports the following:

- Title and description length validation
- Article length recommendation
- Keyword validation on title, description, slug, and content
- More content details

![SEO](/releases/v5.3.0/seo-status.png)

### Settings

In case you want to change the SEO settings, you can use the following settings: 

- `frontMatter.taxonomy.seoSlugLength`: Specifies the optimal title length for SEO (set to `-1` to turn it off).
- `frontMatter.taxonomy.seoTitleLength`: Specifies the optimal title length for SEO (set to `-1` to turn it off).
- `frontMatter.taxonomy.seoDescriptionLength`: Specifies the optimal description length for SEO (set to `-1` to turn it off).
- `frontMatter.taxonomy.seoContentLengh`: Specifies the optimal minimum length for your articles. Between 1,760 words – 2,400 is the absolute ideal article length for SEO in 2021. (set to `-1` to turn it off).
- `frontMatter.taxonomy.seoDescriptionField`: Specifies the name of the SEO description field for your page. Default is 'description'.

To discover your internal links, you can specify your base URL with the `frontMatter.site.baseURL` setting.

## Actions

When writing articles, there are always a couple of actions you need/want to perform. In this section, we provide you the most used/requested actions like:

- Optimizing the slug
- Setting the publishing date
- Setting the modified date
- Publish or revert to draft

![Actions](/releases/v6.0.0/local-server-start.png)

> **Important**: You are able to add your own actions, more information about this you can read in our [custom actions](/docs/custom-actions) section.

> **Info**: In version `3.2.0` a couple of actions were moved to the metadata section like changing the draft state and date time properties.

### Settings

The following settings are related to these actions:

- `frontMatter.preview.host`: Specify the host URL (example: http://localhost:1313) to be used when opening the preview.
- `frontMatter.taxonomy.slugPrefix`: Specify a prefix for the slug.
- `frontMatter.taxonomy.slugSuffix`: Specify a suffix for the slug.
- `frontMatter.taxonomy.alignFilename`: Align the filename with the new slug when it gets generated.

## Metadata

In the metadata section, you can manage the front matter of your Markdown file. This section is fully customizable to your needs with our `content type` support.

![Metadata section](/assets/metadata.png)

> **Info**: More information about content creation/content types/fields can be read at [content creation section](/docs/content-creation).

The tags and categories inputs allow you to insert known and unknown tags/categories. When an unknown tag/category gets added, it will show a `+` sign that allows you to add it to your configuration so that it will appear in the known tags/categories next time.

### Content type actions

When Front Matter notices a difference between your content and the content type defined, it will show you a list of actions.

![Content type actions](/releases/v7.2.0/content-type-actions.png)

- **Create content type**: This will generate a new content type based on the fields in your front matter.
- **Update missing fields**: Adds the fields that are missing in your content type.
- **Set content type**: Allows you to set a content type (which you already defined) for your content.

### Settings

- `frontMatter.panel.freeform`: Specifies if you want to allow yourself from entering unknown tags/categories in the tag picker (when enabled, you will have the option to store them afterwards). Default: `true`.
- `frontMatter.taxonomy.frontMatterType`: Specify which Front Matter language you want to use. The extension supports `YAML` (default), `TOML`, and `JSON`.
## Recently modified

Navigate quickly to a recently modified file. In the recently modified section, the latest 10 modified files get shown. 

![Recently modified](/assets/recent-files.png)

> **Important**: In order to use this functionality, a registered content folder needs to be present. More information in our [getting started](/docs/getting-started) section.

> **Info**: The recently modified section will also be shown when you have the panel open on other types of files.

## Other actions

This section provides a couple of other useful actions, like opening the current project in your explorer/finder. 

![Other actions](/assets/other-actions.png)

> **Info**: The `writing settings enabled / enable write settings` action allows you to make Markdown specific changes to optimize the writing of your articles. It will change settings like the `fontSize`, `lineHeight`, `wordWrap`, `lineNumbers` and more.

> **Info**: The other actions section will also be shown when you have the panel open on other types of files.


## View modes

By default, Front Matter will show all its potential and functionalities to the end-user. As you do not always require all functionality, Front Matter allows you to create view modes. 

You can define what functionality you want to show and use in a view mode.

The creation of a view mode can be done in the `frontMatter.global.modes` setting and the by default activated mode, can be set in the `frontMatter.global.activeMode` setting.

You define a mode with an `id` and a set of features. The allowed features are the following:

**Panel**

- `panel.globalSettings`: Show the global settings section.
- `panel.seo`: Show the SEO status section.
- `panel.actions`: Show the actions section.
- `panel.metadata`: Show the metadata section.
- `panel.contentType`: Show the content type create, update, and set actions underneath the metadata panel section.
- `panel.recentlyModified`: Show the recently modified files section.
- `panel.otherActions`: Show the other actions section.

**Dashboards**

- `dashboard.snippets.view`: Show the snippets dashboard.
- `dashboard.snippets.manage`: Show the snippets management actions.
- `dashboard.data.view`: Show the data dashboard.
- `dashboard.taxonomy.view`: Show the taxonomy dashboard.

Here is an example of a custom view mode:

```json
"frontMatter.global.activeMode": "",
"frontMatter.global.modes": [
  {
    "id": "minimal",
    "features": [
      "panel.metadata",
      "panel.globalSettings",
      "panel.seo",
      "dashboard.data.view",
      "dashboard.snippets.view"
    ]
  }
]
```

Once you created a new view mode, you can change between the default and custom ones. You find the mode switch in the panel:

![Switch view mode](/releases/v7.1.0/panel-mode-switch.png)

Or in the status bar:

![Status bar mode switch](/releases/v7.1.0/status-bar-mode-switch.png)

Editor panel


# Custom actions

## Overview

Not every website is the same. That is why we want to give you the ability to extend Front Matter and you can do this by adding your custom actions to the Front Matter panel. A custom action is nothing more than a Node.js script which is referenced from within your project.

![Custom action](/assets/custom-action.png)

> **Sample**: [Generate open graph preview image in Code with Front Matter](https://www.eliostruyf.com/generate-open-graph-preview-image-code-front-matter/)

> **Important**: You can add custom actions for your content and media files.

## The custom action setting

The content and media custom actions can be defined by using the `frontMatter.custom.scripts` setting.

Custom actions can be configured with the following properties:

- `id`: The id of the custom action/script
- `title`: The title of the custom action
- `script`: The path to the script to execute
- `command`: The command to execute. Example: `node`, `path to your node executable`, `bash`, `python`, ... (default: `node` - optional).
- `type`: The type for which the script will be used. Can be `content`, `mediaFile`, or `mediaFolder`. (default: `content` - optional).
- `bulk`: Run the script for one file or multiple files. .
- `output`: Specifies the output type (default: `notification` - optional). Available values are:
  - `notification`: The output will be passed as a notification.
  - `editor`: The output will be passed to the editor.
- `outputType`: Specifies the output type (default: `text` - optional). Available values the editor values from VS Code like:
  - `text`: The output will be passed as a text file.
  - `html`: The output will be passed as an HTML file.
  - `markdown`: The output will be passed as an Markdown file.
- `hidden`: Hide the action from the UI. This is mostly used when creating a content script that will be used to post process new content (default: `false` - optional).

> **Important**: Previously, you could define the `nodeBin` property to define the path to your node executable. This path was needed when you are working with for instance `nvm` and have multiple versions of node installed. You can now use the `command` property instead.

## Creating a content script

Create a folder in your project where you want to store all your custom scripts, and create a new JavaScript file. The sample content of this file looks like this:

```javascript
const arguments = process.argv;

if (arguments && arguments.length > 0) {
  const workspaceArg = arguments[2]; // The workspace path
  const fileArg = arguments[3]; // The file path
  const frontMatterArg = arguments[4]; // Front matter data

  console.log(`The content returned for your notification.`);
}
```

> **Info**: The sample script can be found here [sample-script.js](https://github.com/estruyf/vscode-front-matter/blob/HEAD/sample/script-sample.js)

The current workspace-, file-path, and front matter data will be passed as a arguments. Like you can see in the above sample script, you can fetch these argument values as follows:

- `arguments[2]`: The workspace path
- `arguments[3]`: The file path (Markdown file)
- `arguments[4]`: The front matter data as object

In order to use this functionality, you will need to configure the `frontMatter.custom.scripts` setting for your project as follows:

```json
{
  "frontMatter.custom.scripts": [{
    "title": "Generate social image",
    "script": "./scripts/social-img.js",
    "command": "~/.nvm/versions/node/v14.15.5/bin/node"
  }]
}
```

> **Important**: When the command execution would fail when it cannot find the node command. You are able to specify your path to the node app. Command execution might for instance fail when using `nvm`. You can use the `command` property to specify the path to your node executable (*this is optional*).

Once a custom action has been configured, it will appear on the Front Matter panel. The output of the script will be passed as a notification in VS Code. This output allows you to copy the output, useful when you generate additional content.

![Custom action output](/assets/custom-action-output.png)

### Updating the front matter

By default, once a custom action executed, it will show the output in a notification. In case you want to update the front matter of your content, you need to provide the data in the following JSON format.

```json
{ "frontmatter": { "<field name>": "field value" }}
```

Example:

```javascript
(async () => {
    // Your script logic

    // Finally, update the front matter of your content by passing the data in the following format
    const output = JSON.stringify({
      "frontmatter": {
        "title": "My new title"
      }
    });

    console.log(output);
  }
})();
```

When data is passed in the above format, it will automatically get parse the JSON data and the file its front matter gets updated accordingly.

## Bulk script execution

If you want, you can run a script for multiple files at once. This is useful when you want to generate a social image for all your markdown files or perform any other bulk operation.

To enable bulk script execution, you need to configure the `frontMatter.custom.scripts` setting for your project as follows:

```json
{
  "frontMatter.custom.scripts": [{
    "title": "Generate social image",
    "script": "./scripts/social-img.js",
    "command": "~/.nvm/versions/node/v16.13.0/bin/node",
    "bulk": true,
    "output": "editor"
  }]
}
```

> **Important**: The `bulk` property is what specifies if it is a script that should be executed for multiple files.

## Creating a media script

Creating a media script is similar to creating a content script. The only difference is that you need to specify the `type` property. You can use the `mediaFile` or `mediaFolder` as the value for the `type` property.

Like the name suggests, the `mediaFile` type will be used for scripts that should be executed for a single media file. The `mediaFolder` type will be used for scripts that should be executed for all media files in a folder.

Here is a sample on how you can define a media script:

```json
{
  "frontMatter.custom.scripts": [
    {
      "title": "Optimize media",
      "script": "./scripts/media.js",
      "command": "~/.nvm/versions/node/v16.13.0/bin/node",
      "type": "mediaFile"
    },
    {
      "title": "Optimize images",
      "script": "./scripts/media-all.js",
      "command": "~/.nvm/versions/node/v16.13.0/bin/node",
      "type": "mediaFolder"
    }
  ]
}
```

The current workspace-, file/folder-path will be passed as a arguments.

- `arguments[2]`: The workspace path
- `arguments[3]`: The file or folder path. This depends on the type of script.

### Media file script

When you defined a media file script, you will be able to execute it for a single media file from its menu.

![Custom action for a media file](/releases/v5.6.0/media-file-custom-script.png)

### Media folder script

When you defined a media folder script, you will be able to execute it for all media files in the menu next to the **create new folder** button.

![Custom action for a media folder](/releases/v5.6.0/media-folder-custom-script.png)

## Sample scripts

### Bash starter

```bash
echo "workspaceArg: $1"
echo "fileArg: $2"
echo "frontMatterArg: $3"
```

### Python starter

```python
#!/usr/bin/python3

import sys

print(f'workspaceArg: {sys.argv[1]}')
print(f'fileArg: {sys.argv[2]}')
print(f'frontMatterArg: {sys.argv[3]}')
```

### Optimize image (media file script)

```javascript
const path = require('path');

const arguments = process.argv;

(async () => {
  if (arguments && arguments.length > 0) {
    const imagemin = (await import('imagemin')).default;
    const imageminJpegtran = (await import('imagemin-jpegtran')).default;
    const imageminPngquant = (await import('imagemin-pngquant')).default;
    
    const fileArg = arguments[3]; // The file path
  
    await imagemin([fileArg], {
      destination: path.dirname(fileArg),
      glob: false,
      plugins: [
        imageminJpegtran(),
        imageminPngquant()
      ]
    });

    console.log(`Optimized image ${path.basename(fileArg)}`)
  }
})();
```

**Prerequisites**:

- `npm i imagemin imagemin-jpegtran imagemin-pngquant`

### Optimize images in the current folder (media folder script)

```javascript
const path = require('path');

const arguments = process.argv;

(async () => {
  if (arguments && arguments.length > 0) {
    const imagemin = (await import('imagemin')).default;
    const imageminJpegtran = (await import('imagemin-jpegtran')).default;
    const imageminPngquant = (await import('imagemin-pngquant')).default;

    const workspaceArg = arguments[2]; // The workspace path
    const folderArg = arguments[3]; // The folder path
  
    const files = await imagemin([path.join(folderArg, '*.{jpg,png}')], {
      destination: folderArg,
      glob: true,
      plugins: [
        imageminJpegtran(),
        imageminPngquant()
      ]
    });

    console.log(`Optimized images: ${files.length}`)
  }
})();
```

**Prerequisites**:

- `npm i imagemin imagemin-jpegtran imagemin-pngquant`


Custom actions


# Static Site Generator and Frameworks

## Overview

Front Matter's goal is not to be opinionated on which static site generator or framework you are using. We want to support all of them out there, but they can have their requirements, configurations, ...

In this section of the documentation, we will list them up and tell more about how you can get started.

## Support additional file types

As there are many static site generators out there, we probably do not support all the file types by default. However, you do not have to worry, if there is a file type you want to support, you can easily add it to the `frontMatter.content.supportedFileTypes` setting.

By default, Front Matter supports: `md`, `markdown`, and `mdx`. If you want to support other types, just add these to the `frontMatter.content.supportedFileTypes` setting.

```json
{
  "frontMatter.content.supportedFileTypes": [ "md", "markdown", "mdx", "svx" ]
}
```

### Hugo

Check out our Hugo configuration documentation to get you started using Front Matter: [Front Matter configuration with Hugo](/docs/ssg-and-frameworks/hugo-configuration).

### Eleventy

*Are you up for the challenge of writing this part of the documentation?*

[Update the docs](https://github.com/FrontMatter/web-documentation-nextjs/edit/main/content/docs/ssg.md)

### Gatsby

*Are you up for the challenge of writing this part of the documentation?*

[Update the docs](https://github.com/FrontMatter/web-documentation-nextjs/edit/main/content/docs/ssg.md)

### Next.js

*Are you up for the challenge of writing this part of the documentation?*

[Update the docs](https://github.com/FrontMatter/web-documentation-nextjs/edit/main/content/docs/ssg.md)

### SvelteKit

*Are you up for the challenge of writing this part of the documentation?*

[Update the docs](https://github.com/FrontMatter/web-documentation-nextjs/edit/main/content/docs/ssg.md)

### ...

*Are you using one which hasn't been referenced yet? Feel free to add it here.*

[Update the docs](https://github.com/FrontMatter/web-documentation-nextjs/edit/main/content/docs/ssg.md)

Static Site Generators


# Hugo Configuration

## Setting up Front Matter for your Hugo site

Start by opening your Hugo project in Visual Studio Code. 

> **Info**: For this article, we made use of the [Hugo Example site](https://github.com/gohugoio/hugoBasicExample) in combination with the *beautifulhugo* theme.

![Opening your Hugo project in VS Code](/hugo-configuration/hugo-configuration1.png)

## Installing Front Matter

Open the extensions panel in Visual Studio Code and search for Front Matter. Once you find it, click on the install button.

![Installing Front Matter extension](/hugo-configuration/hugo-configuration2.png)

The welcome dashboard appears if this is the first time you use Front Matter. 

If you have already installed or used Front Matter before, you can open the dashboard by executing the `Front Matter: Open dashboard` command. The steps to perform go as follows:

- Open the command prompt:
  - Windows `⇧+ctrl+P`
  - Mac: `⇧+⌘+P`
- Type: `Front Matter` and pick the `Front Matter: Open dashboard` command.

The welcome dashboard looks as follows:

![Welcome dashboard](/hugo-configuration/hugo-configuration3.png)

## Configuration of Front Matter

### Project initialization

On the welcome screen, click on the `Initialize project` action. This action creates the `.frontmatter` folder and `frontmatter.json` file in the current project.

![Project intialization](/hugo-configuration/hugo-configuration4.png)

### Framework or static-site generator

Next is to let Front Matter know which framework or static-site generator you use. In this case, we will pick **Hugo**.

![Selecting your framework or static-site generator](/hugo-configuration/hugo-configuration5.png)

### Content folders

Content folders are the locations where Front Matter needs to know where to create your `markdown` pages. 

To configure this, you need to open the `explorer panel` and perform the following steps:

- Right-click on the folder you want to add;
- From the folder menu, click on `Front Matter: Register folder`;

![Register content folder](/hugo-configuration/hugo-configuration6.png)

- Front Matter will ask you what name you want to give this folder. By default, it will take the same name as the added folder.

![Specify a name for the content folder](/hugo-configuration/hugo-configuration7.png)

- Once you complete this step, Front Matter's configuration is completed and opens the content dashboard.

![Content dashboard](/hugo-configuration/hugo-configuration8.png)

> **Info**: You can perform these steps for one folder or many. For instance, if you have multiple content types like blogs, posts, articles, news, etc. You can register each folder the same way.

## Using Front Matter

Now that Front Matter is configured, you can start creating content or managing your content via the Front Matter panel.

![Front Matter panel for content management](/hugo-configuration/hugo-configuration9.png)

## Extra configuration steps

If you want, you can further configure Front Matter to your preferences. Check more in our documentation what you can do: [documentation](/docs)

Hugo Configuration


# Site preview

## Overview

The Markdown preview is not consistently delivering the same result as the one you will see on your site. The Front Matter extension provides you a way to show the actual site instead. 

![Site preview](/assets/site-preview.png)

## Configuration

In order to use the site preview, you will first have to set the `frontMatter.preview.host` setting. You can set it via the `Global Settings` section in the Front Matter panel or in your `frontmatter.json` file. 

For example, with Hugo, the local server spins up on `http://localhost:1313`. When you set this URL as the value of the `frontMatter.preview.host` setting. You can click on the open preview button and the site preview will be shown.

### Prefix or section configuration

As Front Matter tries to support as many Static-Site Generators as possible, we made the choice to use settings that can be changed on various levels: global, per page folder, and per content type.

When you want to show the live site/page previews in Visual Studio Code, you can specify a custom preview path/prefix. For instance, if you create blog articles, and you want to prefix it with `blog/2021/11`, you can set this with the `previewPath` property.

> **Important**: The value used for the preview will be formatted with the article's date. This means that the engine will try to  convert all characters you enter to a date formatted string. In case you wan to skip some characters or all of them to be converted, you need to wrap that part between **two single quotes**. Example: `"'blog/'yyyy/MM"` will result in: `blog/2021/11`.

#### Globally

On the global level, you can use the `frontMatter.preview.pathName` setting to specify the global path that you want to add after the `frontMatter.preview.host` setting value and before your slug. 

This setting can be used for instance to include the year/month like: `yyyy/MM`. The date will be generated based on the article its date field value.

```json
{
  "frontMatter.preview.pathName": "'blog/'yyyy/MM"
}
```

#### Page folder

The `previewPath` property on the `frontMatter.content.pageFolders` setting, will override what is defined globally and can be used to specify a preview path per page folder.

```json
{
  "frontMatter.content.pageFolders": [
    {
      "title": "post",
      "path": "[[workspace]]/content/post",
      "previewPath": "'blog/'yyyy/MM",
    }
  ]
}
```

#### Content type

Similar to the `previewPath` on the page folder level, the `previewPath` property on the content type level will override what is defined on page folder level and globally.

```json
"frontMatter.taxonomy.contentTypes": [
  {
    "name": "default",
    "previewPath": "'blog/'yyyy/MM",
    "pageBundle": false,
    "fields": [
      ...
    ]
  }
]
```




Site preview


# Markdown features

## Overview

The Front Matter extension tries to make it easy to manage your Markdown pages/content. Within a Markdown page, we allow you to fold the file's Front Matter to be less distracting when writing. Also, do we highlight the Front Matter content to create a visual difference between content and metadata.

## WYSIWYG

To help out content editors write their content in Markdown. Front Matter provides a couple of helpful, what you see is what you get (WYSIWYG), controls while working in a Markdown file.

All the controls can be found on the top right of the opened file title bar.

![WYSIWYG controls](/releases/v5.7.0/wysiwyg_controls.png)

Currently supported are:

- Headings
- Bold
- Italic
- Hyperlink
- Strikethrough
- Block quote
- Code snippet
- Code block
- Ordered list
- Unordered list
- Task list

If you want, you can disable these controls with the following setting `frontMatter.content.wysiwyg`. By default, this is set to `true`. When changed to `false`, these controls will disappear.

### Inserting headings

When you click on the headings in the WYSIWYG controls, you will be asked which level of heading you want to insert.

![WYSIWYG headings](/releases/v5.7.0/wysiwyg_headings.png)

### Other WYSIWYG options

When you click on the elipsis icon in the WYSIWYG controls, you will be asked which of the advanced markup you want to insert.

![WYSIWYG options](/releases/v5.7.0/wysiwyg_options.png)

## Insert images

Inserting images was never easier with the `insert image into article` command, which can also be triggered with the image icon in the editor title bar (Markdown files only).

![Insert images](/releases/v4_0_0/insert-images.gif)

> **Info**: You can also use media snippets to insert your images. More information can be found in the [Media Snippets](/docs/snippets#media-snippets) section.

## Front matter folding

If you want to focus on the content of your page, you have the ability to fold the Front Matter section of your page.

![Folding range](/assets/folding.png)

## Front matter highlighting

The extension will automatically highlight the front matter of you document to create a visual difference between metadata and content.

![Highlighting](/assets/fm-highlight.png)

> **Info**: If you do not want this feature, you can disable it in the extension settings -> `Highlight Front Matter` or by setting the `frontMatter.content.fmHighlight` setting to `false`.

## Hiding front matter

Hiding the front matter in the editing experience can be done by the `frontMatter.content.hideFm` setting. By default, this is set to `false`. When changed to `true`, the front matter will be hidden in the editor.

In combination with this setting, you can also set a message to highlight that the front matter is hidden and the Front Matter panel needs to be used to edit the metadata of your page.

### Example

```json
{
  "frontMatter.content.hideFm": true,
  "frontMatter.content.hideFmMessage":"Use the editor panel to make front matter changes"
}
```

### Result

![Hide front matter](/releases/v8.1.0/hide-fm.png)




Markdown


# Snippets

## Overview

Snippets are a pre-defined chunk of code/text that can be used to insert in your content. It provides the editor an easy way to add various elements to the content that is defined for your project/website.

All snippets can be found on the snippets dashboard.

![Snippet dashboard](/releases/v7.0.0/snippet-dashboard.png)

## Create a snippet

Follow the next steps in order to create a snippet:

- Open the Front Matter dashboard, and navigate to the Snippets tab;
- Click on the **Create new snippet** button;
- Fill in the required fields;
- Click on the **Save** button.

Once you clicked on the **Save** button, the snippet is added to the `frontMatter.content.snippets` setting. All your placeholders will be automatically extracted and added to the `fields` property.

The snippet definition contains the following fields:

```json
"<snippet title>": {
  "description": "Description",
  "body": [],
  "fields": [],
  "openingTags": "[[",
  "closingTags": "]]"
}
```

- `description`: A short description of the snippet (optional);
- `body`: The snippet body, each string defined in the array is a new line;
- `fields`: The snippet fields;
- `openingTags`: The opening tags for the snippet (optional);
- `isMediaSnippet`: Specify if the snippet is to be used for media files (optional).

## Placeholders

In your snippets, you will be able to use placeholders to insert content from the Front Matter dashboard. To use a placeholder, you will need to add them via the following notation: `[[placeholder_name]]`.

Internally we use the `[[` as opening tags and `]]` as closing tags. These tags can be defined per snippet. In case of conflicts, you can define your own opening and closing tags on the snippet definition.

**Example:**

```html
{{< highlight [[type]] \"linenos=table,noclasses=false\" >}}
  [[selection]]
{{< / highlight >}}
```

In the above example, we the `type` and `selection` are the defined placeholders.

> **Important**: All variables are HTML-escaped by default, if you want to add unescaped HTML content, you need to add an `&` before your variable name. Example: `[[&selection]]`.

## Fields

Each placeholder defined, will have a corresponding field definition. If no field definition is defined for a placeholder, it will be shown as a input field when inserting the snippet.

The field definition is the same as the one we use for our content types (more information at [defining your own content type](/docs/content-creation/content-types#define-your-own-type)).

At this moment, we only support the following field types:

- `string`
- `choice`

To prepopulate a field, you can use the following special placeholders in the `default` property of your field:

- Standard placeholders are available like `{{year}}`, `{{month}}`, ... (see [Placeholders](/docs/content-creation/placeholders))
- `FM_SELECTED_TEXT`: This placeholder can be used to insert the selected text from the editor.

**Example:**

```json
"frontMatter.content.snippets": {
  "Highlight": {
    "description": "Creates a code highlighting box",
    "body": [
      "{{< highlight \"[[type]]\" \"linenos=table,noclasses=false\" >}}",
      "  [[selection]]",
      "{{< / highlight >}}"
    ],
    "fields": [
      {
        "name": "type",
        "title": "Language",
        "type": "choice",
        "choices": [
          "html",
          "css",
          "typescript"
        ],
        "default": "typescript"
      },
      {
        "name": "selection",
        "title": "Selection",
        "type": "string",
        "default": "FM_SELECTED_TEXT"
      }
    ]
  }
}
```

## Using a snippet

- Open one of your content files;
- Select your text (optional);
- Click on the **Insert snippet** button (or use the **Front Matter: Insert snippet into your content** command);

![Insert a snippet](/releases/v7.0.0/insert-snippet.png)

- Select the snippet you want to use;
- Fill in the fields;

![Fill in the snippet form](/releases/v7.0.0/insert-snippet-form.png)

- Click on insert.

The following steps generate the following outcome in the content (based on the above snippet example):

```markdown
{{< highlight typescript "linenos=table,noclasses=false" >}}
  Selected text from content
{{< / highlight >}}
```

## Media snippets

Media snippets are intended to be used when you want to insert a media file in your content. Media snippets are defined in the `frontMatter.content.snippets` setting, with the `isMediaSnippet` property set to `true`.

```json
"frontMatter.content.snippets": {
  "Image snippet": {
    "description": "Image with caption",
    "body": "{{< caption \"[[&mediaUrl]]\" \"[[caption]]\" >}}",
    "isMediaSnippet": true
  }
}
```

> **Info**: The media snippets provide you with a couple of media placeholders that you can use in your snippet body.

Media snippets will appear on your snippets dashboard, but can only be edited or deleted. You cannot insert media snippets into your content like you can with content snippets. Instead, you will find them on the media cards.

![Media snippet](/releases/v7.3.0/media-snippets.png)

### Placeholders

The available placeholders for your media snippets are the following:

- `mediaUrl`: Use this to insert the relative path to the media file.
- `mediaHeight`: Provides the height (dimension) of the media file.
- `mediaWidth`: Provides the width (dimension) of the media file.
- `caption`: Use this placeholder where you want to insert the caption.
- `alt`: Use this placeholder where you want to insert the alt attribute value.
- `filename`: Name of the file.
- `title`: Title of the file.

> **Info**: All placeholders are optional, so you can leave out the placeholders you do not want to use from your snippet.

### Fields

Like the content snippets, you can also define fields for your media snippets. These fields will be shown when you insert the snippet into your content.

```json
"frontMatter.content.snippets": {
  "Image snippet": {
    "description": "Image with caption",
    "body": "{{< caption src=\"[[&mediaUrl]]\" caption=\"[[caption]]\" class=\"[[className]]\" >}}",
    "isMediaSnippet": true,
    "fields": [
      {
        "name": "className",
        "title": "Class name",
        "type": "string",
        "default": "image__caption"
      }
    ]
  }
}
```

Snippets


# Commands

## Overview

Front Matter actions are also available as commands. In this section of the documentation all commands will be explained.

![Commands](/assets/commands-v6.1.0.png)

## Using commands

- Start by opening the command prompt:
  - Windows: ⇧+ctrl+P
  - Mac: ⇧+⌘+P
- Use one of the following commands

## Available commands

### Initialize project

This command will initialize the project with a template folder and an article template. It makes it easier to get you started with the extension and creating your content.

ID: `frontMatter.init`

### Open dashboard

Opens the dashboard with your Markdown pages overview. If you did not yet initialize your project, the welcome screen will be shown.

ID: `frontMatter.dashboard`

### Insert image into your content

Allows you to quickly insert an image reference in the Markdown file.

ID: `frontMatter.insertImage`

### Insert snippet into your content

Allows you to quickly insert a snippet in the Markdown file.

ID: `frontMatter.insertSnippet`

### Create category

Creates a new category and allows you to include it into your post automatically.

ID: `frontMatter.createCategory`

### Create tag

Creates a new tag and allows you to include it into your post automatically.

ID: `frontMatter.createTag`

### Insert categories

Inserts a selected categories into the front matter of your article/post/... - When using this command, the Front Matter panel opens and focuses on the specified type.

ID: `frontMatter.insertCategories`

### Insert tags

Inserts a selected tags into the front matter of your article/post/... - When using this command, the Front Matter panel opens and focuses on the specified type.

ID: `frontMatter.insertTags`

### Export all tags & categories to your settings

Export all the already used tags & categories in your articles/posts/... to your user settings.

ID: `frontMatter.exportTaxonomy`

### Remap or remove tag/category in all articles

This command helps you quickly update/remap or delete a tag or category in your markdown files. The extension will ask you to select the taxonomy type (tag or category), the old taxonomy value, and the new one (leave the input field blank to remove the tag/category).

> **Info**: Once the remapping/deleting process completes, your VS Code settings update with all new taxonomy tags/categories.

ID: `frontMatter.remap`

### Create a template from current file

This command allows you to create a new template from the current open Markdown file. It will ask you for the name of the template and if you want to keep the current file its content in the template.

ID: `frontMatter.createTemplate`

### Create new content from defined content type or template

With this command, you can easily create content in your project from the defined content types or templates.

> **Info**: The command will use the `frontMatter.templates.prefix` setting in order to add a prefix (default: `yyyy-MM-dd`) on the filename.

ID: `frontMatter.createContent`

### Generate slug based on content title

This command generates a clean slug for your content. It removes known stop words, punctuations, and special characters.

Example:

```yaml
---
title: Just a sample page with a title
slug: sample-page-title
---
```

You can also specify a prefix and suffix, which can be added to the slug if you want. Use the following settings to do this: `frontMatter.taxonomy.slugPrefix` and `frontMatter.taxonomy.slugSuffix`. 

By default, both prefix and suffix settings are not provided, which mean it would not add anything extra to the slug. 

Another setting is to allow you to sync the filename with the generated slug. The setting you need to turn on enable for this is `frontMatter.taxonomy.alignFilename`.

> **Info**: At the moment, the extension only supports English stopwords. 

ID: `frontMatter.generateSlug`

### Set lastmod date

Sets/updates the current modified date in your Markdown file.

ID: `frontMatter.setLastModifiedDate`

### Preview content

Open the site preview of your content in VS Code.

ID: `frontMatter.preview`

### Promote settings from local to team level

This command allows you to promote all local settings from within your `.vscode/settings.json` file to be promoted to the projects team configuration `frontmatter.json` file.

ID: `frontMatter.promoteSettings`

## Removed commands

### Set current date

This command has been removed, as it became obsolete since the introduction of Content Types.

ID: `frontMatter.setDate`


Commands


# Troubleshooting

## Overview

Unfortunately, sometimes you may encounter issues with the Front Matter extension. This can be due to the fact that there are misconfigurations, issues parsing your content, or bugs. We are constantly working to improve the extension and fix any issues you may encounter. In this section you can read what you can do to help you troubleshoot your Front Matter configuration.

## Content and front matter parsing

One of the main issues you may encounter is that there is something wrong in your markdown its front matter. This can be due to a typo, a missing comma, or a missing colon, ...

The extension uses a YAML or TOML parser, depending on the type of front matter you are using. If the extension would spot an error during the content parsing, it will highlight this in the editor and on the problems tab.

![Troubleshooting - Informing you of a parsing issue in the front matter of your article](/releases/v5.8.0/troubleshooting.png)

## Looking what is happening behind the scenes

The extension logs information, warnings, and errors into the Visual Studio Code output tab. You can find the log stream by selecting the `vscode-front-matter` or `vscode-front-matter-beta` extension from the output dropdown.

![Troubleshooting - Show the output of what the extension has been performing](/releases/v5.8.0/troubleshooting-output.png)

## Feature migrations

Sometimes it happens features get renamed or removed, under this section we will show you how to migrate your configuration to the new version.

### Publish and modified date migration

In version 7, the `frontMatter.taxonomy.dateField` and `frontMatter.taxonomy.modifiedField` settings have been deprecated. These settings are now replaced by two new content type field properties:

- `isPublishDate`: defines the publish date
- `isModifiedDate`: define the modified date

Follow the next steps in order to migrate your settings to the new properties:

**No custom content type**

When you use the default content type from Front Matter, you will already use the `isPublishDate` property. In case you were using the `frontMatter.taxonomy.modifiedField`, you will need to define your own content type and use the `isModifiedDate` property.

Check the [change the default content type](/docs/content-creation/content-types#changing-the-default-content-type) section for more information.

**When using a custom content type**

When you already have a custom content type defined, you can set the `isPublishDate` and `isModifiedDate` properties for the `datetime` fields.

Troubleshooting


# Settings

## Overview

Most of Front Matter is configurable to your needs. In this part of the documentation all settings are explained.

## Team settings and local settings

Since version 4 of Front Matter, Team settings got introduced. Teams settings allow you to have all settings on the project/solution level. You will be able to override them on user/local level (`.vscode/settings.json`).

The purpose of team settings is to share the global configuration of your CMS configuration. This way, your whole team can use the same tags/categories but apply their changes locally.

As you do not typically share your `.vscode/settings.json` configuration, we went for a `frontmatter.json` file on the root of your project/solution. The settings you provide in this JSON file are the same as you can configure on a local level. This allows you to easily copy, move settings from team to local level and vice versa.

## Migrate local settings to team settings

To allow you to easily migrate already defined settings, you can run the `Promote settings from local to team level` command. The very first time, it will also ask you if there are settings that can be promoted.

![On startup, Front Matter checks if settings can be promoted](/releases/v5.0.0/ask-to-promote-settings.png)

## Splitting your settings in multiple files

Some of the Front Matter settings can be split in multiple files to make management of these easier. For example, in case you are using multiple content-types for your site, you can now split each content-type to its own file. This allows you to easily manage the settings for each content-type.

### Supported settings to split

The following settings are supported to be split in multiple files:

| Setting name | Folder path | Information | JSON Schema |
| --- | --- | --- | --- |
| `frontMatter.content.pageFolders` |`./frontmatter/config/content/pagefolders/` | | `https://beta.frontmatter.codes/config/content.pagefolders.schema.json` | 
| `frontMatter.content.placeholders` | `./frontmatter/config/content/placeholders/` | | `https://beta.frontmatter.codes/config/content.placeholders.schema.json` |
| `frontMatter.content.snippets` | `./frontmatter/config/content/snippets/` | The file name will be used as the ID/title of the snippet. | `https://beta.frontmatter.codes/config/content.snippets.schema.json` |
| `frontMatter.custom.scripts` | `./frontmatter/config/custom/scripts/` | | `https://beta.frontmatter.codes/config/custom.scripts.schema.json` |
| `frontMatter.data.files` | `./frontmatter/config/data/files/` | | `https://beta.frontmatter.codes/config/data.files.schema.json` |
| `frontMatter.data.folders` | `./frontmatter/config/data/folders/` | | `https://beta.frontmatter.codes/config/data.folders.schema.json` |
| `frontMatter.data.types` | `./frontmatter/config/data/types/` | | `https://beta.frontmatter.codes/config/data.types.schema.json` |
| `frontMatter.taxonomy.contentTypes` | `./frontmatter/config/taxonomy/contenttypes/` | | `https://beta.frontmatter.codes/config/taxonomy.contenttypes.schema.json` |

> **Important**: The folder path is relative to the root of your project/solution and you create the files in their corresponding folder. The file name is the same as the `id` of the setting.

### Example of splitting a setting

Example of specifying a page folder in a separate file:

```
| .frontmatter
| - config
| -- content
| --- pagefolders
| ---- blog.json
```

Contents of the `blog.json` file:

```json
{
  "$schema": "https://beta.frontmatter.codes/config/content.pagefolders.schema.json",
  "title": "blog",
  "path": "[[workspace]]/blog"
}
```

## Available settings

### frontMatter.content.autoUpdateDate

Specify if you want to automatically update the modified date of your article/page.

- Type: `boolean`
- Default: `false`

### frontMatter.content.defaultFileType

Specify the default file type for the content to create.

- Type: `emum`
- Default: `md`

Options:

- `md`
- `mdx`

> For more information how and when this is used, check [content creation](/docs/content-creation#before-you-start)

### frontMatter.content.defaultSorting

Specify the default sorting option for the content dashboard. You can use one of the values from the enum or define your own ID.

- Type: `string` 
- Default: `""`

Options:

- LastModifiedAsc
- LastModifiedDesc
- FileNameAsc
- FileNameDesc
- `ID of your custom sorting option`

### frontMatter.content.draftField

Define the draft field you want to use to manage your content.

- Type: `object` 
  - **name**: Define the type of field
  - **type**: `boolean` or `choice`
  - **invert**: `true` if you want to invert the value. This inversion is only applied if the field is a boolean field and can be used to change the draft to published content behaviou.
  - **choices**: Define the choices of the draft field `string[]`

- Default: 

```json
{
  "name": "draft",
  "type": "boolean"
}
```

### frontMatter.content.fmHighlight

Specify if you want to highlight the Front Matter in the Markdown file.

- Type: `boolean`
- Default: `true`


### frontMatter.content.hideFm

Specify if you want to hide the Front Matter in the Markdown file.

- Type: `boolean`
- Default: `false`

### frontMatter.content.hideFmMessage

Specify the message to display when the Front Matter is hidden.

- Type: `string`
- Default: `""`

![Hide front matter from the content](/releases/v8.1.0/hide-fm.png)

### frontMatter.content.pageFolders

This array of folders defines where the extension can find your content and create new content by running the create article command.

- Type: `object[]`
- Default: `[]`

Properties:

| Title | Type | Description | Default | Required / Optional |
| --- | --- | --- | --- | --- |
| `title` | `string` | A title for the content folder path | `""` | Optional |
| `path` | `string` | The path to the content folder, important is to use the `[[workspace]]` placeholder | `""` | Required |
| `excludeSubdir` | `boolean` | Exclude subdirectories from the content folder | | Optional |
| `previewPath` | `string` | Allows you to set a prefix path for the page preview. Check the [preview path configuration](/docs/site-preview#configuration) section to learn more. |  | Optional |

> **Important**: `[[workspace]]` is a placeholder that the extension uses to replace the workspace path. The reason why we choose to use this, is because some do not keep the original folder name.

Sample:

```json
{
  "frontMatter.content.pageFolders": [
    {
      "title": "Pages",
      "path": "[[workspace]]/content",
      "excludeSubdir": true,
      "previewPath": "post" // Prefixes all files with "/post/" for the page preview
    },
    {
      "title": "Blog posts",
      "path": "[[workspace]]/content/posts"
    }
  ]
}
```

### frontMatter.content.placeholders

Allows you to specify custom placeholders to use in your content creation process.

- Type: `object[]`
- Default: `[]`

Properties:

- `id`: The id of the placeholder
- `value`: The value of the placeholder

> More information on how you can use it can be found here: [placeholders](/docs/content-creation/placeholders).

### frontMatter.content.publicFolder

Specify the folder name where all your assets are located. For instance in Hugo this is the `static` folder.

- Type: `string`
- Default: `""`

### frontMatter.content.sorting

Define the sorting options for your dashboard content.

- Type: `object[]`
- Default: `[]`

Properties:

- `title`: The title of the sorting option
- `name`: The name of the field to sort by (needs to be present in your content its front matter)
- `order`: The order of the sorting (ascending or descending). Option values to use: `asc` or `desc`.
- `type`: The type of field value. Option values to use: `string`, `date`, and `number`.

Sample:

```json
{
  "frontMatter.content.sorting": [
    {
      "title": "Date (asc)",
      "name": "date",
      "order": "asc",
      "type": "date"
    },
    {
      "title": "Date (desc)",
      "name": "date",
      "order": "desc",
      "type": "date"
    }
  ]
}
```

### frontMatter.content.supportedFileTypes

Specify the file types that you want to use in Front Matter.

- Type: `array` 
- Default: `[md, mdx, markdown]`

### frontMatter.content.wysiwyg

Specifies if you want to enable/disable the What You See, Is What You Get (WYSIWYG) markdown controls.

- Type: `boolean`
- Default: `true`

### frontMatter.custom.scripts

Specify the path to a Node.js script to execute. The current file path will be provided as an argument.

- Type: `object[]`
- Default: `[]`

Sample:

```json
{
  "frontMatter.custom.scripts": [{
    "title": "Generate social image",
    "script": "./scripts/social-img.js",
    "nodeBin": "~/.nvm/versions/node/v14.15.5/bin/node"
  }]
}
```

> **Info**: Check the [create your own custom scripts](/docs/custom-actions) section for more information.

### frontMatter.dashboard.content.cardTags

Specify the name of the metadata field that will be used to show the tags on the content card. When empty or null, it will hide the tags from the card.

- Type: `string` 
- Default: `tags`

> **Info**: Check the [card tags](/docs/dashboard#card-tags) section for more information.

### frontMatter.dashboard.content.pagination

Specify if you want to enable/disable pagination for your content.

- Type: `boolean` 
- Default: `true`

### frontMatter.dashboard.openOnStart

Specify if you want to open the dashboard when you start VS Code.

- Type: `boolean | null`
- Default: `null`

### frontMatter.data.files

Specify the data files you want to use for your website. 

- Type: `array` 
- Default: ``

> More information on how to use it can be found in the [data files view](/docs/dashboard#data-files-view) section.

### frontMatter.data.folders

Specify the data files you want to use for your website.

- Type: `array` 
- Default: ``

> More information on how to use it can be found in the [data files view](/docs/dashboard#data-files-view) section.

### frontMatter.data.types

Specify the data types. These types can be used in for your data files.

- Type: `array` 
- Default: ``

> More information on how to use it can be found in the [data files view](/docs/dashboard#data-files-view) section.

### frontMatter.file.preserveCasing

Specify if you want to preserve the casing of your file names from the title.

- Type: `boolean` 
- Default: `false`

> More information on how to use it can be found in the [preserve the casing for your file names](/docs/content-creation/additional-config#preserve-casing-of-file-names) section.

### frontMatter.framework.id

Specify the ID of your static site generator or framework you are using for your website.

- Type: `string`
- Default: `""`

### frontMatter.git.enabled

Specify if you want to use the Git actions for your website.

- Type: `boolean`
- Default: `false`


### frontMatter.git.commitMessage

Specify the commit message you want to use for the sync.

- Type: `string`
- Default: `Synced by Front Matter`

### frontMatter.global.activeMode

Specify the activated mode of Front Matter.

- Type: `string, null`

> **Info**: Check the [view mode](/docs/panel#define-view-modes) documentation section for more information.

### frontMatter.global.modes

Specify the modes you want to use for Front Matter.

- Type: `array` 
- Default: ``

> **Info**: Check the [view mode](/docs/panel#define-view-modes) documentation section for more information.

### frontMatter.global.disabledNotifications

This is an array with the notifications types that can be disabled for Front Matter CMS.

- Type: `array<string>`
- Default: `[]`
- Options:
  - `requiredFieldValidation`

### frontMatter.global.notifications

Specifies which type of notifications you want to see or which you want to hide.

- Type: `array<string>`
- Default: `["info", "warning", "error"]`

### frontMatter.media.defaultSorting

Specify the default sorting option for the media dashboard.

- Type: `string` 
- Default: `""`

Options:

- LastModifiedAsc
- LastModifiedDesc
- FileNameAsc
- FileNameDesc

### frontMatter.media.supportedMimeTypes

Specify the mime types to support for the media files.

- Type: `array` 
- Default: `image/*, video/*, audio/*`

### frontMatter.panel.freeform

Specifies if you want to allow yourself from entering unknown tags/categories in the tag picker (when enabled, you will have the option to store them afterwards).

- Type: `boolean`
- Default: `true`

### frontMatter.preview.host

Specify the host URL (example: http://localhost:1313) to be used when opening the preview.

- Type: `string`
- Default: `""`

### frontMatter.preview.pathName

Specify the path you want to add after the host and before your slug. This can be used for instance to include the year/month like: `yyyy/MM`. The date will be generated based on the article its date field value.

- Type: `string`
- Default: `""`

> **Important**: As the value will be formatted with the article's date, it will try to convert all characters you enter. In case you want to skip some characters or all of them, you need to wrap that part between two single quotes. Example: `"'blog/'yyyy/MM"` will result in: `blog/2021/08`.

### frontMatter.site.baseURL

Specify the base URL of your site, this will be used for SEO checks.

- Type: `string`
- Default: `""`

> **Info**: Example for this site it would be: `https://frontmatter.codes`.

### frontMatter.taxonomy.alignFilename

Align the filename with the new slug when it gets generated.

- Type: `boolean`
- Default: `false`

### frontMatter.taxonomy.categories

Specifies the categories which can be used in the Front Matter.

- Type: `string[]`
- Default: `[]`

### frontMatter.taxonomy.commaSeparatedFields

Specify the fields names that Front Matter should treat as a comma-separated array.

- Type: `string[]`
- Default: `[]`

> **Info**: As some site generators expect arrays in `YAML` to be comma-separated like Pelican. You can use this setting to define which of the front matter properties should be treated as an comma-separated array.

### frontMatter.taxonomy.contentTypes

Specify the type of contents you want to use for your articles/pages/etc. Make sure the `type` is correctly set in your front matter.

- Type: `array, null` 
- Default: check [default content type](/docs/content-creation/content-types#changing-the-default-content-type)


### frontMatter.taxonomy.customTaxonomy

Specify the custom taxonomy field data.

- Type: `array[object]`
- Default: `[]`

Sample:

```json
"frontMatter.taxonomy.customTaxonomy": [
    {
      "id": "customTaxonomy",
      "options": [
        "Option 1",
        "Option 2",
        "Option 3"
      ]
    }
  ]
```

> **Info**: Check the [custom taxonomy](/docs/content-creation/fields#taxonomy) section for more information.

### frontMatter.taxonomy.dateFormat

Specify the date format for your articles. Check [date-fns formating](https://date-fns.org/v2.0.1/docs/format) for more information.

- Type: `string`
- Default: `iso`

### frontMatter.taxonomy.fieldGroups

Define the field groups you want to use for your block fields.

- Type: `array[object]`
- Default: `[]`

> More information on how to use this setting can be found on the [block field](/docs/content-creation/fields#block) section of content creation. 

### frontMatter.taxonomy.frontMatterType

Specify which Front Matter language you want to use. The extension supports `YAML` (default), `TOML`, and `JSON`.

- Type: `enum: YAML | TOML | JSON`
- Default: `YAML`

### frontMatter.taxonomy.indentArrays

Specify if arrays in front matter of the markdown files are indented.

- Type: `boolean`
- Default: `true`

### frontMatter.taxonomy.noPropertyValueQuotes

Specify the property names of which you want to remove the quotes in the output value. Warning: only use this when you know what you are doing. If you're going to, for instance, remove the quotes from the date property, you can add the following:

```json
{
  "frontMatter.taxonomy.noPropertyValueQuotes": ["date"]
}
```

- Type: `string[]`
- Default: `[]`

### frontMatter.taxonomy.seoContentLengh

Specifies the optimal minimum length for your articles. Between 1,760 words – 2,400 is the absolute ideal article length for SEO in 2021. (set to `-1` to turn it off).

- Type: `number`
- Default: `1760`

### frontMatter.taxonomy.seoDescriptionField

Specifies the name of the SEO description field for your page.

- Type: `string`
- Default: `description`

> **Important**: if you would use another field in your content types, be sure to remap this setting.

### frontMatter.taxonomy.seoDescriptionLength

Specifies the optimal description length for SEO (set to `-1` to turn it off).

- Type: `number`
- Default: `160`

### frontMatter.taxonomy.seoSlugLength

Specifies the optimal slug length for SEO (set to `-1` to turn it off).

- Type: `number` 
- Default: `75`

### frontMatter.taxonomy.seoTitleLength

Specifies the optimal title length for SEO (set to `-1` to turn it off).

- Type: `number`
- Default: `60`

### frontMatter.taxonomy.slugPrefix

Specify a prefix for the slug.

- Type: `string`
- Default: `""`

### frontMatter.taxonomy.slugSuffix

Specify a suffix for the slug.

- Type: `string`
- Default: `""`

### frontMatter.taxonomy.tags

Specifies the tags which can be used in the Front Matter.

- Type: `string[]`
- Default: `[]`

### frontMatter.telemetry.disable

Specify if you want to disable the telemetry.

> **Important**: No user data is tracked, we only use telemetry to see what is used, and what isn't. This allows us to make accurate decisions on what to add or enhance to the extension.

- Type: `boolean`
- Default: `false`

### frontMatter.templates.enabled

Specify if you want to use templates functionality.

- Type: `boolean`
- Default: `false`

### frontMatter.templates.folder

Specify the folder to use for your article templates.

- Type: `string`
- Default: `.frontmatter/templates`

> **Important**: In version 5 of Front Matter, we moved the default location from `.templates` to `.frontmatter/templates`.

### frontMatter.templates.prefix

Specify the prefix you want to add for your new article filenames.

- Type: `string`
- Default: `yyyy-MM-dd`


## Deprecated settings

### frontMatter.taxonomy.dateField

This setting is used to define the publishing date field of your articles.

- Type: `string`
- Default: `date`

> **Important**: Use the new `isPublishDate` datetime field setting for content types instead.

### frontMatter.taxonomy.modifiedField

This setting is used to define the modified date field of your articles.

- Type: `string`
- Default: `lastmod`

> **Important**: Use the new `isModifiedDate` datetime field setting for content types instead.

### frontMatter.dashboard.mediaSnippet

This setting is deprecated in version 7.3.0 and and will be removed in the next major version. Please define your media snippet in the `frontMatter.content.snippet` setting.



## Removed settings

### frontMatter.content.folders

This setting has been deprecated since version `3.1.0` in favour of the newly introduced `frontMatter.content.pageFolders` setting.


GIT Integration

Enable GIT integration

Change the commit message

Feedback

Ready to get started?