
# Experimental features

This page contains all the experimental features in the Front Matter CMS.

> **Important**: These features are not yet fully tested and might not work as expected.
> If you find any issues,
> please [open an issue](https://github.com/estruyf/vscode-front-matter/issues).

## Enable experimental features

To enable the experimental features, you need to set the
`frontMatter.experimental` setting to `true`.

```json
"frontMatter.experimental": true
```

## Visual Studio Code theme support

The dashboards will now adapt to the colors of your current theme used in Visual Studio Code.
This feature is experimental because there are various themes and we want to make sure that
we support most of the themes out there.

<div style="display:flex;justify-items:center;">
  <img src="/releases/v8.3.0/theme1.png" alt="Theme example 1" style="max-width:45%" />
  <img src="/releases/v8.3.0/theme2.png" alt="Theme example 2" style="max-width:45%" />
</div>

<div style="display:flex;justify-items:center;">
  <img src="/releases/v8.3.0/theme3.png" alt="Theme example 3" style="max-width:45%" />
  <img src="/releases/v8.3.0/theme4.png" alt="Theme example 4" style="max-width:45%" />
</div>


Experimental features in the Front Matter extension.

Experimental features

# Introduction

## Overview

Are you tired of managing your markdown articles manually? Do you want to simplify 
the process of content creation and management? Look no further than the Front Matter 
extension for Visual Studio Code.

Designed for developers and content creators, Front Matter gives you the power and 
control of a full-blown CMS, without the hassle of dealing with servers, websites, or APIs. 
With Front Matter, you can create and manage your content directly in Visual Studio Code, 
using your favorite tools and workflows.

The extension supports several static-site generators and frameworks, including 
Astro, Hugo, Jekyll, Hexo, NextJs, Gatsby, and more.

![Welcome screen to configure your website][01]

## Features

Front Matter comes packed with a range of powerful features, including:

- A page dashboard that lets you search, filter, and type content with ease.
- A site preview that shows you exactly how your content will look before you publish it.
- SEO checks that help you optimize your content for search engines.
- Support for custom actions/scripts.
- And many more features.

![Site preview][02]

## Why Front Matter?

Initially, [Elio Struyf][03] developed the Front Matter extension when migrating from WordPress to
Hugo (static-site Generator), in order to facilitate content management.
Over time, he expanded the extension's capabilities, until it eventually evolved into a headless
CMS that runs in 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][04]


[01]: /releases/v7.2.0/welcome-screen-7.2.0.png
[02]: https://res.cloudinary.com/estruyf/image/upload/w_1256/v1631871148/frontmatter/preview-3.2.0.png
[03]: https://twitter.com/eliostruyf
[04]: 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.

<iframe width="560" height="315" style="margin: 2.25rem auto;" src="https://www.youtube.com/embed/xb6pZiier_E" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

## Installation

You can get the extension via:



- The VS Code marketplace: [VS Code Marketplace - Front Matter][01].
- 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][02].
- 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][03].

> **Important**: As there can only be one version running of the extension, you will need to
> either disable or uninstall the main version before installing the beta version. Disable
> both extensions globally and select "Enable (Workspace)" will enable the extension only in
> the currently loaded workspace. This way you can test the BETA version on some of your
> projects/workspaces and keep the main version installed and activated in other projects.

## 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][04]

> **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, you will need to initialize the project. This will create a
`frontmatter.json` file and a `.frontmatter` folder in the root of your
project in which the media database and templates will be stored.

### 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 your static-site generator or framework is not in the list, you will still be
able to configure the 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][05]

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][06]

> **Info**: By 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][07] configuration setting and specifying the `excludeSubDir`
> property with the value as `true`.

Since version `8.3.0` you can use [placeholders](/docs/content-creation/placeholders) in the folder
path. This functionality allows you to generate dynamic content paths based for example on the
current date.

## 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][08]

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][09]

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

![Hidden support links][10]

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][11]

