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.

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

# 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' ), {
        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
        }
    }
}

# 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. Available soon — contact us if you need this feature.

• config.exportPdf.converterOptions

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

# 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 = {
    header_html: '<div class="styled">Header content</div>',
    footer_html: '<div class="styled-counter"><span class="pageNumber"></span></div>',
    header_and_footer_css: '.styled { font-weight: bold; padding: 10px; } .styled-counter { font-size: 1em; color: hsl(0, 0%, 60%); }',
}

Note: To ensure the header or footer is displayed, the margin must be big enough to accommodate it.

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 to set the page format. In the second one, you can see how to use web fonts in your configuration.

# Styling the page format

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 have a my-editor-styles.css with your custom styling for the editor content that you want to include in the generated PDF file. Besides, you want to create a document in the US Letter format, with the standard margins (19mm for each side).

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',
                './styles/my-editor-styles.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:

/* my-editor-styles.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: [
                './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.

# 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' );