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

Currently the following experimental features are available:

- External UI scripts
- Front matter AI (only available for GitHub sponsors)


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.

<div class="iframe__wrapper">
  <iframe 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>
</div>

## 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 2.1 (optional): Use a template

For some of the static-site generators, Front Matter CMS has created some templates to get you
started. You can select one of the templates from the list of available templates.

![Front Matter CMS - Starter Templates][13]

> **Info**: The templates are stored in the
> [Front Matter CMS - Starter Templates][12] repository.

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

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.

## Front Matter AI Assistant

If you have a question on how you can configure Front Matter CMS, you can use the AI Assistant to
get some help. The AI Assistant is available via the
`Front Matter: Ask the Front Matter AI for help` command or via the chatbot icon in the
Front Matter CMS panel or when the `frontmatter.json` file is opened.

![Front Matter AI Assistent](/releases/v8.4.0/front-matter-ai-assisten.png)

When you run the command, or click on the chatbot icon, the AI Assistant will open and you can
start typing your question.

![Front Matter AI Assistent](/releases/v8.4.0/front-matter-ai-assistent.png)

## 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
[12]: https://github.com/frontmatter/templates
[13]: /releases/v9.2.0/templates.png

Getting started

# Content creation

## Overview

<div class="iframe__wrapper">
   <iframe src="https://www.youtube.com/embed/oA5ocNaiAtY" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>

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                                                                                                                                           | `""`          |
| `clearEmpty`      | `boolean`                                | Clears the fields from the front matter section if empty                                                                                                           | `false`       |
| `defaultFileName` | `string`                                 | Default file name to use when creating new content                                                                                                                 | `index`       |
| `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`          |
| `pageBundle`      | `boolean`                                | If set to true, the content will be created as a page bundle (folder)                                                                                              | `false`       |
| `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`        |
| `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`        |

## 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 {{ "title": "Using the special placeholders", "description": "" }}
"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 {{ "title": "Using the relative path token", "description": "" }}
"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/`.

### Example 3: using field formatting

In case of using the `{{fm.<field name>}}` placeholder, you can also use field formatting. Here is
an example of how you can use field formatting:

```json {{ "title": "Using field formatting", "description": "" }}
"frontMatter.content.pageFolders": [
  {
    "title": "blog",
    "filePrefix": null,
    "previewPath": "'/{{fm.type}}/{{fm.pubDate|format:dd/MM/yy}}/'",
    "path": "[[workspace]]/content"
  }
]
```

The above configuration results in the following path: `/blog/25/02/23/`.

![Placeholder field formatting](/releases/v9.0.0/placeholder-formatting.png)

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

The contents view is the default view when you open the dashboard. It will show you all the pages in
your project, and allow you to filter and sort them.

## Card configuration

### Card field configuration

If you want to change the fields/values that are shown on the content card, you can do so by using
the following settings:


| Setting | Description | Default |
| --- | --- | --- |
| `frontMatter.dashboard.content.card.fields.title` | The field name to use for the title. | `""` |
| `frontMatter.dashboard.content.card.fields.description` | The field name to use for the description. | `""` |
| `frontMatter.dashboard.content.card.fields.state` | Show/hide the state/draft status. Set to `false` to hide it. | `true` |
| `frontMatter.dashboard.content.card.fields.date` | Show/hide the date. Set to `false` to hide it. | `true` |


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

### Card UI extensibility

In case you want to take more control over the card UI, you can add your own custom code by using
our extensibility library. More information about this can be found in the [UI extensibility][06]
section.

## 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
[06]: /docs/experimental/ui-extensibility#registering-a-custom-ui-extension

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/database/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.


### Defining a data schema

The `schema` property is used to define the structure of the data file. The schema is defined using
the [JSON Schema][03] standard.

The following example shows a schema for a sponsor object:

```json
{
  "title": "Sponsors",
  "type": "object",
  "required": [
    "name",
    "url"
  ],
  "properties": {
    "name": {
      "type": "string",
      "title": "Name"
    },
    "url": {
      "type": "string",
      "title": "URL"
    },
    "description": {
      "type": "string",
      "title": "Description",
      "multiline": true
    }
  }
}
```

#### Field types

The following field types are supported:

- `string`
- `number`
- `boolean`
- `array`
- `object`

When you are using the `string` type, you can use the `multiline` property to define if the field is
a multiline field.

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

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

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



> **Important**: By default, the global settings section is hidden, you need to create a view mode 
> which holds the `panel.globalSettings` panel ID to show it.

> **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. You can also change the start command in the 
> [frontMatter.framework.startCommand][14] setting.

## 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.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-updated.png
[13]: /releases/v7.1.0/status-bar-mode-switch.png
[14]: /docs/settings/overview#frontmatter.framework.startcommand

Editor panel


# Sponsor features

## Front Matter AI

As a sponsor, you can use the Front Matter AI to let an AI help you with
title and tag/categories suggestions.

As using an AI is not free, we have limited this feature to sponsors only and
also because we want to keep the default behaviour of Front Matter CMS without
any API needs.

To use the Front Matter AI as a sponsor, you will have to perform the following
steps:

1. Make sure you are logged in to Front Matter CMS with GitHub. You can find more
information about this in the [backers & sponsors][01]
section.
2. Enable the Front Matter AI in the settings. You can do this, by setting
the `frontMatter.sponsors.ai.enabled` setting to `true`.

### Title suggestions

When the Front Matter AI is enabled, on the creation of new content, you will be asked for
a title or description. Once provided, you will get a list of suggestions for the title and
you also get your own input as a suggestion as well.

![Front Matter AI - Title suggestions](/releases/v8.4.0/front-matter-ai-suggestions.png)

### Tags/categories suggestions

Similar to the title suggestions, you will also get suggestions for tags and categories.

On the tags or categories field, you will get a new icon, when you click on it, it will fetch
suggestions based on the title and description of the content.

![Front Matter AI - Tag suggestions](/releases/v8.4.0/front-matter-ai-tags.png)

### Description suggestions

When you have provided a title and content, the Front Matter AI can help you providing a description
for you article. This can be useful when you want to share your content on social media.

![AI Description Suggestion](/releases/v9.0.0/description-ai-suggestion.png)

## Becoming a sponsor

If you're not already a sponsor, now is a great time to consider supporting the project.
By becoming a sponsor, you not only gain access to exclusive features like Front Matter AI,
but also help to support the ongoing development and maintenance of the project.
You can become a sponsor by visiting the
[GitHub sponsor page][02].

## Internals of the Front Matter AI

