Edit online

Cover (Title) Page

Customizing the cover page is one of the most requested customization requests.

Edit online

Cover Page - XML Fragment

The merged map file contains the <oxy:front-page> element, as a child of the root element. This contains the metadata and an <oxy:front-page-title> element with the title structure.

<bookmap xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/" ...>
  <oxy:front-page xmlns:oxy="http://www.oxygenxml.com/extensions/author">
   <bookmeta xmlns:dita-ot="http://dita-ot.sourceforge.net/ns/201007/dita-ot"
            ...
   </bookmeta>
   <oxy:front-page-title>
    <booktitle xmlns:dita-ot="http://dita-ot.sourceforge.net/ns/201007/dita-ot"
       class="- topic/title bookmap/booktitle ">
       <booklibrary class="- topic/ph bookmap/booklibrary ">Retro Tools</booklibrary>
       <mainbooktitle class="- topic/ph bookmap/mainbooktitle ">Tasks</mainbooktitle>
       <booktitlealt class="- topic/ph bookmap/booktitlealt ">Product tasks</booktitlealt>
    </booktitle>
   </oxy:front-page-title>
</oxy:front-page>

For the DITA Map PDF - based on HTML5 & CSS transformation type, the merged map is further processed resulting in a collection of HTML5 <div> elements. These elements preserve the original DITA @class attribute values and add a new value derived from the DITA element name.

<div class="- map/map bookmap/bookmap bookmap" ... >    
   <div class=" front-page/front-page front-page">       
      <div class="- map/topicmeta bookmap/bookmeta boometa">
        ...
      </div>     
     <div class=" front-page/front-page-title front-page-title">
       <div class="- topic/title bookmap/booktitle booktitle">
         <div class="- topic/ph bookmap/booklibrary booklibrary">Retro Tools</div>
         <div class="- topic/ph bookmap/mainbooktitle mainbooktitle">Tasks</div>
         <div class="- topic/ph bookmap/booktitlealt booktitlealt">Product tasks</div>
      </div>
...
Edit online

Cover Page - Built-in CSS rules

The element with the class frontpage/frontpage is associated with a page named front-page with no headers or footers. The front page title is styled with a bigger font. The built-in CSS rules are in [PLUGIN_DIR]/css/print/p-front-page.css.

@media print {

    *[class~="front-page/front-page"] {
        page: front-page;
    }


    /* Prevents the front-page title margin collapsing */
    *[class~="front-page/front-page"]::before(1000) {
      display:block;
      content:"\A";
      font-size:0;
    }

    *[class~="front-page/front-page-title"] {
        display:block;
        text-align:center;
        margin-top:3in;
        font-size:2em;
        font-family:arial, helvetica, sans-serif;
        font-weight:bold;
    }

    @page front-page {    	
        @top-left-corner    {          content:none }
        @top-left           {          content:none }
        @top-center         {          content:none }
        @top-right          {          content:none }
        @top-right-corner   {          content:none }
        @bottom-left-corner {          content:none }
        @bottom-left        {          content:none }
        @bottom-center      {          content:none }
        @bottom-right       {          content:none }
        @bottom-right-corner{          content:none }
    }
}
Note: This is listed solely for illustration purposes, as the plugin might use something different.
Edit online

How to Add a Background Image for the Cover

The simplest way is to create an SVG image as large as the entire physical page and set it as the background for the front-page. This makes it easy to accomplish a good positioning of the graphical elements or artwork. In the foreground, you can place text fragments using a series of :after pseudo-elements bound to the front page title.

To set the size to an SVG image, you should specify the @width and @height attributes on the <svg> root element using specified unit values (in, cm, etc.) This should be enough only if all the coordinates from your drawing have unit identifiers.

If you are using unit-less coordinates in your drawing like the following:
<polygon points="17.78 826.21 577.51 ....
Next, make sure you also specify the @viewBox attribute on the <svg> root element that defines the abstract rectangle that contains the drawing:
<svg xmlns="http://www.w3.org/2000/svg" width="8.5in" height="11in" viewBox="0 0 600 850">

The following SVG document has the @width, @height, and @viewBox attributes. The width and height have physical units (in inches), while the view box and rectangle coordinates are unit-less.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" 
       "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg xmlns="http://www.w3.org/2000/svg" width="8.5in" height="11in" viewBox="0 0 110 110">
  <desc>A gradient as big as a page.</desc>
  <defs>
    <linearGradient id="lc"
      x1="0%" y1="0%"
      x2="0%" y2="100%"
      spreadMethod="pad">
      <stop offset="0%"   stop-color="#00DD00" stop-opacity="1"/>
      <stop offset="100%" stop-color="#00AA00" stop-opacity="1"/>
    </linearGradient>
  </defs>    
  <rect x="5" y="5" width="100" height="100" rx="10" ry="10"
    style="fill:url(#lc);
    stroke: #005000;
    stroke-width: 3;"/>
  <text x="33%" y="50%"  color="#FFFFAA"> Sample </text>
