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

This feature is in beta version. It is free to use while in the beta phase.

This is a premium feature. Please contact us if you would like to purchase a license. Let us know if you have any feedback or questions!

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

The Flavorful Tuscany Meetup

Welcome letter

Dear Guest,

We are delighted to welcome you to the annual Flavorful Tuscany Meetup and hope you will enjoy the programme as well as your stay at the Bilancino Hotel.

Please find attached the full schedule of the event.

The annual Flavorful Tuscany meetups are always a culinary discovery. You get the best of Tuscan flavors during an intense one-day stay at one of the top hotels of the region. All the sessions are lead by top chefs passionate about their profession. I would certainly recommend to save the date in your calendar for this one!

Angelina Calvino, food journalist

Please arrive at the Bilancino Hotel reception desk at least half an hour earlier to make sure that the registration process goes as smoothly as possible.

We look forward to welcoming you to the event.

Victoria Valc signature

Victoria Valc

Event Manager
Bilancino Hotel

 

 

 

The Flavorful Tuscany Meetup Schedule

Saturday, July 14
9:30 AM - 11:30 AM

Americano vs. Brewed - “know your coffee” with: 

  • Giulia Bianchi
  • Stefano Garau
  • Giuseppe Russo
1:00 PM - 3:00 PM

Pappardelle al pomodoro - live cooking

Incorporate the freshest ingredients 
with Rita Fresco

5:00 PM - 8:00 PM Tuscan vineyards at a glance - wine-tasting 
with Frederico Riscoli

 

# 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( ... );

Read more about installing plugins.

# Configuration

For more technical details, please check the plugin configuration API.

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

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.

Keep in mind that you are not obligated to use .ck.ck-content selectors to style your content. If your implementation contains custom CSS classes, you can use them instead.

# 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( ... );

This example focuses only on preparing the editable to match the converter settings. Please keep in mind that as a result, the appearance of your editor may change. Depending on your editor type and implementation or even some inherited global styles like box-sizing, applying new padding values may change the size of the editor on your website.

For the purpose of this example, box-sizing: border-box was implemented to make sure that the editor’s width will not change.

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.

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