Export to Word

The export to Word feature allows you to generate a .docx file directly from the CKEditor 5 WYSIWYG editor content.

When enabled, this feature sends the content of your editor together with the styles that are used to display it to the CKEditor Cloud Services HTML to DOCX converter service. The service then generates a Word document that can be downloaded by the user. This allows you to easily export your content to the Microsoft Word format. You can read more about the converter and the plugin in a dedicated Feature spotlight blog post.

The complementary pagination feature allows you to see where page breaks would be after the document is exported to Word. Thanks to the live preview, the user is able to fine-tune the structure of the output document when editing it. In addition to this, the pagination feature shows you the page count and allows to easily navigate between the document pages.

# Demo

The demo below allows you to generate a Word file based on the editor content. Craft the document content in the WYSIWYG editor, then click the “Export to Word” toolbar button to save it as a Word file.

# How it works

The export to Microsoft Word feature collects the HTML generated with the editor.getData() method and the default editor content styles combined with the styles provided by you in the configuration. It then sends them to the CKEditor Cloud Services HTML to DOCX converter service. The service generates a Word file and returns it to the user’s browser so they can save it in the Word format on their disk.

# Related features

• The complementary pagination feature provides live preview of the document’s page breaks, ensuring the output document looks correct.
• If you would like to export your content to a portable, universal format, using the export to PDF feature will allow you to generate PDF files out of your editor-created content.

# Before you start

After you purchase a license, follow the steps below, as explained in the Export to Word quick start guide:

• Log into the CKEditor Ecosystem customer dashboard.
• Create the token endpoint needed for authorization.
• Install and configure the CKEditor 5 export to Word plugin.

# Installation

To add the export to Word feature to your editor, install the @ckeditor/ckeditor5-export-word package:

npm install --save @ckeditor/ckeditor5-export-word

Then add the ExportWord plugin to your plugin list and configure it:

import ExportWord from '@ckeditor/ckeditor5-export-word/src/exportword';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportWord, ... ],
        toolbar: [
            'exportWord', '|',
            ...
        ],
        exportWord: {
            tokenUrl: 'https://example.com/cs-token-endpoint',
            fileName: 'my-file.docx',
            converterOptions: {
                format: 'A4', // Default value, you don't need to specify it explicitly for A4.
                margin_top: '20mm',
                margin_bottom: '20mm',
                margin_right: '12mm',
                margin_left: '12mm'
            }
        }
    } )
    .then( ... )
    .catch( ... );

# Configuration

# Default configuration

This is the default configuration of the Word export feature for CKEditor 5.

{
    exportWord: {
        fileName: 'document.docx',
        converterUrl: 'https://docx-converter.cke-cs.com/v1/convert',
        stylesheets: [ 'EDITOR_STYLES' ],
        converterOptions: {
            format: 'A4',
            margin_top: '1in',
            margin_bottom: '1in',
            margin_right: '1in',
            margin_left: '1in',
            header: undefined,
            footer: undefined,
            comments: undefined,
            suggestions: undefined,
            orientation: 'portrait'
        },
        dataCallback: ( editor ) => editor.getData( { pagination: true } )
    }
}

# Plugin options

For some use cases the default configuration will suffice. As you can see in the example above, you can improve how your Word file will look by adjusting the Word export plugin configuration.

• config.exportWord.stylesheets

  You can set the paths (relative or absolute URLs) to the stylesheets that should be included during the HTML to DOCX conversion. If you want to extend editor’s default content styles, you have to pass a special 'EDITOR_STYLES' token before a path to your custom styling.

  Note: The order of the paths matters. If you have custom elements or have overridden some of the default editor’s content styles, the paths to your file(s) should go after the 'EDITOR_STYLES' token. See the examples in the config.exportWord.stylesheets documentation.

• config.exportWord.fileName

  Sets the name for the generated Word file (together with the extension). The default name is document.docx. You can see it called in the default configuration listing above.

  This option, however, also allows for using a callback to generate dynamic filename. In the example below, the document’s title will be used as the filename of the generated .docx file.

  // Dynamic file name.
  const exportWordConfig = {
      fileName: () => {
          const articleTitle = document.querySelector( '#title' );
          return `${ articleTitle.value }.docx`;
      }
  }
  

• config.exportWord.converterUrl

  By default, the Word export feature is configured to use the CKEditor Cloud Services HTML to DOCX converter service to generate the Word files. You can, however, use this option to provide the URL to an on-premises converter. Contact us if you need this feature.

• config.exportWord.tokenUrl

  A token URL or a token request function. This field is optional and should be used when a different tokenUrl is required for the Export to Word feature. You can skip this option if you use the cloudServices configuration to provide the same tokenUrl (in fact in most cases you will probably want to provide the token in cloudServices, as other plugins like EasyImage or real-time collaboration will use this token as well. For the purpose of this guide, to explicitly show that this value is needed, we leave it the inside exportWord config).

• config.exportWord.converterOptions

  The plugin allows you to provide a custom CKEditor Cloud Services HTML to DOCX converter configuration.

• config.exportWord.dataCallback

  By default, the plugin uses editor.getData( { pagination: true } ) to gather the HTML to be sent to the conversion service. You can use this option to customize the editor’s data.

  When using the pagination feature, the pagination:true option inserts additional markers into editor’s data. Thanks to that, the DOCX converter creates a Word document similar to what is displayed in the editor.

# HTML to Word converter features

# Styling a document

By default, Export to Word plugin takes editor content styles and sends them to the CKEditor Cloud Services HTML to DOCX Converter. You can also add your own styles by providing the paths to the external CSS files.

    // ...
    exportWord: {
        fileName: 'document.docx',
        converterUrl: 'https://docx-converter.cke-cs.com/v1/convert',
        stylesheets: [
            'EDITOR_STYLES',
            'path/to/my-styles.css'
        ],
        // ...
    }
    // ...

