Written by
Adina Milica
, Graphic & UI/UX Designer
Looking to improve how your XWiki pages are exported to PDF?
Whether you’re managing technical documentation, internal wikis, or public knowledge bases, customizing your XWiki PDF templates lets you create professional, branded documents ready for sharing, archiving, or printing.
In this step-by-step tutorial, you’ll learn how to create and customize a PDF template in XWiki — from setting up the template structure using Velocity and XHTML to styling it with CSS and adding dynamic information.
- Video tutorial covering everything that follows
- How to create a PDF template in XWiki?
- How to make your PDF template usable in XWiki?
- How to export a page to PDF?
- Can you edit a PDF template in XWiki?
- How to add images to my PDF template in XWiki?
- How to add dynamic information to my PDF template cover in XWiki?
- How to add company branding or styling to my PDF template cover in XWiki?
Video tutorial covering everything that follows
In the following tutorial, we'll build a modern PDF template with a branded cover.
How to create a PDF template in XWiki?
You can create a PDF template from any page in your wiki. Good practice would be to keep all your PDF templates related to one topic under a page that relates to that topic. This is only to help you find it at a later time.
#1 Click Create from the top right of any page.
#2 Set a name for the template you want to create. For example, I'll name mine: "Development Team Report".
#3 Select from the right side, in the Template section, the page type titled "PDF Template".
#4 Click Save. You will be directed to the PDF Template Page. What you see is not exactly how a document will look like when you export it with this PDF template. We can edit it so we add more information and styling. For this, see the next section.
How to make your PDF template usable in XWiki?
Now that you've created your PDF template, you probably want to check out how it looks by default to get an idea of your starting point.
To find it there, you have to add the created PDF template in the usable PDF templates list for your wiki. For the video tutorial, see the next video in this page.
Let's do this together:
#1 Go to Administer Wiki (Global Administration) > Content > PDF Export.
#2 In the Configuration section, click on the Templates field.
In that multi-select field, you'll already find the Default template.
In the dropdown that opened, select your recently created template. In my case, Development Team Report.
#3 Scroll down the page and click Save.
Your PDF template is now usable. ✅
How to export a page to PDF?
Now that you can use your recently created PDF Template, you can go on any page that you want to export to PDF.
#1 Open the page menu through the 3 dots in the right corner.
#2 Click Export.
#3 Choose PDF from the formats available.
#4 Select the pages you want to include in the export.
#5 Click the Export button.
#6 From the Template field, choose the template you want.
Can you edit a PDF template in XWiki?
TL;DR, yes.
Okay, in the previous step, you made your template usable and you exported a page to see your template.
Sure, it works, but let's add a bit more info and company branding magic to it. ✨
#1 Go to your PDF template page and click Edit.
When you enter the Edit mode of your template, you will be able to edit the velocity code of:
- The template's cover
- Table of Contents
- Header
- Footer
I know the phrase "edit your velocity code" sounds a bit scary if you're not a dev, but, I promise, it's simple. You'll mostly edit HTML and add dynamic info very easily with the help of the next section.
How to add images to my PDF template in XWiki?
The HTML Include the following code in your velocity code (in edit mode of your PDF template, in your cover for example). The CSS class "image" can be renamed in any way you want, just make sure to use the same name when defining your CSS class. Replace the "#" with the link to your needed image. | Styling You can add/edit this following CSS by following the steps from this section of the tutorial. |
<img class="image" src="#"> | .image { border-radius: 20px; height: 200px;} |
How to add dynamic information to my PDF template cover in XWiki?
| Use cases | The HTML & Velocity Include the following code in your velocity code (in edit mode of your PDF Template, in your cover for example). The CSS class "name-class" can be renamed in any way you want, just make sure to use the same name when defining your CSS class. The bolded text is the velocity code.
|
Show the document's title. (present in the template by default) | <h1 class="name-class"> $escapetool.xml($tdoc.plainTitle) </h1> |
| Show the document's wiki pretty name. | <div class="author-cover"> $services.wiki.getCurrentWikiDescriptor().getPrettyName() </div> |
| Show the full name of the creator of the document. | <div class="author-cover"> #displayUser($tdoc.authorReference {'useInlineHTML': true}) </div> |
Show the document's creation date. | <div class="date-cover">$xwiki.formatDate($tdoc.getCreationDate(), "MMMM, yyyy")</div> |
| Show the document's last edit date. | <div class="name-class"> $xwiki.formatDate($tdoc.date, "MMMM, yyyy") </div> |
How to add company branding or styling to my PDF template cover in XWiki?
We need to access the styling side of the PDF Template Page.
Go to the URL bar at the top of your browser window.
#2 Delete the "" from the end of your URL and add at the end: "?editor=object "
#3 Your new screen should look like this (well, minus our explanations):
What is Objects of type XWiki.PDFExport.TemplateClass?
The velocity part. This is where we define the structure and unstyled content of the template's cover, table of contents, header and footer. You already saw this in the simple Edit mode, but under a slightly different interface. Opening the section right under it (PDFExport.TemplateClass 0: {{velocity}}...), you can edit each separately.
What is Objects of type XWiki.StyleSheetExtension?
This is where the CSS sheets are stored, where the pretty magic happens. Every PDF template comes with a default CSS sheet that helps with basic styling.
To add styling, we'll need both.
- The velocity part for adding classes to each HTML element that we add to the structure.
- The CSS part to define each of those classes that we added.
Center everything
| The HTML & Velocity Code | Styling |
| Put all your divs in one big div in the velocity code of your PDF template. | The big div can have the following class: {display:flex; flex-direction:column; justify-content:center;} Each div in this big div will be centered, but if they have their own elements, those elements need to be centered in their individual div. Learn more about CSS flexbox. |
Have columns on your cover
Use CSS flexbox or grids to create columns.
Other quick use cases for styling your cover
- Bolding text elements: add font-weight: bold or, if that doesn't work, it means there's another class overwriting it and you could just add <b></b> around the html element you want to bold out
- Capitalizing text elements: add text-transform: uppercase
- Changing text sizes: add font-size: 50px
- Change spacing between elements: add margin-top: 20px; for more space upwards or margin-bottom: 20px; for more space downwards
- Change text color: add color: red
- Show username without avatar: .user-avatar{ display:none; }
- Show links without link styling: a {text-decoration: none; color:black; }