The Front Matter AI is powered by [OpenAI](https://openai.com/) and the code for the AI is also
open source and available on [GitHub][03].

![Front Matter AI - Architecture](/releases/v8.4.0/front-matter-ai-architecture.png)

We believe in transparency and that is why we are sharing the code for the AI, so that you can see
how it works and what it does.

The GitHub user token (with only _read_ access) is used to retrieve your username,
as we need to make sure you are allowed to use the AI.

[01]: /docs/getting-started#backers-&-sponsors
[02]: https://github.com/sponsors/estruyf
[03]: https://github.com/FrontMatter/web-documentation-nextjs/blob/main/pages/api/ai


Sponsor features

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

## Git submodules

If you are using git submodules for managing your content, you have more control over them via the
following settings:

| Setting | Description | Default |
| --- | --- | --- |
| `frontMatter.git.submodule.push` | Whether to push the submodule changes to the remote repository. | `false` |
| `frontMatter.git.submodule.pull` | Whether to pull the submodule changes from the remote repository. | `false` |
| `frontMatter.git.submodule.branch` | The branch to use for the submodule. | `` |
| `frontMatter.git.submodule.folder` | The folder where the submodule is located. | `` |


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

Git integration

# Custom actions

## Overview

<div class="iframe__wrapper">
  <iframe src="https://www.youtube.com/embed/wvH9Tn5LQ2c" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>

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

### Astro

To use Front Matter with Astro, you can check out the following guide on the Astro website:
[Front Matter CMS & Astro][03]

### Hugo

Check out our Hugo configuration documentation to get you started using Front Matter:
[Front Matter configuration with Hugo][01].

### Next.js

Check out our Next.js configuration documentation to get you started using Front Matter: [Front Matter configuration with Next.js][04].

### Other static site generators

In case you are using a static site generator which is not listed here, feel free to reach out
to us to check how we can help you configure Front Matter CMS in your project.

You can help us by adding the documentation for your static site generator to this documentation.

[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
[03]: https://docs.astro.build/en/guides/cms/frontmatter-cms/
[04]: /docs/ssg-and-frameworks/nextjs-configuration

Static Site Generators

# Astro Configuration

Astro is the all-in-one web framework designed for speed. Pull your content from anywhere
and deploy everywhere, all powered by your favorite UI components and libraries.

Front Matter CMS is a great companion to Astro and we added a
start guide on the Astro documentation site: [Front Matter CMS & Astro][01].


[01]: https://docs.astro.build/en/guides/cms/frontmatter-cms/

Astro Configuration

# 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


# Next.js Configuration

## Creating the Next.js project

For the Next.js project configuration, the documentation makes use of the official
[blog starter kit](https://vercel.com/templates/next.js/blog-starter-kit).

If you want to start by creating a new blog, you can use the following command:

```bash
npx create-next-app --example blog-starter <your-project-name>
```

> **Info**: In case you already have a Next.js project, you can follow the steps below
> to configure Front Matter CMS.

## Installing Front Matter

You can get the extension from the [Visual Studio Code Marketplace - Front Matter](https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-front-matter)
or by clicking on the following link: [open Front Matter CMS extension in VS Code](vscode:extension/eliostruyf.vscode-front-matter).

## Initializing Front Matter

Once Front Matter CMS is installed, you will get a new icon in the Activity Bar.
When you click on it, it will open the Front Matter CMS panel in the primary sidebar.
Follow the next steps to initialize your project:

- Click on the Initialize project button in the Front Matter panel
- The welcome screen will open, and you can start initializing the project
- Click on the first step to **Initialize project**
- As Next.js is one of the supported frameworks, it will be selected by default
- Register the content folder by clicking on the `_posts` folder
  - Front Matter will ask you for the collection name, which can be renamed to `posts`
- If you have articles with tags and/or categories, you can click on the import action
- Once the initialization is completed, you can click on the **Open Dashboard** button to open the dashboard

![Content dashboard of the Next.js project](/nextjs-configuration/nextjs-dashboard.png)

## Project configuration

Once the project is initialized, you will get a `frontmatter.json` configuration file
and a `.frontmatter` folder in the root of your project.

```bash
| _posts/
| .frontmatter/
| - database
| -- taxonomyDb.json
| ...
| frontmatter.json
| package.json
```

## Content-type configuration

> **Important**: The following steps are only required if you want to use the blog starter kit is
> structure and metadata. If you want to use your own structure, you can skip this step or configure
> it to your needs.

Start by opening one of the markdown files shown on the dashboard. Once opened, you can see the
SEO status, actions, and metadata of the content.

In the **metadata** section, you will notice that the content type has some missing fields.
Follow the next steps to fix this:

- Click on the **create content-type** button

![Create content-type button](/nextjs-configuration/create-content-type.png)

- Select **yes** to overwrite the existing content-type. Once completed, you can see an update to
the metadata section.

![Content-type configuration](/nextjs-configuration/content-type-configuration.png)

- Sometimes, more configuration might be required. In that case, you can manually open the
`frontmatter.json` file and update the configuration. Which we will do for the image
field in the `author` and `ogImage` fields.
- In the `frontmatter.json` file, you can find the `frontMatter.taxonomy.contentTypes`, which has
a **default** content-type configured with the fields of the blog starter kit.
- Add the `isPreviewImage` property to the `coverImage` field and set its value to `true`
- Update the `picture` field of the `author` from `string` to `image`
- Update the `ogImage` field from `string` to `image`

Once you have updated the configuration, you can go back to the markdown file and see the changes
in the metadata section.

![Updated content-type configuration](/nextjs-configuration/updated-content-type-configuration.png)

Here you can see the updated configuration:

```json
{
  "frontMatter.taxonomy.contentTypes": [
    {
      "name": "default",
      "pageBundle": false,
      "previewPath": null,
      "fields": [
        {
          "title": "title",
          "name": "title",
          "type": "string"
        },
        {
          "title": "excerpt",
          "name": "excerpt",
          "type": "string"
        },
        {
          "title": "coverImage",
          "name": "coverImage",
          "type": "image",
          "isPreviewImage": true
        },
        {
          "title": "date",
          "name": "date",
          "type": "datetime"
        },
        {
          "title": "author",
          "name": "author",
          "type": "fields",
          "fields": [
            {
              "title": "name",
              "name": "name",
              "type": "string"
            },
            {
              "title": "picture",
              "name": "picture",
              "type": "image"
            }
          ]
        },
        {
          "title": "ogImage",
          "name": "ogImage",
          "type": "fields",
          "fields": [
            {
              "title": "url",
              "name": "url",
              "type": "image"
            }
          ]
        }
      ]
    }
  ]
}
```

When the configuration is completed, you can see the cover images being used on the content
dashboard of Front Matter.

![Content dashboard with cover images](/nextjs-configuration/content-dashboard-with-cover-images.png)

> **Info**: If the cover images are not showing up, you can try to clear the cache of Front Matter
> by running the `Front Matter: Clear cache` command.

## You are all set

You have successfully configured Front Matter CMS for your Next.js project. You can now start
creating content and managing your website via Front Matter CMS.


Next.js 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 want 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": [
      ...
    ]
  }
]
```

### Open on the website

With the `frontMatter.website.host` setting, you can specify the host of your website. Once the
setting is configured, you can click on the `Open on website` button to open the current page on
your website.

> **Info**: The `frontMatter.website.host` setting can be configured in the `frontmatter.json` file.



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

<div class="iframe__wrapper">
   <iframe src="https://www.youtube.com/embed/0J-StFyEbV0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>

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

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

### Snippet wrapper

The snippet wrapper functionality automatically wraps the inserted snippet in your content with the
inserted data.

For instance, in the above example, the following wrapper is added:


```html

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