Follow the proposed steps from Visual Studio Code.

## Enjoy using Front Matter



[01]: https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-front-matter
[02]: https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-front-matter-beta
[03]: https://beta.frontmatter.codes
[04]: /releases/v7.2.0/welcome-screen-7.2.0.png
[05]: /releases/v7.2.0/content-list.png
[06]: /assets/register-folder.png
[07]: /docs/settings/overview#frontmatter.content.pagefolders
[08]: /releases/v5.0.0/workspace-folder.png
[09]: /releases/v6.0.0/support-links.png
[10]: /releases/v6.0.0/support-links-hidden.png
[11]: /releases/v6.0.0/signin-github.png

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.
1. 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 
(in the `frontmatter.json`) 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][01]


[01]: /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][01]

### 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][02]                                                                                                                              | `[]`          |
| `filePrefix`      | `string`                                 | Defines a prefix for the file name                                                                                                                                 | `null`        |
| `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`          |
| `defaultFileName` | `string`                                 | Default file name to use when creating new content                                                                                                                 | `index`       |
| `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`][03] 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][04]   | `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][05] 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][06] section.

## Link to content folders

In case you want to make sure that a content type is only available for specific folders,
you can use the `contentTypes` property on the `frontMatter.content.pageFolders` setting.

```json
{
  "frontMatter.content.pageFolders": [
    {
      "title": "Documentation",
      "path": "[[workspace]]/content/docs",
      "contentTypes": ["documentation"]
    }
  ]
}
```



[01]: /assets/adapted-default-ct.png
[02]: /docs/content-creation/fields#supported-field-types
[03]: /docs/settings/overview#frontmatter.preview.pathname
[04]: /docs/custom-actions/#content-script
[05]: /docs/content-creation/fields
[06]: /docs/custom-actions

Content types

Fields


# Field conditions

Field conditions allow you to show or hide fields based on the value of another field. 
This is useful when you want to show a field only when a specific value is selected or provided.

## Show or hide fields

To show or hide a field, you need to add the `when` property to the field.

```json
{
  "title": "Show or hide field",
  "name": "showOrHideField",
  "type": "string",
  "when": {
    "fieldRef": "title",
    "operator": "contains",
    "value": "<the value to validate>",
    "caseSensitive": false
  }
}
```

| Property | Description |
| --- | --- |
| `fieldRef` | The name of the field to validate |
| `operator` | The operator to use to validate the field value. See [Supported operators](#supported-operators) |
| `value` | The value to validate |
| `caseSensitive` | If the validation should be case sensitive. Default: `true` |

## Supported operators

| Type | Value |
| --- | --- |
| Equals | `eq` |
| Not equals | `neq` |
| Contains | `contains` |
| Not contains | `notContains` |
| Starts with | `startsWith` |
| Ends with | `endsWith` |
| Greater than | `gt` |
| Greater than or equal | `gte` |
| Less than | `lt` |
| Less than or equal | `lte` |

Field conditions

# 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.

## Default placeholders

| Placeholder  | Description                                                                                      |
| ------------ | ------------------------------------------------------------------------------------------------ |
| `{{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                                                                                      |
| `{{hour12}}` | Current hour in 12-hour format                                                                   |
| `{{hour24}}` | Current hour in 24-hour format                                                                   |
| `{{ampm}}`   | Show AM/PM                                                                                       |
| `{{minute}}` | Current minute                                                                                   |

## Special placeholders

| Placeholder             | Description                                                | Works for                                             |
| ----------------------- | ---------------------------------------------------------- | ----------------------------------------------------- |
| `{{fm.<field name>}}`   | The value of the field in the front matter                 | `previewPath` on the page folder or the content-type. |
| `{{pathToken.<index>}}` | The value of the path token at the index                   | `previewPath` on the page folder or the content-type. |
| `{{pathToken.relPath}}` | The relative value path staring from the page folder' path | `previewPath` on the page folder or the content-type. |

### Example 1

Example of how you can use the special placeholders:

```json
"frontMatter.content.pageFolders": [
  {
    "title": "post",
    "filePrefix": null,
    "previewPath": "/{{fm.type}}/{{pathToken.3}}/{{pathToken.4}}",
    "path": "[[workspace]]/content/{{year}}/{{month}}",
    "contentTypes": ["post"]
  }
]
```

The preview path will generate the following path: `/post/2023/02/<slug>`.

### Example 2

```json
"frontMatter.content.pageFolders": [
  {
    "title": "post",
    "filePrefix": null,
    "previewPath": "/{{pathToken.relPath}}/",
    "path": "[[workspace]]/content"
  }
]
```

If a file would exist in: `./content/docs/settings.md`. The preview path will generate the following
path: `/docs/settings/`.

## 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][01]. 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][01].

#### 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}}"
}
```



[01]: /docs/custom-actions/#content-script

Placeholders


# Additional configuration

## Preview path

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

## File prefixes

By default, Front Matter will use the `yyyy-MM-dd` date format for the file prefix. You can change this per page folder or per content-type.

### Page folder level

To change the file prefix for a specific page folder, you can add the `filePrefix` property to your page folder in the `frontMatter.content.pageFolders` setting.

```json
{
  "frontMatter.content.pageFolders": [
    {
      "title": "Blog",
      "path": "[[workspace]]/content/blog",
      "filePrefix": "yyyy"
    }
  ]
}
```

### Content-type level

Similarly, you can change the file prefix for a specific content type by adding the `filePrefix` property to your content type in the `frontMatter.taxonomy.contentTypes` setting.

> **Important**: The `filePrefix` from the content-type will override the `filePrefix` property from the page folder.

```json
{
  "frontMatter.taxonomy.contentTypes": [
    {
      "name": "default",
      "filePrefix": "yyyy-MM",
      "fields": [
        ...
      ]
    }
  ]
}
```

## Page and leaf bundles

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

```markdown
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][01]

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][02]

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][03] 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. |


