You can use the WRITE API in the rich editor to submit HTML strings. This can be useful for migrating from the old rich editor or from other CMS platforms.

Basic Rules

• The HTML string passed in the request needs to have double quotes escaped (\") or replaced with single quotes (').
• For display purposes, this document shows HTML including line breaks, but please do not include line breaks in the actual request.

Headings and Paragraphs

h1 to h5 and p tags are supported. The specified hashed id will not be applied during parsing but will be included in the API response.

<h1>Heading 1</h1>

Line Breaks and Paragraphs

If there is a br tag in the text, it will be parsed as a line break.

// Paragraph
<p>Pressing Enter will</p>
<p>create a new paragraph.</p>

// Line Break
<p>Pressing Shift + Enter will create a<br>line break.</p>

Bold Text

For strong tags, the text will be parsed as bold.

<strong>This text will be bold</strong>

Italic Text

For em tags, the text will be parsed as italic.

<em>This text will be italic</em>

Underlined Text

For u tags, the text will be parsed as underlined.

<u>This text will be underlined</u>

Strikethrough Text

For s tags, the text will be parsed as strikethrough.

<s>This text will have strikethrough</s>

Code

For code tags, the text will be parsed as code.

<code>console.log('Hello microCMS!')</code>

Text Color

By specifying the color property in the style attribute of the span tag, the text color can be parsed.

<span style='color: #ff0000'>Text Color</span>

Font Size

Currently not supported.

Text Alignment

By specifying text-align in the style, you can set left alignment / center alignment / right alignment .

Left alignment (default)

<p>Left aligned text</p>

Center alignment

<p style='text-align:center'>Center aligned text</p>

Right alignment

<p style='text-align: right'>Right aligned text</p>

Horizontal Line

In the case of the hr tag, it is parsed as a horizontal line.

<hr>

Quote

In the case of the blockquote tag, it is parsed as a quote.

<blockquote>Quoted text</blockquote>

Code Block

If you specify the code tag inside the pre tag, it is parsed as a code block.

<pre>
  <code>const greeting = 'Hello microCMS!';\nconsole.log(greeting);</code>
</pre>

You can specify a filename and language for the code block. By setting the value of the data-filename attribute in the div tag, it will be parsed as the filename. Additionally, by specifying a value in the class of the code tag, it will be parsed as the language.

<div data-filename='greeting.js'>
  <pre>
    <code class='language-javascript'>const greeting = 'Hello microCMS!'; console.log(greeting);</code>
  </pre>
</div>

Table

You can parse a table by creating a structure of table tag > tbody tag > tr tag > th tag or td tag. If you want the first row or column to be a header, use the th tag. Also, if you want to parse it as merged cells, specify the values for colspan and rowspan.

<table>
  <tbody>
    <tr>
      <th colspan='1' rowspan='1'>
        <p>Company</p>
      </th>
      <th colspan='1' rowspan='1'>
        <p>Location</p>
      </th>
    </tr>
    <tr>
      <td colspan='1' rowspan='1'>
        <p>microCMS</p>
      </td>
      <td colspan='1' rowspan='1'>
        <p>Tokyo</p>
      </td>
    </tr>
  </tbody>
</table>

List

If you specify the li tag inside the ul tag, it will be parsed as a list.

<ul>
  <li>Apple</li>
  <li>Orange</li>
</ul>

It can also be parsed in a nested structure.

<ul>
  <li>Japan
    <ul>
      <li>Tokyo</li>
      <li>Osaka</li>
      <li>Saitama</li>
    </ul>
  </li>
  <li>America</li>
</ul>

Numbered List

When you specify li tags within an ol tag, it is parsed as a numbered list.

<ol>
  <li>Account Registration</li>
  <li>Service Registration</li>
  <li>Create API</li>
</ol>

Links

If a URL is specified in the href of the a tag, it will be parsed as a link.

<p><a href='https://microcms.io'>Link here</a></p>

By specifying target='_blank' in the a tag, it can be parsed as opening in a new tab. The value of rel is not applied during parsing but is included in the API response.

<p><a href='https://microcms.io/pricing/' target='_blank'>microCMS Pricing Page</a></p>

Images

If src is specified in the img tag, it will be parsed as an image. The value of src is only valid for the microCMS image domain, and external URLs are not supported. Additionally, if the image URL is incorrect or if an image from a different service is specified (when the service ID does not match), it will not be parsed.

If no value is set, alt will be "" (empty string), and width and height will be set to the original size of the image.

<img src='https://images.microcms-assets.io/assets/service/test/file.png'
        alt='' width='1200' height='630' />

If an img tag is specified within an a tag, it will be parsed as an image link.

<a href='https://example.com'>
  <img src='https://images.microcms-assets.io/assets/service/test/file.png' alt='' width='1200' height='630' />
</a>

By specifying values in the query strings w and h in the src URL, it will be parsed as Custom Width and Custom Height. If both w and h are not specified, parsing will not be applied.

<img src='https://images.microcms-assets.io/assets/service/test/file.png?w=1200&h=630'
        alt='' width='1200' height='630' />

The above behavior remains the same even for the figure tag. However, if you want to specify a figcaption, you need to use the figure tag.

<figure>
  <img src='https://images.microcms-assets.io/assets/service/test/file.png' alt='' width='1200' height='630' />
  <figcaption>caption</figcaption>
</figure>

For services with a custom media domain set, you can specify images from the configured domain.

<img src='https://images.example.com/assets/service/test/file.png' alt='' width='1200' height='630' />

Image Alignment

By specifying text-align in the style attribute of the figure tag, you can set the image to be left-aligned / center-aligned / right-aligned .

<figure style='text-align: left;'>
  <img src='https://images.microcms-assets.io/assets/service/test/file.png'
          alt='' width='1200' height='630' />
</figure>

File

By specifying a URL in the href of the a tag and setting data-embed-type="file", it will be parsed as a file.

<p><a data-embed-type='file' href='https://files.microcms-assets.io/assets/service/test/file.pdf'>file.pdf</a></p>

The value of href is only valid for the microCMS file domain, and external URLs are not supported. Additionally, the following cases will be parsed as text.

• If the file URL is incorrect
• If a file from a different service is specified (when the service ID does not match)
• If data-embed-type is set to anything other than file

Furthermore, the following cases will be parsed as a normal a tag.

• If data-embed-type is not specified

For services with a custom media domain set, you can specify the configured domain.

<p><a data-embed-type='file' href='https://files.example.com/assets/service/test/file.pdf'>file.pdf</a></p>

Custom Class

If a value is specified for class in the span tag, it will be parsed as a custom class. If no custom class is set, it will be parsed as simple text in a p tag.

<p><span class='highlight'>Highlighted text</span></p>

Embedded Editing

Currently not supported.

Toolbar Editing

In the rich editor, you can customize the decoration buttons. If the decoration button is turned off, parsing will not be applied. For example, if bold is turned off, the strong tag will not be parsed and will become simple text in a p tag.

<p>Text that will be bold</p>

If HTML Parsing Fails

The relevant section will generally be parsed as paragraph text (p tag).
Additionally, depending on the content of the request, a response may be returned with a 500 series status code, resulting in a failure to register the data.