```


> **Important**: The wrapper can be disabled with the `frontMatter.snippets.wrapper.enabled` setting. By default, it
is enabled.

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

### Refresh the settings

This command allows you to refresh the settings from the `frontmatter.json` file. This is useful
when you have updated the settings manually and want to reload them.

ID: `frontMatter.settings.refresh`

## Removed commands

### Set current date

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

ID: `frontMatter.setDate`


Commands


# UI extensibility

As every user has different needs, the Front Matter extension allows you to extend the UI with your
own custom elements and components which can be used in the Front Matter dashboards and the panel.

The approach we choose, is to let you register a JavaScript file which will be loaded in the
dashboard and panel.

## Extensibility points

Front Matter CMS allows you to extend the UI in the following places:

- Content dashboard
  - Image
  - Footer
  - Draft status
  - Date
  - Title
  - Description
  - Tags

- Panel
  - Custom panel view
  - Custom fields

## Registering a custom UI extension

To start, you will need to create a JavaScript. To make it easier, you need to make use of the
[@frontmatter/extensibility][01] dependency which makes all the necessary functions available.

```js {{ "title": "Using the @frontmatter/extensibility dependency", "description": "" }}
import {
  enableDevelopmentMode,
  registerCardImage,
  registerCardFooter,
  registerPanelView,
  registerCustomField
} from "https://cdn.jsdelivr.net/npm/@frontmatter/extensibility/+esm";
```

Once you have created the JavaScript file, you can register your UI script in
the `frontMatter.extensibility.scripts` setting as follows:

```json {{ "title": "Registering a custom UI extension", "description": "" }}
{
  "frontMatter.extensibility.scripts": [
    "[[workspace]]/.frontmatter/ui/external.js"
  ]
}
```

## The extensibility framework options

### Development mode

To enable development mode, you can use the `enableDevelopmentMode` function. This will allow you to
reload the webview and open the developer tools without the need to reload Visual Studio Code.

```js {{ "title": "Enabling development mode", "description": "" }}
enableDevelopmentMode();
```

Once the development mode is enabled, you will see the developer bar at the top of the webview.

![Developer mode enabled](/releases/v8.4.0/developer-mode.png)

### Registering a card image

To register a custom card image, you can use the `registerCardImage` function. This functionality
allows you to register your own image/element on the content card.

```js {{ "title": "Registering a card image", "description": "" }}
registerCardImage(async (filePath, metadata) => {
  return `<span>Your HTML for the card image</span>`;
});
```

- The `filePath` parameter contains the path to the file which is being rendered in the card.
- The `metadata` parameter contains the metadata (front matter) of the file which is
being rendered in the card.
  - On this metadata object, you can find the `fmPreviewImage` property which contains the webview
  URL of the current project. You can use this property to render your own image located in the
  project.

Example of a custom image rendering:

![Custom card image](/releases/v8.4.0/custom-card-image.png)

Example of using the `fmPreviewImage` property:

```js {{ "title": "Using the fmPreviewImage property", "description": "" }}
import { registerCardImage, enableDevelopmentMode } from "https://cdn.jsdelivr.net/npm/@frontmatter/extensibility/+esm";
enableDevelopmentMode();

