Adding Idyll Support to Strapi

This is a guide on how to customize the admin panel in order to add Idyll support to the default markdown rich text editor. We will customize the editor to add Idyll components to the editor’s controls panel and implement preview functionality for Idyll.

This guide assumes you are using Strapi version 3.1.3 or higher. If you are using a Windows machine, make sure to use PowerShell as some of the command-line scripts may not run as expected on default Windows CMD.

You may be wondering what Idyll is and why you would want to use it…

What is Idyll?

Idyll is an open-source markup language and toolkit that allows content creators to write interactive articles.

It enables collaboration between programmers and journalists, researchers, and designers.

Idyll uses a lot of the same principles and syntax as markdown. But the real power of Idyll is that it has a special syntax that allows you to embed Javascript inline with your text. Idyll comes with a variety of components that can be used out-of-the-box to create rich documents. In addition to the built-in components, you can write custom components using tools like D3 or React. You can learn more about Idyll on the official website.

Pre-requisites

To follow this guide, you will need to have an instance of Strapi up and running. If not, here is a quick command to get started

1npx create-strapi-app my-project --quickstart

Head over to the Strapi docs for more information on Strapi installation.

Idyll Installation

First, we navigate to the root folder and install the dependencies. The Idyll packages we will need are idyll-components and idyll-document.

1npm install --save idyll-components idyll-document

Mirroring the content-manager and related folders

Next, we are going to run the application using the command:

1npm run develop --watch-admin

This will create the .cache folder where all the admin files are copied.

The code we need to modify is located in the .cache/plugins/strapi-plugin-content-manager/admin/src folder. We are basically mirroring and overriding specific files of Strapi's content-manager plugin.

To create the mirror folders, run the following in the app’s root directory (e.g., this would be my-project in this tutorial):

1mkdir -p extensions/content-manager/admin/src/components/Wysiwyg
2
3
4mkdir -p extensions/content-manager/admin/src/components/PreviewWysiwyg

The -p flag enables the mkdir command to create parent directories if they don’t already exist.

If you are using Windows CMD and the above command does work correctly, you can alternatively create the folders manually in the Windows File Manager.

We will then copy the files we want to over from .cache to our mirror folders

On Windows

1cp .cache\plugins\strapi-plugin-content-manager\admin\src\components\Wysiwyg\constants.js extensions\content-manager\admin\src\components\Wysiwyg\constants.js
2cp .cache\plugins\strapi-plugin-content-manager\admin\src\components\PreviewWysiwyg\index.js extensions\content-manager\admin\src\components\PreviewWysiwyg\index.js
3cp .cache\plugins\strapi-plugin-content-manager\admin\src\components\Wysiwyg\index.js extensions\content-manager\admin\src\components\Wysiwyg\index.js

On Linux/Mac

1cp .cache/plugins/strapi-plugin-content-manager/admin/src/components/Wysiwyg/constants.js extensions/content-manager/admin/src/components/Wysiwyg/constants.js
2cp .cache/plugins/strapi-plugin-content-manager/admin/src/components/PreviewWysiwyg/index.js extensions/content-manager/admin/src/components/PreviewWysiwyg/index.js
3cp .cache/plugins/strapi-plugin-content-manager/admin/src/components/Wysiwyg/index.js extensions/content-manager/admin/src/components/Wysiwyg/index.js

Adding Idyll components to the editor’s inline controls

Next, we are gonna add a dropdown list of Idyll components which will appear inline with the default editor's markdown controls. This makes it easy for content managers to easily add Idyll components to documents without having to type out the entire syntax.

Define dropdown options First, we need to define the options for the dropdown. The options are defined as an array of objects, each object representing an Idyll component. For this guide, we will just add a few of them. Open extensions/content-manager/admin/src/components/Wysiwyg/constants.js in a code editor and append the following code.

1export const IDYLL_OPTIONS = [
2  { id: 'Add Idyll Component', value: '' },
3  { id: 'Variable', value: '[var name:"textToReplace" value:0 /]' },
4  { id: 'Display', value: '[Display value:textToReplace /]' },
5  { id: 'Range', value: '[Range value:textToReplace min:0 max:100 /]' },
6  { id: 'Button', value: '[button onClick:textToReplace]Click Me[/button]' },
7  { id: 'TextInput', value: '[TextInput value:textToReplace /]'},
8];