[01]: /releases/v7.1.0/dashboard-7.1.0.png
[02]: /releases/v7.1.0/dashboard-media.png
[03]: /docs/getting-started

Dashboard

# 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][01]

## 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][02]

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][03].

![Draft filters][04]

## 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][05] 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`. In case you want to change the number of items per page, you can specify a number in the same setting.



[01]: /releases/v7.1.0/card-tags.png
[02]: /releases/v7.1.0/draft-filters.png
[03]: /docs/content-creation/fields#draft
[04]: /releases/v5.3.0/draft-status.png
[05]: /docs/settings/overview#frontmatter.content.sorting

Content view

# 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][01]

## 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][02]


> **Info**: Check the [Insert images section][03] 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][04]

### 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][05] 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][06]


[01]: /releases/v5.9.0/media-lightbox.png
[02]: /releases/v5.0.0/metadata-media.png
[03]: /docs/markdown#insert-images
[04]: /releases/v5.9.0/media-deletion.png
[05]: /docs/custom-actions#creating-a-media-script
[06]: /releases/v5.9.0/media-upload.png

Media view

# 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][01]

## 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",
    "singleEntry": false,
    "schema": {
      "title": "Sponsors",
      "type": "object",
      "required": [
        "name",
        "url"
      ],
      "properties": {
        "name": {
          "type": "string",
          "title": "Name"
        },
        "url": {
          "type": "string",
          "title": "URL"
        },
        "description": {
          "type": "string",
          "title": "Description"
        }
      }
    }
  }
]
```

> **Info**: The `singleEntry` setting is used to define if the data file is a single entry or a not.

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][02]


> **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][03] 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.



[01]: /releases/v6.0.0/data-files-dashboard.png
[02]: /releases/v6.0.0/data-dashboard-sample.png
[03]: https://json-schema.org/

Data files view

# 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][01]

## Actions

![Taxonomy actions][02]

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.


[01]: /releases/v8.1.0/taxonomies-view.png
[02]: /releases/v8.0.0/taxonomy-actions.png

Taxonomy view

# 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][01]

## Global settings

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

![Global settings][02]



> **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][03]

### Settings

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

| Setting                                     | Description                                                                                                                                                             | 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). | `1760`        |
| `frontMatter.taxonomy.seoDescriptionField`  | Specifies the name of the SEO description field for your page.                                                                                                          | `description` |
| `frontMatter.taxonomy.seoDescriptionLength` | Specifies the optimal description length for SEO (set to `-1` to turn it off).                                                                                          | `160`         |
| `frontMatter.taxonomy.seoSlugLength`        | Specifies the optimal title length for SEO (set to `-1` to turn it off).                                                                                                | `75`          |
| `frontMatter.taxonomy.seoTitleField`        | Specifies the name of the title field for your page                                                                                                                     | `title`       |
| `frontMatter.taxonomy.seoTitleLength`       | Specifies the optimal title length for SEO (set to `-1` to turn it off).                                                                                                | `60`          |

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][04]

> **Important**: You are able to add your own actions, more information about this you can read in
> our [custom actions][05] 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][06]

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

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][08]

- **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][09]

> **Important**: In order to use this functionality, a registered content folder needs to be
> present. More information in our [getting started][10] 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][11]

> **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][12]

Or in the status bar:

![Status bar mode switch][13]



[01]: /assets/activitybar-action.png
[02]: /releases/v6.0.0/local-server.png
[03]: /releases/v5.3.0/seo-status.png
[04]: /releases/v6.0.0/local-server-start.png
[05]: /docs/custom-actions
[06]: /assets/metadata.png
[07]: /docs/content-creation
[08]: /releases/v7.2.0/content-type-actions.png
[09]: /assets/recent-files.png
[10]: /docs/getting-started
[11]: /assets/other-actions.png
[12]: /releases/v7.1.0/panel-mode-switch.png
[13]: /releases/v7.1.0/status-bar-mode-switch.png

Editor panel

# 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][01]

## 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`).

