
# Introduction

## Overview

Front Matter is an essential Visual Studio Code extension that simplifies working and managing your markdown articles. We created the extension to support many static-site generators like Hugo, Jekyll, Hexo, NextJs, Gatsby, and more.

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

![Welcome screen](/assets/welcome-progress.png)

Our main extension features are:

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

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

## Why Front Matter?

Initially, the Front Matter extension was created when [Elio Struyf](https://twitter.com/eliostruyf) migrated from WordPress to Hugo (Static Site Generator). To make content management more straightforward, he started to develop the Front Matter extension. He added more features regularly, and eventually, it became a headless CMS that runs within Visual Studio Code.

## Advantages

We believe that Front Matter gives you the following advantages:

### Speed

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

### Use it within Visual Studio Code

You do not need to jump from tool to tool. Just use the one that you like the most, which is, of course, Visual Studio Code.

### Customizable

Almost all of the Front Matter features are customizable by the extension of its settings. These settings make sure that you can tweak it to your needs.

### Extensibility

We know that not every site is the same. That is why we allow you to add your custom scripts. These scripts will show up as actions in our panel and could take your content management to the next level. 

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

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

Introduction


# Getting started

## Overview

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

## Installation

You can get the extension via:

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

### Beta version

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

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

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

## Welcome screen

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

![Welcome screen](/releases/v5.2.0/welcome-screen.png)

It also supports light themes:

![Welcome screen](/assets/welcome-light.png)

> **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 **not** created to only support one static site generator, you will be able 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.

You can register a folder by right-clicking on a folder name in the explorer panel from Visual Studio Code and selecting **Front Matter: Register folder**.

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

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

## Workspaces with multiple folders

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

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

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

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

## Enjoy using Front Matter

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

Getting started


# Content Types

## Overview

As each website is different, we allow you to define your types of content to use with Front Matter. Front Matter will adapt the metadata fields to show in its editor panel depending on the type of content.

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

## How it works

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

Our default content type consists of the following fields:

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

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

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

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

## 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"
      },
      {
        "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"
      },
      {
        "title": "Last modified date",
        "name": "lastmod",
        "type": "datetime"
      },
      {
        "title": "Navigation weight",
        "name": "weight",
        "type": "number"
      }
    ]
  }
]
```

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

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

### Content type properties

For the content type you can configure the following properties:

- `name (string)`: Name of the content type
- `fields (Field[])`: Check the [supported field types](/docs/content-types#supported-field-types)
- `pageBundle (boolean)`: Specify if for the content a folder will be created. Default: `false`.
- `previewPath (string)`: Defines a custom preview path for the content type. Default: `null`. When the preview path is not set, the value from the [frontMatter.preview.pathName](https://frontmatter.codes/docs/settings#frontmatter.preview.pathname) setting will be used.

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

## Supported field types

Front Matter its metadata section supports the following fields:

- `string`
- `number`
- `datetime`
- `boolean`
- `image`
- `choice`
- `draft`: specifies the kind of draft field you want to use: `boolean` or `choice`. This field, can be configured with the [frontmatter.content.draftfield](/docs/settings#frontmatter.content.draftfield) setting.
- `tags`: mapped to the tags defined in your settings.
- `categories`: mapped to the categories defined in your settings.
- `taxonomy`: if you want to define your own custom taxonomy fields.

### Custom draft field

By default, the draft field is a boolean field. If you want to use your own status values, you can configure it via the [frontmatter.content.draftfield](/docs/settings#frontmatter.content.draftfield) setting.

Sample of custom draft field with:

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

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

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

### Field properties

A field consists out of the following properties:

- `title (string)`: The title to show in the metadata section (optional);
- `name (string)`: The name of your field, will be used to set in the front matter of your Markdown file;
- `type (field type - string)`: One of the above supported types.
- `hidden (boolean - optional)`: Specifies if you want to hide the field from the metadata section, but still have it available in Front Matter.

#### Additional properties

##### String fields

- `single (boolean)`: When you picked the `string` field type, you can specify if it is a single line. By default it will render as a multiline field (optional).

##### Image fields

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

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

##### Choice fields

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

Example of using an array of string values:

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

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

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

##### Custom taxonomy field

- `taxonomyId`: The id of the taxonomy you want to use, it will need to be defined in the `frontMatter.taxonomy.customTaxonomy` setting.

Example of a custom taxonomy field definition:

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

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

Here is an example of the custom taxonomy setting definition:

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

## Preview path

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.

There are two ways to set this:

1. Via the global [frontMatter.preview.pathName](https://frontmatter.codes/docs/settings#frontmatter.preview.pathname) setting. This will be used as the default value for all content types.
2. Define a path per content type can be done via the `previewPath` property. Once set, it will ignore the `frontMatter.preview.pathName` setting.

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

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

## Page and leaf bundles

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

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

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

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

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

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

## Creating a template

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

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

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

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

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

Content Types


# 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](https://res.cloudinary.com/estruyf/image/upload/w_1256/v1631520508/frontmatter/dashboard.png)

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

![Dashboard - Media view](https://res.cloudinary.com/estruyf/image/upload/w_1256/v1631520508/frontmatter/media.png)

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

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

## Contents view

### Draft status navigation

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

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

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

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

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

### Supported filters

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

### Supported sorting

- Last modified
- Filename (asc/desc)

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

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

## 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](/assets/lightbox.png)

### Media actions

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

**Setting metadata**

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

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

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

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

**Deleting a media file**

![Dashboard - Delete media file](/assets/delete-media.png)

**Custom media actions**

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

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

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

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

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

### Drag and Drop

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

![Dashboard - Upload media file](/assets/upload-media.png)

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


Dashboard


# Editor panel

## Overview

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

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

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

## Using the panel

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

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

## Global settings

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

![Global settings](/assets/global-settings.png)

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

## SEO status

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

Supports the following:

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

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

### Settings

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

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

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

## Actions

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

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

![Actions](/assets/actions.png)

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

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

### Settings

The following settings are related to these actions:

- `frontMatter.preview.host`: Specify the host URL (example: http://localhost:1313) to be used when opening the preview.
- `frontMatter.taxonomy.dateField`: Specifies the date field name to use in your Front Matter. Default: `date`.
- `frontMatter.taxonomy.modifiedField`: Specifies the modified date field name to use in your Front Matter. Default: `lastmod`.
- `frontMatter.taxonomy.dateFormat`: Specify the date format for your articles. Check [date-fns formating](https://date-fns.org/v2.0.1/docs/format) for more information.
- `frontMatter.taxonomy.slugPrefix`: Specify a prefix for the slug.
- `frontMatter.taxonomy.slugSuffix`: Specify a suffix for the slug.
- `frontMatter.taxonomy.alignFilename`: Align the filename with the new slug when it gets generated.

## Metadata

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

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

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

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.

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

## Recently modified

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

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

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

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

## Other actions

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

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

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

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


Editor panel


# Custom actions

## Overview

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

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

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

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

## The custom action setting

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

The following properties will be used for all your custom actions:

- `title`: The title of the custom action
- `script`: The path to the script to execute
- `nodeBin`: The path to your node executable. In case of using `nvm` this might need to be defined. (default: `node` - optional).
- `type`: The type for which the script will be used. Can be `content` or `mediaFile` or `mediaFolder`. (default: `content` - optional).

## Creating a content script

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

```javascript
const arguments = process.argv;

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

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

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

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

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

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