/**
 * @param {string} filePath - The path of the file
 * @param {object} data - The metadata of the file
 * @returns {string} - The HTML to be rendered in the card footer
 */
registerCardImage(async (filePath, metadata) => {
    const image = metadata.fmPreviewImage ? metadata.fmPreviewImage : `${metadata.fmWebviewUrl}/relPath/to/fallback.jpg`;
    return `<img src="${image}" alt="${metadata.title}" style="object-fit: cover;" class="h-36" />`;
});
```

### Registering a card footer

To register a custom card footer, you can use the `registerCardFooter` function. This functionality
allows you to register your own footer/element which will be rendered at the bottom of the content.

```js {{ "title": "Registering a card footer", "description": "" }}
registerCardFooter(async (filePath, metadata) => {
  return `<span>Your HTML for the card footer</span>`;
});
```

Example of a custom footer rendering:

![Custom card footer](/releases/v8.4.0/custom-card-footer.png)

### Registering a panel view

To register a custom panel view, you can use the `registerPanelView` function. This functionality
allows you to register your own panel view which will be rendered in the panel.

```js {{ "title": "Registering a panel view", "description": "" }}
registerPanelView(async (metadata) => {
  return {
    title: "Custom View",
    content: `
      <div>
        <h1>Custom view...</h1>
        <p>Here you can add your own custom view.</p>
      </div>
    `,
  };
});
```

Example of a custom panel view rendering:

![Custom panel view](/releases/v8.4.0/custom-panel-view.png)

### Registering a custom field

To register a custom field, you can use the `registerCustomField` function. This functionality
allows you to register your own custom field which can be used when editing the front matter.

The custom field requires a bit more work, as it comes with a change handler for the field value
updates. To make it easier, it is recommended to use for instance a library like [lit][02] to
create your custom field.

```js {{ "title": "Registering a custom field", "description": "" }}
import { registerCustomField } from "https://cdn.jsdelivr.net/npm/@frontmatter/extensibility/+esm";
import { css, html, LitElement } from "https://esm.run/lit";

let CustomFieldValueChange;

class CustomField extends LitElement {
  static styles = css`
    input {
      border: 1px solid transparent;
      box-sizing: border-box;
      font-family: var(--vscode-font-family);
      padding: var(--input-padding-vertical) var(--input-padding-horizontal);
      color: var(--vscode-input-foreground);
      outline: none;
      background-color: var(--vscode-input-background);
      width: 100%;
    }

    input:focus {
      border: 1px solid var(--vscode-inputValidation-infoBorder);
    }
  `;

  static properties = {
    inputValue: {
      type: String,
    },
  };

  constructor() {
    super();
    this.inputValue = "";
  }

  _internalChange(e) {
    this.inputValue = e.target.value;
    CustomFieldValueChange(e.target.value);
  }

  render() {
    return html`
      <input
        type="text"
        value="${this.inputValue}"
        @change=${(e) => this._internalChange(e)}
      />
    `;
  }
}
customElements.define("custom-field", CustomField);

/**
 * @param {string} name - The name of the custom field to use in the content-type
 * @param {function} callback - The callback that will be used for rendering the
 * custom field
 */