> **Info**: You can make use of the placeholders available in Front Matter for 
> your commit messages. For example: `Synced by Front Matter {{hour24}}:{{minute}}`.


[01]: /releases/v8.1.0/git-integration.png

Git integration

# 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][01]



> **Sample**: [Generate open graph preview image in Code with Front Matter][02]

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

| Title          | Type                                    | Description                                                                                                                                                                                                                                                                                        | Default        |
| -------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `id`           | `string`                                | The id of the custom action/script                                                                                                                                                                                                                                                                 | `""`           |
| `title`        | `string`                                | The title of the custom action                                                                                                                                                                                                                                                                     | `""`           |
| `script`       | `string`                                | The path to the script to execute                                                                                                                                                                                                                                                                  | `""`           |
| `command`      | `string`                                | The command to execute (optional). Example: `node`, `path to your node executable`, `bash`, `python`, ...                                                                                                                                                                                          | `node`         |
| `type`         | `<content \| mediaFile \| mediaFolder>` | The type for which the script will be used (optional). <br /><br /> Use one of the following types: `content`, `mediaFile`, or `mediaFolder`.                                                                                                                                                      | `content`      |
| `bulk`         | `boolean`                               | Run the script for one file or multiple files.                                                                                                                                                                                                                                                     | `false`        |
| `output`       | `<notification \| editor`               | Specifies the output type (optional). <br /><br /> Available values are: `notification` and `editor`. <br /><br /> `notification`: The output will be passed as a notification. <br /> `editor`: The output will be passed to the editor.                                                          | `notification` |
| `outputType`   | `<text \| html>`                        | Specifies the output type (optional). <br /><br /> Available values the editor values from VS Code like: <br /><br /> `text`: The output will be passed as a text file. <br /> `html`: The output will be passed as an HTML file. <br /> `markdown`: The output will be passed as a Markdown file. | `text`         |
| `hidden`       | `boolean`                               | Hide the action from the UI. This is mostly used when creating a content script that will be used to post process new content (optional).                                                                                                                                                          | `false`        |
| `environments` | `environment`                           | The environments option allows you to specify in which environments the script should be executed (optional). <br /><br /> Available values are: `macos`, `linux`, or `windows`.                                                                                                                   | `undefined`    |

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