```json
{
  "frontMatter.custom.scripts": [{
    "title": "Generate social image",
    "script": "./scripts/social-img.js",
    "nodeBin": "~/.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 `nodeBin` property to specify the path to your node executable. **This property is optional**.

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

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

## 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",
    "nodeBin": "~/.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",
      "nodeBin": "~/.nvm/versions/node/v16.13.0/bin/node",
      "type": "mediaFile"
    },
    {
      "title": "Optimize images",
      "script": "./scripts/media-all.js",
      "nodeBin": "~/.nvm/versions/node/v16.13.0/bin/node",
      "type": "mediaFolder"
    }
  ]
}
```

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

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

### Media file script

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

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

### Media folder script

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

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

## Additional output configuration

There are additional configuration options for script execution:

- `output`: Specifies the output type. The default value is `notification`. The 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. The default value is `text`. The 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.

## Sample scripts

### Optimize image (media file script)

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

const arguments = process.argv;

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

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

**Prerequisites**:

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

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

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

const arguments = process.argv;

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

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

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

**Prerequisites**:

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


Custom actions


# Static Site Generator and Frameworks

## Overview

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

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

### Eleventy

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

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

### Gatsby

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

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

### Next.js

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

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

### SvelteKit

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

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

### ...

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

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

Static Site Generators


# Site preview

## Overview

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

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

## Configuration

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

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

Site preview


# Markdown features

## Overview

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

## WYSIWYG

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

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

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

Currently supported are:

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

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

### Inserting headings

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

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

### Other WYSIWYG options

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

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

## Insert images

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

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

> **Important**: If you want, you can add your own media snippet to allow you to use your shortcodes/markdown/... In order to specify the snippet, use the `frontMatter.dashboard.mediaSnippet` setting.

## Insert your own media snippet

The `frontMatter.dashboard.mediaSnippet` setting is used similarly like the default VS Code snippets. You need to define an array of strings for multiline snippets.

The example used in the GIF above looks as follows:

```json
"frontMatter.dashboard.mediaSnippet": [
  "{{< imgShortCode \"{mediaUrl}\" \"{caption}\" >}}"
]
```

### Placeholders

For your snippet, you can use the following placeholders:

- `{mediaUrl}`: Use this to insert the relative path to 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.

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

## Front Matter folding

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

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

## Front Matter highlighting

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

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

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


Markdown


# Commands

## Overview

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

![Commands](/assets/commands.png)

## Using commands

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

## Available commands

### Initialize project

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

ID: `frontMatter.init`

### Open dashboard

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

ID: `frontMatter.dashboard`

