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

1
npx 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.

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

Mirroring the content-manager and related folders

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

1
npm 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):

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


mkdir -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

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

On Linux/Mac

1
2
3
cp .cache/plugins/strapi-plugin-content-manager/admin/src/components/Wysiwyg/constants.js extensions/content-manager/admin/src/components/Wysiwyg/constants.js
cp .cache/plugins/strapi-plugin-content-manager/admin/src/components/PreviewWysiwyg/index.js extensions/content-manager/admin/src/components/PreviewWysiwyg/index.js
cp .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.

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

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.

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
import React from 'react';
import { InputSelect as Select } from 'strapi-helper-plugin';
import useWysiwyg from '../../hooks/useWysiwyg';
import { IDYLL_OPTIONS } from './constants';
import SelectWrapper from './SelectWrapper';

const IdyllControlSelect = () => {
  const {
    isPreviewMode,
    headerValue,
    isFullscreen,
    handleChangeSelect,
  } = useWysiwyg();

  return (
    <SelectWrapper isFullscreen={isFullscreen}>
      <Select
        disabled={isPreviewMode}
        name="headerSelect"
        onChange={handleChangeSelect}
        value={headerValue}
        selectOptions={IDYLL_OPTIONS}
      />
    </SelectWrapper>
  );
};

export 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
2
...
import IdyllControlSelect from './idyllControlSelect';

Then add it to controls container

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

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
import React from 'react';
import PropTypes from 'prop-types';
import PreviewWysiwygWrapper from './Wrapper';
import * as components from 'idyll-components';
import IdyllDocument from 'idyll-document';

class PreviewWysiwyg extends React.PureComponent {
  render() {
    return (
      <PreviewWysiwygWrapper isFullscreen={this.context.isFullscreen}>
        <IdyllDocument
          markup={this.props.data}
          components={components}
          layout={'centered'}
          context={context => {
            typeof window !== 'undefined'
              ? (window.IDYLL_CONTEXT = context)
              : null;
          }}
          datasets={{}}
        />

        <input
          className="editorInput"
          value=""
          onChange={() => { }}
          tabIndex="-1"
        />
      </PreviewWysiwygWrapper>
    );
  }
}

PreviewWysiwyg.defaultProps = {
  data: '',
};

PreviewWysiwyg.propTypes = {
  data: PropTypes.string,
};

export 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!