
# 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

# Introduction

## Overview

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

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

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

Our main extension features are:

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

![Site preview][02]

## Why Front Matter?

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

## Advantages

We believe that Front Matter gives you the subsequent advantages:

### Speed

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

### Use it within Visual Studio Code

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

### Customizable

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

### Extensibility

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

> **Example**:
> [Generate open graph preview image in Code with Front Matter][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.

## 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
> uninstall the main version before installing the beta version.

## Welcome screen

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

![Welcome screen to configure your website][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, a `.frontmatter/templates` folder and `article.md` file template will be created in
the current project.

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

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

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

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

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

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

![Content folders][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**: Be default, the extension will include content from the current folder and its
> sub-folders. If you wish to exclude the sub-folders, you can do this by updating the
> [frontMatter.content.pageFolders][07] configuration setting and specifying the `excludeSubDir`
> property with the value as `true`.

## Workspaces with multiple folders

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

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

![Select your workspace folder for Front Matter][08]

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

## Backers & supporters

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

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

![Support links shown by default][09]

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

![Hidden support links][10]

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

![Sign in with GitHub for Front Matter][11]

Follow the proposed steps from Visual Studio Code.

## Enjoy using Front Matter

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


[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#frontmatter.content.pagefolders
[08]: /releases/v5.0.0/workspace-folder.png
[09]: /releases/v6.0.0/support-links.png
[10]: /releases/v6.0.0/support-links-hidden.png
[11]: /releases/v6.0.0/signin-github.png

Getting started

# Content creation

## Overview

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

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

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

## Before you start

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

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

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

## How it works

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

Our default content type consists of the following fields:

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

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

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

![Default content type fields][01]


[01]: /assets/default-contenttype.png

Content creation

# Content types

## Changing the default content type

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

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

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

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

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

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

![Adapted default content type fields][01]

### Content type properties

For the content type you can configure the following properties:

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

## Define your own type

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

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

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

Sample:

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

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

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

> **Fields**: Check out the [fields][05] section to learn which fields are supported.

## Using a template with the content type

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

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

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

## Run a script after your content is created

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

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

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

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

> **Info**: More information about custom scripts can be found in the
> [custom actions][06] section.

## Link to content folders

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

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


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

Content types

Fields

# Placeholders

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

There are known placeholders from Front Matter:

- `{{title}}`: Title of the page
- `{{slug}}`: Slug of the page
- `{{now}}`: Current date formatted with the value defined in `frontMatter.taxonomy.dateFormat` or
  ISO string
- `{{year}}`: Current year
- `{{month}}`: Current month
- `{{day}}`: Current day
- `{{hour12}}`: Current hour in 12-hour format
- `{{hour24}}`: Current hour in 24-hour format
- `{{ampm}}`: Show AM/PM
- `{{minute}}`: Current minute

## 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. You can change this in your `frontMatter.content.pageFolders` setting by adding the `filePrefix` property to your page folder.

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

## Page and leaf bundles

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

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

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

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

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

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

## Creating a template

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

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

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

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

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

## Preserve casing of file names

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

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

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


Additional configuration

# Dashboard

## Overview

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

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

![Dashboard - Contents view][01]

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

![Dashboard - Media view][02]

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

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

## Commands

There are the following commands to open the dashboards:

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


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

Dashboard

# Contents view

## Card tags

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

![Card tags][01]

## Draft status navigation

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

![Draft filters][02]

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

> **Info**: [Set a custom draft field][03].

![Draft filters][04]

## Supported filters

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

## Supported sorting

- Last modified
- Filename (asc/desc)

> **Info**: You can define custom sorting options by specifying these within the
> [frontMatter.content.sorting][05] setting.

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

## Show on startup

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

## Content pagination

By default, the content is paginated by 16 items. If you want, you can disable the pagination by
setting the `frontMatter.dashboard.content.pagination` setting to `false`. In case you want to change the number of items per page, you can specify a number in the same setting.


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

Content view

# Media view

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

![Dashboard - Media view - Lightbox][01]

## Supported files

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

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

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

## Media actions

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

### Setting metadata

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

![Dashboard - Setting metadata][02]


> **Info**: Check the [Insert images section][03] for more information.

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


### Deleting a media file

![Dashboard - Delete media file][04]

### Custom media actions

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

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

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

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

> **Info**: Check out [creating media scripts][05] for more information.

## Drag and Drop

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

![Dashboard - Upload media file][06]


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

Media view

# Data files view

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

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

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

![Data files dashboard][01]

## Configuration

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

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

## Creating a data file

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

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

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

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

![Data dashboard - Sponsor example][02]


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

> **Important**: In the `schema` property we use the [JSON Schema][03] standard to define the
> structure of the data file.

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

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

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

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

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

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

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



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

Data files view

# Taxonomies view

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

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

![Taxonomies view][01]

## Actions

![Taxonomy actions][02]

You can perform the following actions on the taxonomies view:

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


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

Taxonomy view

# Editor panel

## Overview

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

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

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

## Using the panel

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

![Activity bar action][01]

## Global settings

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

![Global settings][02]


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

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

## SEO status

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

Supports the following:

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

![SEO][03]

### Settings

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

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

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

## Actions

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

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

![Actions][04]

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

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

### Settings

The following settings are related to these actions:

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

## Metadata

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

![Metadata section][06]

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

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

### Content type actions

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

![Content type actions][08]

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

### Settings

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

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

![Recently modified][09]

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

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

## Other actions

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

![Other actions][11]

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

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

## View modes

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

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

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

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

### Panel

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

### Dashboards

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

Here is an example of a custom view mode:

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

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

![Switch view mode][12]

Or in the status bar:

![Status bar mode switch][13]


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

Editor panel

# GIT Integration

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

![Sync your changes with GIT][01]

## Enable GIT integration

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

## Change the commit message

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

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


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

Git integration

# Custom actions

## Overview

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

![Custom action][01]


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

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

## The custom action setting

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

Custom actions can be configured with the following properties:

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

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

## Creating a content script

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

```javascript
const arguments = process.argv;

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

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

> **Info**: The sample script can be found here [sample-script.js][03]

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

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

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

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

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

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

![Custom action output][04]

### Updating the front matter

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

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

Example:

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

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

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

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

## Bulk script execution

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

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

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

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

## Creating a media script

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

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

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

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

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

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

### Media file script

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

![Custom action for a media file][05]

### Media folder script

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

![Custom action for a media folder][06]

## Sample scripts

### Bash starter

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

### Python starter

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

import sys

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

### Optimize image (media file script)

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

const arguments = process.argv;

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

    const fileArg = arguments[3]; // The file path

    await imagemin([fileArg], {
      destination: path.dirname(fileArg),
      glob: false,
      plugins: [
        imageminJpegtran(),
        imageminPngquant()
      ]
    });

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

**Prerequisites**:

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

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

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

const arguments = process.argv;

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

    const workspaceArg = arguments[2]; // The workspace path
    const folderArg = arguments[3]; // The folder path

    const files = await imagemin([path.join(folderArg, '*.{jpg,png}')], {
      destination: folderArg,
      glob: true,
      plugins: [
        imageminJpegtran(),
        imageminPngquant()
      ]
    });

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

**Prerequisites**:

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


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

Custom actions

# Static Site Generator and Frameworks

## Overview

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

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

## Support additional file types

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

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

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

### Hugo

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

### Eleventy

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

[Update the docs][02]

### Gatsby

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

[Update the docs][02]

### Next.js

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

[Update the docs][02]

### SvelteKit

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

[Update the docs][02]


### ...

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

[Update the docs][02]


[01]: /docs/ssg-and-frameworks/hugo-configuration
[02]: https://github.com/FrontMatter/web-documentation-nextjs/edit/main/content/docs/ssg.md

Static Site Generators

# Hugo Configuration

## Setting up Front Matter for your Hugo site

Start by opening your Hugo project in Visual Studio Code.

> **Info**: For this article, we made use of the [Hugo Example site][01] in combination with the
> _beautifulhugo_ theme.

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

## Installing Front Matter

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

![Installing Front Matter extension][03]

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

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

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

The welcome dashboard looks as follows:

![Welcome dashboard][04]

## Configuration of Front Matter

### Project initialization

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

![Project intialization][05]

### Framework or static-site generator

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

![Selecting your framework or static-site generator][06]

### Content folders

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

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

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

![Register content folder][07]

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

![Specify a name for the content folder][08]

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

![Content dashboard][09]

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

## Using Front Matter

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

![Front Matter panel for content management][10]

## Extra configuration steps

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


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

Hugo Configuration

# Site preview

## Overview

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

![Site preview][01]

## Configuration

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

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

### Prefix or section configuration

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

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

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

#### Globally

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

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

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

#### Page folder

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

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

#### Content type

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

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


[01]: /assets/site-preview.png

Site preview

# Markdown features

## Overview

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

## WYSIWYG

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

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

![WYSIWYG controls][01]

Currently supported are:

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

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

### Inserting headings

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

![WYSIWYG headings][02]

### Other WYSIWYG options

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

![WYSIWYG options][03]

## Insert images

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

![Insert images][04]

> **Info**: You can also use media snippets to insert your images. More information can be found in
> the [Media Snippets][05] section.

## Front matter folding

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

![Folding range][06]

## Front matter highlighting

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

![Highlighting][07]

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

## Hiding front matter

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

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

### Example


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


### Result

![Hide front matter][08]


[01]: /releases/v5.7.0/wysiwyg_controls.png
[02]: /releases/v5.7.0/wysiwyg_headings.png
[03]: /releases/v5.7.0/wysiwyg_options.png
[04]: /releases/v4_0_0/insert-images.gif
[05]: /docs/snippets#media-snippets
[06]: /assets/folding.png
[07]: /assets/fm-highlight.png
[08]: /releases/v8.1.0/hide-fm.png

Markdown

# Snippets

## Overview

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

All snippets can be found on the snippets dashboard.

![Snippet dashboard][01]

## Create a snippet

Follow the next steps in order to create a snippet:

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

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

The snippet definition contains the following fields:

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

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

## Placeholders

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

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

**Example:**

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

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

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

## Fields

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

The field definition is the same as the one we use for our content types (more information at
[defining your own content type][02]).

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

- `string`
- `choice`

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

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

**Example:**

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

## Using a snippet

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

![Insert a snippet][04]

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

![Fill in the snippet form][05]

- Click on insert.

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

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

## Media snippets

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

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

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

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

![Media snippet][06]

### Placeholders

The available placeholders for your media snippets are the following:

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

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

### Fields

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


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



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

Snippets

# Commands

## Overview

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

![Commands][01]

## Using commands

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

## Available commands

### Initialize project

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

ID: `frontMatter.init`

### Open dashboard

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

ID: `frontMatter.dashboard`

### Diagnostic logging

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

ID: `frontMatter.diagnostics`

### Insert image into your content

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

ID: `frontMatter.insertImage`

### Insert snippet into your content

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

ID: `frontMatter.insertSnippet`

### Create category

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

ID: `frontMatter.createCategory`

### Create tag

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

ID: `frontMatter.createTag`

### Insert categories

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

ID: `frontMatter.insertCategories`

### Insert tags

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

ID: `frontMatter.insertTags`

### Export all tags & categories to your settings

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

ID: `frontMatter.exportTaxonomy`

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

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

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

ID: `frontMatter.remap`

### Create a template from current file

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

ID: `frontMatter.createTemplate`

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

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

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

ID: `frontMatter.createContent`

### Generate slug based on content title

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

Example:

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

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

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

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

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

ID: `frontMatter.generateSlug`

### Set lastmod date

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

ID: `frontMatter.setLastModifiedDate`

### Preview content

Open the site preview of your content in VS Code.

ID: `frontMatter.preview`

### Promote settings from local to team level

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

ID: `frontMatter.promoteSettings`

## Removed commands

### Set current date

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

ID: `frontMatter.setDate`


[01]: /assets/commands-v6.1.0.png

Commands

# Troubleshooting

## Overview

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

## Content and front matter parsing

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

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

![Troubleshooting - Informing you of a parsing issue in the front matter of your article][01]

## Looking what is happening behind the scenes

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

![Troubleshooting - Show the output of what the extension has been performing][02]

## Inspecting configuration behavior

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

The document has several sections:

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

## Feature migrations

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

### Publish and modified date migration

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

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

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

#### No custom content type

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

Check the [change the default content type][05] section for more information.

#### When using a custom content type

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


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

Property	Description
`fieldRef`	The name of the field to validate
`operator`	The operator to use to validate the field value. See Supported operators
`value`	The value to validate
`caseSensitive`	If the validation should be case sensitive. Default: `true`

Field conditions

Show or hide fields

Supported operators

Feedback/comments

Ready to get started?

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`