Export to PDF

The ExportPdf feature allows you to generate a PDF 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 PDF converter service. The service then generates a PDF document that can be downloaded by the user. This allows you to easily print your content to the PDF format.

The complementary pagination feature allows you to see where page breaks would be after the document is exported to PDF. 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 PDF file based on the editor content. Craft the document content in the WYSIWYG editor, then click the “Export to PDF” toolbar button to save it as PDF.

# How it works

The PDF export 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 PDF converter service. The service generates a PDF file and returns it to the user’s browser so they can save it in the PDF format on their disk.

The crucial aspect of this feature is its configuration. In order to ensure that the generated PDF looks as close as possible to the same content when it is displayed in the WYSIWYG editor, the feature must be carefully configured.

# 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 an editable format, using the export to Word feature will allow you to generate .docx files out of your editor-created content.
• If you would like to use the track changes feature and show suggestion highlights in the PDF, refer to the Saving data with suggestion highlights section.

# Before you start

After you purchase a license, follow the steps below, as explained in the Export to PDF 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 PDF plugin.

# Installation

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

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

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

import ExportPdf from '@ckeditor/ckeditor5-export-pdf/src/exportpdf';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        cloudServices: {
            tokenUrl: 'https://example.com/cs-token-endpoint'
        }
        plugins: [ ExportPdf, ... ],
        toolbar: [
            'exportPdf', '|',
            ...
        ],
        exportPdf: {
            stylesheets: [
                './path/to/fonts.css',
                'EDITOR_STYLES',
                './path/to/style.css'
            ],
            fileName: 'my-file.pdf',
            converterOptions: {
                format: 'A4',
                margin_top: '20mm',
                margin_bottom: '20mm',
                margin_right: '12mm',
                margin_left: '12mm',
                page_orientation: 'portrait'
            }
        }
    } )
    .then( ... )
    .catch( ... );

# Configuration

The configuration is the key to allow the HTML to PDF converter service to generate PDF documents that look as close as possible to the content created in the rich-text editor.

The configuration consists of 3 main parts:

• The converter options that tell the HTML to PDF converter service what is the format of the page (A4, Letter), the page orientation, etc.
• The stylesheets that should be sent to the service. They allow styling the content in the PDF document with the same styles that are applied to the content in the editor.
• The content styles used in the editor when it is rendered on the page.

These options need to stay in sync. For example:

• The stylesheets sent to the service must define the same typography that is used in the editor.
• The editor’s content container should be styled in a way that it reflects the page size and margins defined in the converter options.
• All web fonts defined on the page where the editor is used must be sent to the service as well.

Read on to learn how to achieve this.

# Default configuration

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

{
    exportPdf: {
        stylesheets: [ 'EDITOR_STYLES' ],
        fileName: 'document.pdf',
        converterUrl: 'https://pdf-converter.cke-cs.com/v1/convert',
        converterOptions: {
            format: 'A4',
            margin_top: '0',
            margin_bottom: '0',
            margin_right: '0',
            margin_left: '0',
            page_orientation: 'portrait',
            header_html: undefined,
            footer_html: undefined,
            header_and_footer_css: undefined,
            wait_for_network: true,
            wait_time: 0
        },
        dataCallback: ( editor ) => editor.getData()
    }
}

# Plugin options

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

• config.exportPdf.stylesheets

  You can set the paths (relative or absolute URLs) to the stylesheets that should be included during the HTML to PDF 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.exportPdf.stylesheets documentation.

• config.exportPdf.fileName

  Sets the name for the generated PDF file (together with the extension). The default name is document.pdf.

• config.exportPdf.converterUrl

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

• config.exportPdf.tokenUrl

  A token URL or a token request function. This field is optional and should be used only when a different tokenUrl is required for the export to PDF feature.

• config.exportPdf.converterOptions

  The plugin allows you to provide a custom HTML to PDF converter configuration.

• config.exportPdf.dataCallback

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

# HTML to PDF converter features

# Images

Currently, the plugin only supports absolute URLs as well as the Base64 format for images. See the converter documentation.

# Web fonts

If you are using web fonts via an @import or @font-face declaration, you can pass the path(s) to the .css file(s) containing them to the config.exportPdf.stylesheets. Remember that the order of the provided paths matters — stylesheets with web font declarations should be listed first. For more technical details, please check the API documentation and converter documentation.

# 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.

const converterOptions = {
    margin_top: '15mm',
    margin_bottom: '15mm',
    margin_right: '15mm',
    margin_left: '15mm',
    header_html: '<div class="styled">Header content</div>',
    footer_html: '<div class="styled-counter"><span class="pageNumber"></span></div>',
    header_and_footer_css: '#header, #footer { background: hsl(0, 0%, 95%); } .styled { font-weight: bold; text-align: center; } .styled-counter { font-size: 1em; color: hsl(0, 0%, 60%); }',
}

Note:

• To ensure that the header or footer is displayed, the margin must be big enough to accommodate it. In the code above, margin_top corresponds with the header and margin_bottom — with the footer. In this example the height of both elements will equal 15mm.
• You can set a background for the header and footer. To achieve this, use the #header or #footer selector in the header_and_footer_css option. Do not use these IDs in the header_html or footer_html options to avoid duplication. These elements are provided by the HTML to PDF converter.

As you can see in the example above, you can even set the pageNumber. But there is more — for details, refer to the converter’s documentation.

