Document Template Development Notes¶

Here we collect general recommendations and best practices to develop document templates. In case you would like to include a specific notes, please let us know - any suggestions are appreciated.

Missing or Special Fonts¶

Issue: It may happen that certain fonts are not installed in the document worker (affecting PDF documents) or user’s device (affecting client-rendered documents like HTML or SVG). This may result in weird/incorrect characters appearing incl. rectangular shapes.

Recommendations: Include fonts via CSS/HTML, e.g. using the Google Fonts or other similar:

<head>
    <title>Data Management Plan</title>
    <meta charset="utf-8">
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,100..900;1,100..900&family=Open+Sans:ital,wght@0,300..800;1,300..800&display=swap" rel="stylesheet">
    <style>
        body { font-family: "Open Sans", sans-serif; }
    </style>
</head>

It is not recommended to add fonts as part of the document template for performance and usage reasons.

Misplaced Content in PDF¶

Issue: It may happen that content is placed over header/footer or incorrectly split between pages.

Recommendations: First, avoid incorrect HTML structures such as empty list items, nested paragraphs, tables without tbody etc. Then also make sure that the page, footer and header sizes are correctly set via CSS. Similarly, you can prevent page break using CSS. In case of issues, also refer to the WeasyPrint step or directly the WeasyPrint documentation.

Issues with PDF Formatting¶

Issue: PDF is rendered differently than if I check HTML in print view of browser.

Recommendations: This is done via Step: weasyprint thus the WeasyPrint library. Please check their documentation, recommendation and issues. It is also useful to search (e.g. via Google) specifically how to achieve certain styling/layouting in WeasyPrint.

Styling MS Word Documents¶

Issue: CSS and HTML styling is not appearing correctly in MS Word documents (transformed from HTML via the Pandoc step).

Recommendations:

CSS styles do not affect resulting MS Word documents as that is not possible with Pandoc. The Word document will use the matching styles based on certain HTML tags (e.g. <title>, <h1>, <p>, or <table>). You can adjust how those look by creating reference.docx document with desired styles incl. headers/footers. Ideal way is to download MS Word document generated, adjust styles as needed, and store it as the reference.docx document. Then, it can be simply added to the document template and used for the Pandoc step via args. Please check directly the relevant part of the Pandoc documentation.
HTML only supports heading levels up to <h6>, while MS Word supports more levels (up to 9). To set style for >6 level, you can set the style in reference.docx and use following code:

<div data-custom-style="Heading 7">
    <p>YOUR TITLE</p>
</div>

Note

In the reference.docx document, you need to go to Styles Pane and edit the styles there, other methods do not work. See the Pandoc documentation for more details.

Compressing Images in MS Word Documents¶

Issue: Uncompressed images in MS Word documents can significantly increase the file size, often making it much larger than the original HTML or PDF version.

Recommendations: In the reference.docx document, you can adjust the image compression level to reduce the file size. To do this, open the document reference.docx and click on an image. Then, navigate to Picture Format -> Compress Pictures in the Adjust group. In the dialog box, you can select the desired compression level. Alternatively, you can set the default compression level for all images in the document. This will ensure that images are compressed when the document is saved.