You can add more Idyll components by simply appending to the IDYLL_OPTIONS array.

Create the dropdown After defining the options, we are going to create the dropdown itself.

1touch extensions/content-manager/admin/src/components/Wysiwyg/idyllControlSelect.js

Open this file in a code editor and add the following code:

1import React from 'react';
2import { InputSelect as Select } from 'strapi-helper-plugin';
3import useWysiwyg from '../../hooks/useWysiwyg';
4import { IDYLL_OPTIONS } from './constants';
5import SelectWrapper from './SelectWrapper';
6
7const IdyllControlSelect = () => {
8  const {
9    isPreviewMode,
10    headerValue,
11    isFullscreen,
12    handleChangeSelect,
13  } = useWysiwyg();
14
15  return (
16    <SelectWrapper isFullscreen={isFullscreen}>
17      <Select
18        disabled={isPreviewMode}
19        name="headerSelect"
20        onChange={handleChangeSelect}
21        value={headerValue}
22        selectOptions={IDYLL_OPTIONS}
23      />
24    </SelectWrapper>
25  );
26};
27
28export default IdyllControlSelect;

Add dropdown in inline controls Open extensions/content-manager\admin\src\components\Wysiwyg\index.js in a code editor and make the following changes

Add an import for the dropdown you just created.

1...
2import IdyllControlSelect from './idyllControlSelect';

Then add it to controls container

1...
2<div className="controlsContainer">
3              <CustomSelect />
4              {CONTROLS.map((value, key) => (
5                <Controls
6                  key={key}
7                  buttons={value}
8                  disabled={isPreviewMode}
9                  editorState={editorState}
10                  handlers={{
11                    addContent: this.addContent,
12                    addOlBlock: this.addOlBlock,
13                    addSimpleBlockWithSelection: this.addSimpleBlockWithSelection,
14                    addUlBlock: this.addUlBlock,
15                    handleOpenMediaLibrary: this.handleOpenMediaLibrary,
16                  }}
17                  onToggle={this.toggleInlineStyle}
18                  onToggleBlock={this.toggleBlockType}
19                />
20              ))}
21              <IdyllControlSelect /> {/* <-- Add Idyll Dropdown here */}
22              {!isFullscreen ? (
23                <ToggleMode isPreviewMode={isPreviewMode} onClick={this.handleClickPreview} />
24              ) : (
25                <div style={{ marginRight: '10px' }} />
26              )}
27            </div>
28...

Adding Preview functionality

In order to add the Idyll preview functionality, we need to override the default preview component. Because Idyll has markdown support, the new preview component will render both Idyll and markdown. Open extensions/content-manager\admin\src\components\PreviewWysiwyg\index.js and overwrite the entire file with the following code.

1import React from 'react';
2import PropTypes from 'prop-types';
3import PreviewWysiwygWrapper from './Wrapper';
4import * as components from 'idyll-components';
5import IdyllDocument from 'idyll-document';
6
7class PreviewWysiwyg extends React.PureComponent {
8  render() {
9    return (
10      <PreviewWysiwygWrapper isFullscreen={this.context.isFullscreen}>
11        <IdyllDocument
12          markup={this.props.data}
13          components={components}
14          layout={'centered'}
15          context={context => {
16            typeof window !== 'undefined'
17              ? (window.IDYLL_CONTEXT = context)
18              : null;
19          }}
20          datasets={{}}
21        />
22
23        <input
24          className="editorInput"
25          value=""
26          onChange={() => { }}
27          tabIndex="-1"
28        />
29      </PreviewWysiwygWrapper>
30    );
31  }
32}
33
34PreviewWysiwyg.defaultProps = {
35  data: '',
36};
37
38PreviewWysiwyg.propTypes = {
39  data: PropTypes.string,
40};
41
42export default PreviewWysiwyg;

Build and Test

Rebuild the app with modifications by running npm run build (from the root folder) Run npm run develop again and open the Strapi admin panel in your browser and create a new entry. The editor should now look like this

Here is a video of the Idyll editor in action.

Conclusion

I hope this guide was helpful for customizing the default Strapi editor (and Idyll support). You can learn more about customizing the editor here(this will show you how to replace the default editor entirely).

Happy Coding!