registerCustomField("customTextField", async (value, onChange) => {
  // Bind the event handler for the onChange evet
  CustomFieldValueChange = onChange;
  // Return the HTML of the custom field
  return `
    <custom-field inputValue="${value || ""}"></custom-field>
  `;
});
```

Once this script has been registered, you can use the `customField` type in your content-type.
Register it as follows:

```json {{ "title": "Configure your custom field in the content-type" }}
{
  "frontMatter.taxonomy.contentTypes": [{
    "name": "default",
    "pageBundle": false,
    "fields": [
      ...
      {
        "title": "Custom field",
        "name": "customField",
        "type": "customField",
        "customType": "customTextField"
      }
    ]
  }]
}
```

Example of a custom field rendering:

![Custom field](/releases/v8.4.0/custom-field.png)

[01]: https://www.npmjs.com/package/@frontmatter/extensibility
[02]: https://lit.dev/


UI extensibility in the Front Matter extension.

UI extensibility

# 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


# Projects

Projects are useful when managing multiple sites or when you want to separate your content
into different environments. For instance, when you are using Front Matter in a monorepo with
multiple sites, you can use projects to define the settings per site.

## Overview

For instance, you have the following structure:

```bash
├── websites
│   ├── blog
│   ├── portfolio
└── frontmatter.json
```

In this case, there are two sites to be managed, one for the `blog`
and one for the `portfolio` site. When you would not have the projects feature,
both of the sites would share the same settings. This is not always desirable,
as that can lead to issues for instance with the media paths.

That is why you can use projects to define the settings per site.

## Project configuration

The way our project configuration works is that each project inherits the settings
which are globally defined and per project you can override the settings.

For instance, if you have the following configuration:

```json
{
  "frontMatter.projects": [
    {
      "name": "blog",
      "default": true,
      "configuration": {
        "frontMatter.content.pageFolders": [{
          "title": "Blog posts",
          "path": "[[workspace]]/websites/blog/posts"
        }],
        "frontMatter.content.publicFolder": "[[workspace]]/websites/blog/public"
      }
    },
    {
      "name": "portfolio",
      "configuration": {
        "frontMatter.content.pageFolders": [{
          "title": "Portfolio",
          "path": "[[workspace]]/websites/portfolio/content"
        }],
        "frontMatter.content.publicFolder": "[[workspace]]/websites/portfolio/public"
      }
    }
  ]
}
```

You can only have one project as the default project. This is the project will be loaded
when you open the Front Matter CMS - dashboard. When you switch between projects, all
the settings will be reloaded, but also the last used project will be remembered.

> **Important**: In the `configuration` object, you can use all of the Front Matter CMS - settings.
Be aware that it overrides what has been defined on global level. It will not merge the settings.

## Switching projects

You can switch between projects by using the **Front Matter: Switch project** command, using the
panel project switch action, or the project dropdown on the dashboard.

![Project switching](/releases/v8.4.0/project-support.png)


Projects are useful when managing multiple sites or when you want to separate your content into different environments.

Projects

Settings overview


# Contributing to Front Matter CMS

There are many ways you can contribute to Front Matter CMS. You can help us by:

- Reporting bugs
- Suggesting new features
- Improving the documentation
- Improving the code
- Translating the extension
- Spreading the word ❤️

## Reporting bugs and suggesting new features

If you find a bug or have an idea for a new feature,
please create an issue in the [GitHub repository][01].

## Improving the documentation

If you find a typo or want to improve the documentation,
you can do so by editing the documentation directly on GitHub.

The source of the documentation can be found in the [GitHub repository][02].

## Improving the code

If you want to improve the code, you can do so by creating a pull request.

The source code of the extension can be found in the [GitHub repository][03].

## Translating the extension

If you want to help us translate the extension to your language, you best follow these steps:

1. Fork the [GitHub repository][03]
1. Create a new `bundle.<language>.json` file in the `l10n` folder
1. Create a new `package.nls.<language>.json` file in root
1. Run the `npm run localization:sync` command, this will automatically fill the new files
with the default values
1. Translate all values prefixed with `🚧:`
1. Once the translation is done, create a pull request and we will review it

> **Important**: you can only add translations for languages that are
> supported by Visual Studio Code. Check the [available locales][04] for more information.

[01]: https://github.com/estruyf/vscode-front-matter/issues
[02]: https://github.com/FrontMatter/web-documentation-nextjs
[03]: https://github.com/estruyf/vscode-front-matter
[04]: https://code.visualstudio.com/docs/getstarted/locales#_available-locales


Experimental features

Enable experimental features

Feedback/comments

Ready to get started?