### Environment type

The environment option contains the following properties:

| Title     | Type                          | Description                                                                                               | Default |
| --------- | ----------------------------- | --------------------------------------------------------------------------------------------------------- | ------- |
| `type`    | `<macos \| linux \| windows>` | The environment type for the script to run at.                                                            | `""`    |
| `script`  | `string`                      | The path to the script to execute.                                                                        | `""`    |
| `command` | `string`                      | The command to execute (optional). Example: `node`, `path to your node executable`, `bash`, `python`, ... | `node`  |

#### Example of defining a custom action with an environment

```json
{
  "frontMatter.custom.scripts": [
    {
      "title": "Create image folder",
      "id": "create-image-folder",
      "script": "./.frontmatter/config/custom/scripts/create-image-folder.sh",
      "command": "bash",
      "environments": [
        {
          "type": "windows",
          "script": "./.frontmatter/config/custom/scripts/create-image-folder.ps1",
          "command": "powershell"
        }
      ]
    }
  ]
}
```

> **Info**: The above sample would execute the bash script on macOS and Linux and the PowerShell for
> Windows. In case the PowerShell script would fail, it would fallback to the bash script.

## 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][03]

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][04]

### 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][05]

### 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][06]

## 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`



[01]: /assets/custom-action.png
[02]: https://www.eliostruyf.com/generate-open-graph-preview-image-code-front-matter/
[03]: https://github.com/estruyf/vscode-front-matter/blob/HEAD/sample/script-sample.js
[04]: /assets/custom-action-output.png
[05]: /releases/v5.6.0/media-file-custom-script.png
[06]: /releases/v5.6.0/media-folder-custom-script.png

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][01].

### Eleventy

_Are you up for the challenge of writing this part of the documentation?_

[Update the docs][02]

### Gatsby

_Are you up for the challenge of writing this part of the documentation?_

[Update the docs][02]

### Next.js

_Are you up for the challenge of writing this part of the documentation?_

[Update the docs][02]

### SvelteKit

_Are you up for the challenge of writing this part of the documentation?_

[Update the docs][02]


### ...

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

[Update the docs][02]


[01]: /docs/ssg-and-frameworks/hugo-configuration
[02]: 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][01] in combination with the
> _beautifulhugo_ theme.

![Opening your Hugo project in VS Code][02]

## 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][03]

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][04]

## 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][05]

### 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][06]

### 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][07]

- 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][08]

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

![Content dashboard][09]

> **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][10]

## 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][11]


[01]: https://github.com/gohugoio/hugoBasicExample
[02]: /hugo-configuration/hugo-configuration1.png
[03]: /hugo-configuration/hugo-configuration2.png
[04]: /hugo-configuration/hugo-configuration3.png
[05]: /hugo-configuration/hugo-configuration4.png
[06]: /hugo-configuration/hugo-configuration5.png
[07]: /hugo-configuration/hugo-configuration6.png
[08]: /hugo-configuration/hugo-configuration7.png
[09]: /hugo-configuration/hugo-configuration8.png
[10]: /hugo-configuration/hugo-configuration9.png
[11]: /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][01]

> **Info**: Once a preview is opened, you will be able to manually change the URL. Something to note
> is that the URL will not be updated when navigating to other pages.

## 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`.

### Usage of placeholders

Since version `8.3.0`, the you can use placeholders in the `previewPath` property and there are a
couple of additional placeholders available which can be used for your preview paths.

