static-cms/packages/docs/content/docs/widget-markdown.mdx

---
group: Widgets
title: Markdown
weight: 19
---

- **Name:** `markdown`
- **UI:** [Toast UI Editor](https://ui.toast.com/tui-editor) ([Docs](https://nhn.github.io/tui.editor/latest/))
- **Data type:** `markdown string`

The markdown widget provides a full fledged text editor allowing users to format text with features such as headings and blockquotes. Users can change their editing view with a handy toggle button.

_Please note:_ If you want to use your markdown editor to fill a markdown file contents after its frontmatter, you'll have to name the field `body` so the CMS recognizes it and saves the file accordingly.

## Widget Options

For common options, see [Common widget options](/docs/widgets#common-widget-options).

| Name          | Type                  | Default | Description                                                                                                                                           |
| ------------- | --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| default       | string                | `''`    | _Optional_. The default value for the field. Accepts markdown content                                                                                 |
| media_library | Media Library Options | `{}`    | _Optional_. Media library settings to apply when a media library is opened by the current widget. See [Media Library Options](#media-library-options) |
| media_folder  | string                |         | _Optional_. Specifies the folder path where uploaded files should be saved, relative to the base of the repo                                          |
| public_folder | string                |         | _Optional_. Specifies the folder path where the files uploaded by the media library will be accessed, relative to the base of the built site          |

### Media Library Options

| Name           | Type                   | Default | Description                                                                                                                                       |
| -------------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| allow_multiple | boolean                | `true`  | _Optional_. When set to `false`, prevents multiple selection for any media library extension, but must be supported by the extension in use       |
| config         | string                 | `{}`    | _Optional_. A configuration object that will be passed directly to the media library being used - available options are determined by the library |
| choose_url     | string<br />\| boolean | `true`  | _Optional_. When set to `false`, the "Insert from URL" button will be hidden                                                                      |

## Example

<CodeTabs>
```yaml
name: body
label: Blog post content
widget: markdown
```

```js
name: 'body',
label: 'Blog post content',
widget: 'markdown',
```

</CodeTabs>

This would render as:

![Markdown widget example](/img/widgets-markdown.webp)

_Please note:_ The markdown widget outputs a raw markdown string. Your static site generator may or may not render the markdown to HTML automatically. Consult with your static site generator's documentation for more information about rendering markdown.

## Shortcodes

Shortcodes can be added to customize the Markdown editor via `registerShortcode`.

### Usage

```markdown
[youtube|p6h-rYSVX90]
```

<CodeTabs>

```js
CMS.registerShortcode('youtube', {
  label: 'YouTube',
  openTag: '[',
  closeTag: ']',
  separator: '|',
  toProps: args => {
    if (args.length > 0) {
      return { src: args[0] };
    }

    return { src: '' };
  },
  toArgs: ({ src }) => {
    return [src];
  },
  control: ({ src, onChange }) => {
    return h('span', {}, [
      h('input', {
        key: 'control-input',
        value: src,
        onChange: event => {
          onChange({ src: event.target.value });
        },
      }),
      h(
        'iframe',
        {
          key: 'control-preview',
          width: '420',
          height: '315',
          src: `https://www.youtube.com/embed/${src}`,
        },
        '',
      ),
    ]);
  },
  preview: ({ src }) => {
    return h(
      'span',
      {},
      h(
        'iframe',
        {
          width: '420',
          height: '315',
          src: `https://www.youtube.com/embed/${src}`,
        },
        '',
      ),
    );
  },
});
```

```jsx
import CMS from '@staticcms/core';

CMS.registerShortcode('youtube', {
  label: 'YouTube',
  openTag: '[',
  closeTag: ']',
  separator: '|',
  toProps: args => {
    if (args.length > 0) {
      return { src: args[0] };
    }

    return { src: '' };
  },
  toArgs: ({ src }) => {
    return [src];
  },
  control: ({ src, onChange }) => {
    return (
      <span>
        <input
          key="control-input"
          value={src}
          onChange={event => {
            onChange({ src: event.target.value });
          }}
        />
        <iframe
          key="control-preview"
          width="420"
          height="315"
          src={`https://www.youtube.com/embed/${src}`}
        />
      </span>
    );
  },
  preview: ({ src }) => {
    return (
      <span>
        <iframe
          width="420"
          height="315"
          src={`https://www.youtube.com/embed/${src}`}
        />
      </span>
    );
  },
});
```

```tsx
import CMS from '@staticcms/core';

interface YouTubeShortcodeProps {
  src: string;
}

CMS.registerShortcode<YouTubeShortcodeProps>('youtube', {
  label: 'YouTube',
  openTag: '[',
  closeTag: ']',
  separator: '|',
  toProps: args => {
    if (args.length > 0) {
      return { src: args[0] };
    }

    return { src: '' };
  },
  toArgs: ({ src }) => {
    return [src];
  },
  control: ({ src, onChange }) => {
    return (
      <span>
        <input
          key="control-input"
          value={src}
          onChange={event => {
            onChange({ src: event.target.value });
          }}
        />
        <iframe
          key="control-preview"
          width="420"
          height="315"
          src={`https://www.youtube.com/embed/${src}`}
        />
      </span>
    );
  },
  preview: ({ src }) => {
    return (
      <span>
        <iframe
          width="420"
          height="315"
          src={`https://www.youtube.com/embed/${src}`}
        />
      </span>
    );
  },
});
```

</CodeTabs>