### Insert image into your content

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

ID: `frontMatter.insertImage`

### Create category

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

ID: `frontMatter.createCategory`

### Create tag

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

ID: `frontMatter.createTag`

### Insert categories

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

ID: `frontMatter.insertCategories`

### Insert tags

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

ID: `frontMatter.insertTags`

### Export all tags & categories to your settings

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

ID: `frontMatter.exportTaxonomy`

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

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

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

ID: `frontMatter.remap`

### Create a template from current file

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

ID: `frontMatter.createTemplate`

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

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

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

ID: `frontMatter.createContent`

### Generate slug based on content title

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

Example:

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

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

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

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

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

ID: `frontMatter.generateSlug`

### Set lastmod date

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

ID: `frontMatter.setLastModifiedDate`

### Preview content

Open the site preview of your content in VS Code.

ID: `frontMatter.preview`

## Promote settings from local to team level

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

ID: `frontMatter.promoteSettings`

## Removed commands

### Set current date

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

ID: `frontMatter.setDate`


Commands


# Settings

## Overview

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

## Team settings and local settings

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

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

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

## Migrate local settings to team settings

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

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

## Available settings

### frontMatter.content.autoUpdateDate

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

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

### frontMatter.content.defaultSorting

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

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

Options:

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

### frontMatter.content.draftField

Define the draft field you want to use to manage your content. [Check in the docs](https://frontmatter.codes/docs/settings#frontMatter.content.draftField)

- Type: `object` 
  - name: Define the type of field
  - type: `boolean` or `choice`
  - choices: Define the choices of the draft field `string[]` 

- Default: 

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

### frontMatter.content.fmHighlight

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

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

### frontMatter.content.pageFolders

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

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

Properties:

- `title`: Give a title for the content folder path
- `path`: The path to the content folder, important is to use the `[[workspace]]` placeholder
- `excludeSubdir`: Optional, specify if you want to exclude subdirectories from the content folder. Default: `false`.

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

Sample:

```json
{
  "frontMatter.content.pageFolders": [
    {
      "title": "Pages",
      "path": "[[workspace]]/content",
      "excludeSubdir": true
    },
    {
      "title": "Blog posts",
      "path": "[[workspace]]/content/posts"
    }
  ]
}
```

### frontMatter.content.publicFolder

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

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

### frontMatter.content.sorting

Define the sorting options for your dashboard content.

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

Properties:

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

Sample:

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

### frontMatter.content.wysiwyg

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

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

### frontMatter.custom.scripts

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

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

Sample:

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

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

### frontMatter.dashboard.mediaSnippet

Specify the a snippet for your custom media insert markup.

```json
"frontMatter.dashboard.mediaSnippet": [
  "{{< caption \"{mediaUrl}\" \"Description\" >}}"
]
```

> **Important**: Use the `{mediaUrl}` placeholder where you want the relative image path to be inserted. Check [placeholders](/docs/markdown#placeholders) for more information.

### frontMatter.dashboard.openOnStart

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

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

### frontMatter.framework.id

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

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

### frontMatter.media.defaultSorting

Specify the default sorting option for the media dashboard.

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

Options:

- LastModifiedAsc
- LastModifiedDesc
- FileNameAsc
- FileNameDesc

### frontMatter.panel.freeform

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

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

### frontMatter.preview.host

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

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

### frontMatter.preview.pathName

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

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

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

### frontMatter.site.baseURL

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

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

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

### frontMatter.taxonomy.alignFilename

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

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

### frontMatter.taxonomy.categories

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

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

### frontMatter.taxonomy.commaSeparatedFields

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

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

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

### frontMatter.taxonomy.contentTypes

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

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


### frontMatter.taxonomy.customTaxonomy

Specify the custom taxonomy field data.

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

Sample:

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

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

### frontMatter.taxonomy.dateField

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

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

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

### frontMatter.taxonomy.dateFormat

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

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

### frontMatter.taxonomy.frontMatterType

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

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

### frontMatter.taxonomy.indentArrays

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

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

### frontMatter.taxonomy.modifiedField

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

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

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

### frontMatter.taxonomy.noPropertyValueQuotes

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

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

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

### frontMatter.taxonomy.seoContentLengh

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

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

### frontMatter.taxonomy.seoDescriptionField

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

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

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

### frontMatter.taxonomy.seoDescriptionLength

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

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

### frontMatter.taxonomy.seoSlugLength

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

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

### frontMatter.taxonomy.seoTitleLength

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

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

### frontMatter.taxonomy.slugPrefix

Specify a prefix for the slug.

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

### frontMatter.taxonomy.slugSuffix

Specify a suffix for the slug.

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

### frontMatter.taxonomy.tags

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

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

### frontMatter.templates.folder

Specify the folder to use for your article templates.

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

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

### frontMatter.templates.prefix

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

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


## Removed settings

### frontMatter.content.folders

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


Introduction

Overview

Why Front Matter?

Advantages

Speed

Use it within Visual Studio Code

Customizable

Extensibility

Feedback