> **Info**: You can find these placeholders in the [placeholders section](/docs/content-creation/placeholders#special-placeholders).

#### Usage of a placeholder

```json
"frontMatter.content.pageFolders": [
  {
    "title": "post",
    "filePrefix": null,
    "previewPath": "/{{fm.type}}/{{pathToken.3}}/{{pathToken.4}}",
    "path": "[[workspace]]/content/{{year}}/{{month}}",
    "contentTypes": ["post"]
  }
]
```

The preview path will generate the following path: `/post/2023/02/<slug>`.

#### Usage of a placeholder with the publishing date

```json
"frontMatter.content.pageFolders": [
  {
    "title": "post",
    "filePrefix": null,
    "previewPath": "'/{{fm.type}}/'yyyy",
    "contentTypes": ["post"]
  }
]
```

The preview path will generate the following path: `/post/2023/<slug>`.

### Configuration levels

#### 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"
    }
  ]
}
```

> **Info**: The `previewPath` property can contain

#### 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": [
      ...
    ]
  }
]
```



[01]: /releases/v8.3.0/site-preview.png

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][01]

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][02]

### 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][03]

## 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][04]

> **Info**: You can also use media snippets to insert your images. More information can be found in
> the [Media Snippets][05] 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][06]

## Front matter highlighting

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

![Highlighting][07]

> **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][08]


[01]: /releases/v5.7.0/wysiwyg_controls.png
[02]: /releases/v5.7.0/wysiwyg_headings.png
[03]: /releases/v5.7.0/wysiwyg_options.png
[04]: /releases/v4_0_0/insert-images.gif
[05]: /docs/snippets#media-snippets
[06]: /assets/folding.png
[07]: /assets/fm-highlight.png
[08]: /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][01]

## 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": "]]"
}
```

- `title`: A title for your snippet (optional);
- `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][02]).

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][03])
- `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][04]

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

![Fill in the snippet form][05]

- 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][06]

### 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"
      }
    ]
  }
}
```



[01]: /releases/v7.0.0/snippet-dashboard.png
[02]: /docs/content-creation/content-types#define-your-own-type
[03]: /docs/content-creation/placeholders
[04]: /releases/v7.0.0/insert-snippet.png
[05]: /releases/v7.0.0/insert-snippet-form.png
[06]: /releases/v7.3.0/media-snippets.png

Snippets


# Commands

## Overview

Front Matter actions can also be done using commands. This section of the documentation will
provide an explanation of all the available commands.

<img src="/assets/commands-v6.1.0.png" alt="Commands" style="max-width: 60%" />

Some of the commands do also have a default keyboard binding for quick access.

## Keyboard bindings

| Command                     | Description                           | Windows                                           | Mac                                              | Linux                                             |
| --------------------------- | ------------------------------------- | ------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------- |
| `frontMatter.dashboard`     | Open the Front Matter dashboard       | <kbd>alt</kbd> + d                                | <kbd>option</kbd> + d                            | <kbd>alt</kbd> + d                                |
| `frontMatter.insertMedia`   | Insert a media file into your content | <kbd>ctrl</kbd> + <kbd>shift</kbd> + <kbd>i</kbd> | <kbd>cmd</kbd> + <kbd>shift</kbd> + <kbd>i</kbd> | <kbd>ctrl</kbd> + <kbd>shift</kbd> + <kbd>i</kbd> |
| `frontMatter.insertSnippet` | Insert a snippet into your content    | <kbd>cmd</kbd> + <kbd>shift</kbd> + <kbd>v</kbd>  | <kbd>cmd</kbd> + <kbd>shift</kbd> + <kbd>v</kbd> | <kbd>cmd</kbd> + <kbd>shift</kbd> + <kbd>v</kbd>  |

## Using commands

- Start by opening the command prompt:
  - Linux & Windows: <kbd>shift</kbd> + <kbd>ctrl</kbd> + <kbd>P</kbd>
  - Mac: <kbd>shift</kbd> + <kbd>cmd</kbd> + <kbd>P</kbd>