</svg>

This example shows a gradient. It is the size of a US-LETTER page and can be used in a publication using this page size.

Note: You can use raster image formats (such as PNG or JPEG), but it is best to use vector images (such as SVG or PDF). They scale very well and produce better results when printed. In addition, the text from these images is searchable and can be selected (if the glyphs have not been converted to shapes) in the PDF viewer.

In your customization CSS, add the following:

@page front-page {
    background-image: url("us-letter.svg");
    background-position: center;
    background-repeat: no-repeat;
    background-size: 100% 100%;
}

For smaller artworks, you can use background-position with percentage values to position and center the artwork (for example, a company logo):

@page front-page {
    background-image:url("company-logo.svg");
    background-position:50% 5%; /* The first is the alignement on the X axis, the second on the Y axis.*/
    background-repeat:no-repeat; 
}
Note: The text from the SVG or PDF background images is searchable in the PDF reader.

How to Use Different Background Cover Images Based on Bookmap or Map Info

It is common to use the same CSS file for customizing multiple publications, and you may need to set a different cover for each of them. The solution is to use an XPath expression to extract some information from the document, and based on that, select the SVG images.

@page front-page {
    background-image: url(oxy_xpath("\
		if(//*[contains(@class, ' topic/prodname ')][1] = 'gardening') then 'bg-gardening.svg' else\
		if(//*[contains(@class, ' topic/prodname ')][1] = 'soil') then 'bg-soil.svg'\
		else 'bg-default.svg'\
    "));
    background-position:center;
}

The backslash (\) is used to continue the expression string on the subsequent lines (there should be no spaces after it). For more use cases solved using XPath, see: Metadata.

Edit online

How to Change Styling of the Cover Page Title

Match the front page title element in your customization CSS based on its class attribute:
*[class ~= "front-page/front-page-title" {
  margin-top: 1in;  
  font-size: 3em;
}
Important: Make sure the sum of the top and bottom margins and paddings for this element do not exceed the physical dimension of the page. If this happens, an extra blank page may appear before the cover page. Usually, it is enough to specify only the top margin.
Edit online

How to Add Text to the Cover Page

If you need to add arbitrary text to the cover page, you can use the front page title element as an anchor and add as many blocks of text as you need after it, and style them differently.

In your customization CSS, add the following:

*[class ~= "front-page/front-page-title"]:after(1) {
    display:block;
    content: "DRAFT VERSION";
    font-size: large;
    color: red;
    text-align:center;
}

*[class ~= "front-page/front-page-title"]:after(2) {
    display:block;
    content: "DO NOT DISTRIBUTE WITHOUT PERMISSION";
    font-size: large;
    color: red;
    text-align:center;
    font-style: italic;
}

The result is:

Screenshot of a publication front page

To use content from the document, you can use the oxy_xpath function in the content property. For a more complex example, including the generation of a new page for the synthetic :after elements, see: How to Show Metadata in the Cover Page.

Edit online

How to Add a Specific Number of Empty Pages After the Cover Page

In your customization CSS, add the following CSS rules:

@page my-blank-page { 
    /* Hide the page numbers */
    @top-left {content: none};
    @top-right {content: none};
}

*[class ~= 'front-page/front-page']:after(1){
    page:my-blank-page;
    display:block;    
    content: '\2002';
    color:transparent;
    page-break-after:always;
}

*[class ~= 'front-page/front-page']:after(2){
    page:my-blank-page;
    display:block;    
    content: '\2002';
    page-break-after:always;
}

*[class ~= 'front-page/front-page']:after(3){
    page:my-blank-page;
    display:block;    
    content: '\2002';
    page-break-after:always;
}
Note: The \2002 character is a space that is not shown on the pages, but gives a value for the content property.
Edit online

How to Remove the Cover Page and TOC

If you need to hide or remove the cover page, the table of contents or other structures, match the elements with a "front-page/front-page" and "toc/toc" classes in your customization CSS:

*[class ~= 'map/map'] > *[class ~= 'toc/toc'] {
    display:none !important;
}
*[class ~= 'map/map'] > *[class ~= 'front-page/front-page']{
    display:none !important;
}
*[class~='topic/topic'][is-chapter] {
    -oxy-page-group : auto;
}