# Other

• By default, the generated PDF file is encoded with UTF-8.
• By default, the converter sets color-adjust: exact;. This means that your PDF document will preserve colors, images, and styles as you can see them in the editor.

# Examples

Check out some configuration examples that will show you how to customize the export to PDF feature. In the first example, you will learn how add custom styling. The second example will show you how to set the page format. In the third one, you can see how to use web fonts in your configuration.

# Re-using custom editor styling

The default configuration of the ExportPdf plugin attaches the default editor content styles to the HTML content sent to the converter.

However, if you need, you can also set paths to additional CSS files. Let us assume that you already have a my-custom-editor-styles.css with your custom styling for the editor content that you use on your website, but you also want to include these styles in the generated PDF file.

Here is the example code:

import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
import ExportPdf from '@ckeditor/ckeditor5-export-pdf/src/exportpdf';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportPdf, ... ],
        toolbar: [
            'exportPdf', '|',
            // ...
        ],
        exportPdf: {
            stylesheets: [
                'EDITOR_STYLES',
                // Add an external stylesheet after the 'EDITOR_STYLES' token.
                './styles/my-custom-editor-styles.css'
            ],
            fileName: 'my-document.pdf'
        }
    } )
    .then( ... )
    .catch( ... );

This is how the corresponding editor styles may look like:

/* my-custom-editor-styles.css */

/* Custom link color. */
.ck.ck-content a {
    color: purple;
}

/* Custom header styling. */
.ck.ck-content h1 {
    border-bottom: 2px solid;
}

/* Another custom styling... */
/* ... */

With these settings, the content in the generated PDF file should have the same styling as it has in the WYSIWYG editor.

# Setting the page format

Consistency is an important factor. To make sure that the editor content and the generated PDF 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 PDF 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 ExportPdf from '@ckeditor/ckeditor5-export-pdf/src/exportpdf';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportPdf, ... ],
        toolbar: [
            'exportPdf', '|',
            // ...
        ],
        exportPdf: {
            stylesheets: [
                'EDITOR_STYLES',
                // Add an external stylesheet after the 'EDITOR_STYLES' token.
                './styles/format.css'
            ],
            fileName: 'my-document.pdf',
            converterOptions: {
                // Document format settings with proper margins.
                format: 'Letter',
                margin_top: '19mm',
                margin_bottom: '19mm',
                margin_right: '19mm',
                margin_left: '19mm',
                page_orientation: 'portrait'
            }
        }
    } )
    .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 PDF file should have the same US Letter format layout as it has in the editor.

# Providing web font styles

This time you want to add a web font to your plugin. Let us assume that the editor is used on a page with a certain typography, so the content in the editor inherits the font styles from the page. As such, these styles need to be passed to the HTML to PDF converter service.

The example below uses a web font from the Google Fonts service. For your convenience, the @import declaration and any font styles needed for your website are kept in the separate file, for example: fonts.css.

/* fonts.css */

@import url('https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;700&display=swap');

html, body {
    font-family: "Source Sans Pro", sans-serif;
    /* ... */
}

/* ... */

This allows you to use the web font settings in the plugin, without any additional tweaks. Just pass the path to the file in the config.exportPdf.stylesheets configuration option.

It is important to remember that the order matters here. Font declarations should be at the very beginning of the stylesheets’ array, otherwise there is no guarantee that the font styling will be applied to the PDF file. Refer to the config.exportPdf.stylesheets API documentation for more details.

import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
import ExportPdf from '@ckeditor/ckeditor5-export-pdf/src/exportpdf';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportPdf, ... ],
        toolbar: [
            'exportPdf', '|',
            ...
        ],
        exportPdf: {
            stylesheets: [
                // Add the external stylesheet before the 'EDITOR_STYLES' token.
                './styles/fonts.css',
                'EDITOR_STYLES'
            ],
            // ...
        }
    } )
    .then( ... )
    .catch( ... );

Thanks to this, the editor inherits the font settings and you can be sure that they will be applied in the generated PDF file as well.

Take a look at another example of a fonts.css file. Suppose that your website uses the Source Sans Pro font as before but this time you want the Inter font to be used in the WYSIWYG editor. So the file should look like this:

/* fonts.css */

/* Import the web font for your website. */
@import url('https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;700&display=swap');
/* Import the web font for your editor. */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap');

/* Use the Source Sans Pro web font in your website. */
html, body {
    font-family: "Source Sans Pro", sans-serif;
    /* ... */
}

/* Use the Inter web font in your editor. */
.ck.ck-content.ck-editor__editable {
    font-family: "Inter", sans-serif;
    /* ... */
}

/* ... */

Having the file set like this for your website and just re-using it in config.exportPdf.stylesheets makes the whole setup as simple as possible.

# Known issues

Not all CKEditor 5 plugins and features are compatible with export to PDF at the moment. Here is a list of known issues:

• Media embed – Not supported.
• MathType – Not fully supported yet. Right now the plugin parses the data but not the formatting. Feel free to contact us if you are interested in this feature.

# Common API

The ExportPdf plugin registers:

• The 'exportPdf' button.

• The 'exportPdf' command implemented by ExportPdfCommand.

  The command can be executed using the editor.execute() method:

  // Start generating a PDF file based on the editor content and plugin configuration.
  editor.execute( 'exportPdf' );