- 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`

### Diagnostic logging

Opens a virtual Markdown document with detailed information about your Front Matter configuration.

ID: `frontMatter.diagnostics`

### Insert media into your content

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

ID: `frontMatter.insertMedia`

### 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][01]

## 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][02]

## Inspecting configuration behavior

With the [diagnostic logging][03] command, you can see your current configuration and related
information in a virtual Markdown document.

The document has several sections:

- **Folders** lists the entries defined in `frontMatter.content.pageFolders` by their title and the
  full path to each folder.
- **Workspace folder** notes the full path to your project's workspace.
- **Total files** notes the total file count for your workspace.
- **Folders to search files** lists the count for discovered files by type in your content folders
  and includes the search glob used.
- **Complete frontmatter.json config** shows the current configuration JSON. If you
  [split your configuration settings][04], it
  shows the fully composed configuration.

## 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][05] 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.



[01]: /releases/v5.8.0/troubleshooting.png
[02]: /releases/v5.8.0/troubleshooting-output.png
[03]: /docs/commands#diagnostic-logging
[04]: /docs/settings#splitting-your-settings-in-multiple-files
[05]: /docs/content-creation/content-types#changing-the-default-content-type

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][01]

## 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.

> **Important**: The configuration of the `frontmatter.json` file will override the settings which
> you might have splitted.

### Supported settings to split

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

| Setting name                        | Folder path                                    | JSON Schema                                                          |
| ----------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------- |
| `frontMatter.content.pageFolders`   | `./.frontmatter/config/content/pagefolders/`   | `https://frontmatter.codes/config/content.pagefolders.schema.json`   |
| `frontMatter.content.placeholders`  | `./.frontmatter/config/content/placeholders/`  | `https://frontmatter.codes/config/content.placeholders.schema.json`  |
| `frontMatter.content.snippets`      | `./.frontmatter/config/content/snippets/`      | `https://frontmatter.codes/config/content.snippets.schema.json`      |
| `frontMatter.custom.scripts`        | `./.frontmatter/config/custom/scripts/`        | `https://frontmatter.codes/config/custom.scripts.schema.json`        |
| `frontMatter.data.files`            | `./.frontmatter/config/data/files/`            | `https://frontmatter.codes/config/data.files.schema.json`            |
| `frontMatter.data.folders`          | `./.frontmatter/config/data/folders/`          | `https://frontmatter.codes/config/data.folders.schema.json`          |
| `frontMatter.data.types`            | `./.frontmatter/config/data/types/`            | `https://frontmatter.codes/config/data.types.schema.json`            |
| `frontMatter.taxonomy.contentTypes` | `./.frontmatter/config/taxonomy/contenttypes/` | `https://frontmatter.codes/config/taxonomy.contenttypes.schema.json` |
| `frontMatter.taxonomy.fieldGroups`  | `./.frontmatter/config/taxonomy/fieldgroups/`  | `https://frontmatter.codes/config/taxonomy.fieldgroups.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.

You can use the JSON schema to validate and get intellisense for the settings. Use it as follows:

```json
{
  "$schema": "https://frontmatter.codes/config/content.pagefolders.schema.json"
}
```

### Example of splitting a setting

#### Example 1: Specify a blog page folder

Example of specifying a page folder in a separate file:

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

Contents of the `blog.json` file:

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

#### Example 2: Specify a custom data type

You are also able to define sub-folders for your settings, that way, you can easily group your
settings. For example, in this case we'll create a `baz` data type in its own folder.

```markdown
| .frontmatter
| - config
| -- data
| --- types
| ---- bar
| ----- baz.json
```

Contents of the `baz.json` file:

```json
{
  "$schema": "https://frontmatter.codes/config/data.types.schema.json",
  "id": "hugo.params.baz",
  "schema": {
    "title": "Baz Site Parameters for hugo-toroidal",
    "type": "object",
    "properties": {
      "First": {
        "title": "First Property",
        "description": "First Baz",
        "type": "string",
        "default": ""
      }
    }
  }
}
```

## Extending settings

You can extend the settings of Front Matter by using the `frontMatter.extends` setting. This allows 
you to extend the settings from a custom local or remote location. This can be useful if you want to 
share a common set of settings across multiple projects.

### Example

```json
{
  "$schema": "https://frontmatter.codes/frontmatter.schema.json",
  "frontMatter.extends": [
    "https://platen.io/frontmatter/platen.json",
     "./config/frontmatter.config.json"
  ],
  ...
}
```

## Reviewing composed settings

You can inspect your composed settings with the [diagnostic logging][02] command, which shows you
the [Complete frontmatter.json config][03] in a virtual Markdown document. Use that output to verify
that your split configuration settings are applied the way you expect.




[01]: /releases/v5.0.0/ask-to-promote-settings.png
[02]: /docs/commands#diagnostic-logging
[03]: /docs/troubleshooting#inspecting-configuration-behavior

Settings

# Settings overview

Here you can find an overview of all available settings. 

## 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][04]

### 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][05]

### 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. You can also make use of placeholder to generate dynamic paths. | `""`    | 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][06] section to learn more.                              |         | Optional            |
| `filePrefix`    | `string`   | Defines a prefix for the file name.                                                                                                                  |         | Optional            |
| `contentTypes`  | `string[]` | An array of content types to use for this folder. If not specified, all content types are used.                                                      |         | 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"
    },
    {
      "title": "docs",
      "path": "[[workspace]]/docs",
      "filePrefix": "",
      "contentTypes": ["doc"]
    }
  ]
}
```

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