# Supported CSS properties

DOCX Converter supports proper CSS inheritance with a set of whitelisted properties which can be used to style document content.

CSS properties like:

• color
• background-color
• font-size
• font-family
• text-align

can be applied to the following elements: h1, h2, h3, h4, h5, h6, p, span, td, th, strong, i, u, s, sub, sup, mark.

You can also position images using float CSS property, supporting left, right, and none values.

# Setting the page format

Consistency is an important factor. To make sure that the editor content and the generated Word file look exactly the same, you need to match their format settings. You can modify your existing stylesheet or use a new one, for example, format.css. By default the CKEditor Cloud Services HTML to DOCX converter is set to A4 format, but you may change this setting in your configuration.

Assuming that you want to create a document in the US Letter format, with the standard margins (19mm for each side), here is the example code you can use:

import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
import ExportWord from '@ckeditor/ckeditor5-export-pdf/src/exportword';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportWord, ... ],
        toolbar: [
            'exportWord', '|',
            // ...
        ],
        exportWord: {
            stylesheets: [
                'EDITOR_STYLES',
                // Add an external stylesheet after the 'EDITOR_STYLES' token.
                './styles/format.css'
            ],
            fileName: 'my-document.docx',
            converterOptions: {
                // Document format settings with proper margins.
                format: 'Letter',
                margin_top: '19mm',
                margin_bottom: '19mm',
                margin_right: '19mm',
                margin_left: '19mm',
            }
        }
    } )
    .then( ... )
    .catch( ... );

Now set the corresponding editor styles:

/* format.css */

/* Styles for the editable. */
.ck.ck-content.ck-editor__editable {
    /* US Letter size. */
    width: 215.9mm;
    /* Padding is your document's margin. */
    padding: 19mm;
    /* You don't want to change the size of the editor by applying the new padding values. */
    box-sizing: border-box;
    /* ... */
}

With these settings, the content in the generated Word file should have the same US Letter format layout as it has in the editor.

# Header and footer

The converter allows you to set the document’s header and footer in a similar way as you do this in your Microsoft Word or Google Docs files.

// Let's keep the CSS string as a variable to avoid unnecessary string duplication.
const templateCSS = '.styled { font-weight: bold; text-align: center; }'

const converterOptions = {
    header: [
        // Header template for all headers (without the `type` property).
        { html: '<div class="styled">Default header content</div>', css: templateCSS },
        // Header template only for the first page of the document.
        { html: '<div class="styled">First document page header content</div>', css: templateCSS, type: 'first' },
        // Header template for every even page of the document.
        { html: '<div class="styled">Every even page header content</div>', css: templateCSS, type: 'even' },
        // Header template for every odd page of the document.
        { html: '<div class="styled">Every odd page header content</div>', css: templateCSS, type: 'odd' }
    ],
    footer: [
        // Footer template for all footers (without the `type` property).
        { html: '<div class="styled">Default footer content</div>', css: templateCSS },
        // Footer template only for the first page of the document.
        { html: '<div class="styled">First document page footer content</div>', css: templateCSS, type: 'first' },
        // Footer template for every even page of the document.
        { html: '<div class="styled">Every even page footer content</div>', css: templateCSS, type: 'even' },
        // Footer template for every odd page of the document.
        { html: '<div class="styled">Every odd page footer content</div>', css: templateCSS, type: 'odd' }
    ],
}

As you can see, the header and footer options take an array of objects that define templates for the particular type of page. If you want to have consistent templates no matter the page, you can define only the default headers/footers template (NOTE: This setting misses the type property on purpose).

Regarding CSS, header and footer can be styled using the same supported properties as used for styling the whole document.

For more details, refer to the CKEditor Cloud Services HTML to DOCX converter’s documentation.

# Setting the base URL

To enable proper resolution of relative URLs for images and links, you need to pass the base_url option:

const conversionOptions = {
    base_url: 'https://ckeditor.com'
};

For an editor’s content like the one below:

<p><a href="/">Our company homepage</a></p>
<p><img src="/logo.svg" alt="Our logo"></p>

this option will result in resolving these URLs into their absolute forms:

• / will become https://ckeditor.com,
• /logo.svg will become https://ckeditor.com/logo.svg.

# Comments and suggestions

When your editor has collaboration features (like comments and track changes) enabled, the Export to Word feature will take care of setting the configuration needed by the CKEditor Cloud Services HTML to DOCX converter. But if for some reason you need to pass your own data, you can do this via the REST API converter options.

# Other

• By default, the generated Word file is encoded with UTF-8.

# Known issues

Not all CKEditor 5 plugins and features are compatible with export to Word at the moment. Feel free to contact us if you are interested in any of these features specifically. Here is a list of known issues:

# Unsupported plugins

• Media embed – Embedded media will not be included in the exported document.
• MathType – Supported partially. The plugin parses the data but not the formatting, losing some of the math operators and not reproducing a usable equation in the effecting file.

# Unsupported features

• Inline and block formatting suggestions – Such suggestions are not included in the exported document.
• Comments applied to whole widgets (e.g. tables) – Such comments are not included in the exported document.

# Common API

The ExportWord plugin registers:

• The 'exportWord' button.

• The 'exportWord' command implemented by ExportWordCommand.

  The command can be executed using the editor.execute() method. However, should the command be used directly (not via the toolbar button), the options need to be specified or gathered from the config. Otherwise the command will not execute properly.

  And example code to use the command directly should look like this:

  // Start generating a PDF file based on the editor content and plugin configuration.
  const config = editor.config.get( 'exportWord' );
  editor.execute( 'exportWord', config );