CSS Cross-References for HTML to PDF Conversion

Cross-references are commonly used in printed documents or ebooks to create text such as "[See Page 45]". Often, with dynamically generated content, you don’t know before rendering on which page a chapter or section will begin. Cross-references are particularly useful for adding page numbers to table of contents.

Specifications for CSS Cross-References

The CSS Generated Content for Paged Media draft defines the CSS cross reference functions. Unfortunately, these specifications aren’t supported by browser engines such as Google Chrome or browser-based open-source HTML to PDF tools. Full support for the generated content module is a unique advantage offered by DocRaptor’s HTML to PDF API.

How to Reference a Page Number

CSS cross-references are created by linking to another part of the PDF with a standard <a> link. The reference is inserted with a combination of an ::after pseudo-element, the content property, and the target-counter function with the following syntax:

<style>
a.cross-reference::after {
        content: " [See page " target-counter(attr(href), page) "]"
    }
</style>

The <a class=”cross-reference” href=”#html-to-pdf”>HTML to PDF chapter</a> contains more information on the DocRaptor API.

<h1 id=”html-to-pdf”>HTML to PDF</h1>

Assuming that <h1> actually started on page number 41, this would generate as:

The HTML to PDF chapter [See page 41] contains more information on the DocRaptor API.

All links must be to internal links in the form of a unique identifier or anchor (such as #chapter-one). External links will not work. The target element must also use the href attribute (or you can change the attribute used in the target-counter function).

Reference a Text or Title

You can also reference the text of a link target, instead of the page number. This can provide context such as:

The introductory chapter [See HTML to PDF on page 32] contains more information on the DocRaptor API.

To create that line, we’ll use both the target-content function and the target-counter function. Here's the code:

<style>
a.cross-reference::after {
        content: " [See” target-content(attr(href) “ on page “ target-counter(attr(href), page) "]"
    }
</style>

The <a class=”cross-reference” href=”#html-to-pdf”>introductory chapter</a> contains more information on the DocRaptor API.

<h1 id=”html-to-pdf”>HTML to PDF</h1>

Custom Counter References

All the previous code examples show cross references to page numbers, but the same functionality can be used to count chapters or any other sections.

Use a counter reset

Create a custom counter using the counter-reset property. You can name it anything, but we'll call this one "chapter":

h1 { counter-reset: chapter; }

Reference your new counter

Then, use the new chapter counter in the second parameter of the target-counter function:

a.chapter-reference::after {
  content: " [See chapter " target-counter(attr(href), chapter) "]"
}

Removing Default Cross Reference Link Styling

In printed material, you probably may want the link elements styled the same as the PDF output text (whereas most web page links are blue and underlined). Use standard CSS to change the link properties to remove underlines and inherit the default body text color:

a.cross-reference {
  color: inherit;
  text-underline: none;
}