> **Info**: More information on how you can use it can be found here: [placeholders][07].

### 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: `""`

In case you are using Hexo in combinations with the [asset folders](https://hexo.io/docs/asset-folders), you can use the following settings:

- `source/images`: If you want to use the default image location of Hexo;
- `hexo:post_asset_folder`: If you want to use the post asset folder functionality.

### 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][08] 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][09] section for more information.

### frontMatter.dashboard.content.pagination

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

- Type: `boolean` or `number`
- Default: `true`
- Maximum: `52`

### 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][10] 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][10] 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][10] section.

### frontMatter.experimental

Specify if you want to enable the experimental features.

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

> **Info**: More information on how to use it can be found in the [experimental features][02] section.

### frontMatter.extends

Specify the list of paths/URLs to extend the Front Matter CMS config.

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

> **Info**: More information on how to use it can be found in the [extending settings][01] section.

### frontMatter.file.preserveCasing

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

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

> **Info**: More information on how to use it can be found in the
> [preserve the casing for your file names][11] 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][12] 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][12] 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][13]

### 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][14] section for more information.

### frontMatter.taxonomy.dateFormat

Specify the date format for your articles. Check [date-fns formating][15] 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][16] 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.seoTitleField

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

- Type: `string`
- Default: `title`

### 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.



[01]: /docs/settings#extending-settings
[02]: /docs/experimental
[04]: /docs/content-creation#before-you-start
[05]: /releases/v8.1.0/hide-fm.png
[06]: /docs/site-preview#configuration
[07]: /docs/content-creation/placeholders
[08]: /docs/custom-actions
[09]: /docs/dashboard#card-tags
[10]: /docs/dashboard#data-files-view
[11]: /docs/content-creation/additional-config#preserve-casing-of-file-names
[12]: /docs/panel#define-view-modes
[13]: /docs/content-creation/content-types#changing-the-default-content-type
[14]: /docs/content-creation/fields#taxonomy
[15]: https://date-fns.org/v2.0.1/docs/format
[16]: /docs/content-creation/fields#block

Experimental features

Enable experimental features

Visual Studio Code theme support

Feedback/comments

Ready to get started?