Export to PDF

The export to PDF feature lets you generate a PDF file directly from the editor.

# Demo

The demo below lets you generate a PDF file based on the editor’s content. Edit the document, then click the export to PDF toolbar button to save the content as a 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 this format on their disk.

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

The complementary pagination feature allows you to see where page breaks would be after you export the document to PDF. Thanks to the live preview, the user can fine-tune the structure of the output document when editing it. The pagination feature also shows you the page count and lets you navigate between the document pages.

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

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportPdf, /* ... */ ],
        toolbar: [ 'exportPdf', '|', /* ... */ ],
        exportPdf: {
            tokenUrl: 'https://example.com/cs-token-endpoint',
            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 style sheets 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 rendered on the page.

These options need to stay in sync. For example:

• The style sheets 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 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: '0mm',
            margin_bottom: '0mm',
            margin_right: '0mm',
            margin_left: '0mm',
            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 style sheets 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 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. You can see it called in the default configuration listing above.

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

  // Dynamic file name.
  const exportPdfConfig = {
      fileName: () => {
          const articleTitle = document.querySelector( '#title' );
          return `${ articleTitle.value }.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 you should use it when you require a different tokenUrl for the export to PDF feature. You can skip this option if you use the cloudServices configuration to provide the same tokenUrl. In most cases you will probably want to provide the token in cloudServices, as other plugins like Easy Image or real-time collaboration will use this token as well. In this guide, to explicitly show that this value is needed, we leave it the inside exportPdf configuration.

• 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 sent to the conversion service. You can use this option to customize the editor’s data. For example, use this setting to enable highlighting tracked changes in the exported PDF file.

      dataCallback: editor => editor.getData( {
          showSuggestionHighlights: true
      } ),
  

# 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. The order of the provided paths matters – you should list style sheets with web font declarations first. For more technical details, check the API documentation and converter documentation.

# Header and footer

The converter lets you set the document’s header and footer similarly to Microsoft Word or Google Docs.

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.
• The generated document can be watermarked. See the example and demo in the section below.

# 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 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 to, 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';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportPdf, /* ... */ ],
        toolbar: [ 'exportPdf', '|', /* ... */ ],
        exportPdf: {
            stylesheets: [
                'EDITOR_STYLES',
                // Add an external style sheet 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 the same, you need to match their format settings. You can change your existing style sheet 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';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportPdf, /* ... */ ],
        toolbar: [ 'exportPdf', '|', /* ... */ ],
        exportPdf: {
            stylesheets: [
                'EDITOR_STYLES',
                // Add an external style sheet 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 do not 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 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 a 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.

The order matters here. Font declarations should be at the beginning of the style sheets’ 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';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ ExportPdf, /* ... */ ],
        toolbar: [ 'exportPdf', '|', /* ... */ ],
        exportPdf: {
            stylesheets: [
                // Add the external style sheet before the 'EDITOR_STYLES' token.
                './styles/fonts.css',
                'EDITOR_STYLES'
            ],
            // More configuration of the export to PDF feature.
            // ...
        }
    } )
    .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. 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.

# Adding a watermark to the document

Apart from adding a header and a footer, there is also the possibility of adding a watermark to the generated document. This can be achieved by utilizing config.exportPdf.dataCallback.

To do this, you need to get the data that is being sent to the converter first and update it with a watermark markup:

exportPdf: {
    // More configuration of the export to PDF.
    // ...
    dataCallback: ( editor ) => {
        return `
            ${ editor.getData() }
            <div class="watermark">Draft document</div>
        `;
    },
    // More configuration of the export to PDF.
    // ...
}

Then update the custom CSS file with the proper styles:

.watermark {
    font-size: 50px;
    opacity: 0.5;
    color: black;
    position: fixed;
    left: 20%;
    top: 50%;
    transform: rotate(25deg);
    letter-spacing: 10px
}

Below you can see a simplified demo with the final result. Click the toolbar button to generate the document with a watermark.