docusaurus-plugin-papersaurus

Plugin for Docusaurus v2 to generate PDF files including table of contents and a cover page.

The plugin is creating a PDF file for each individual document as well as a PDF file for any section and subsection found in sidebar and also one overall PDF file containing all sections.

Optionally the plugin can add a download button to the documentation website which opens a menu with download links for the PDF files of current chapter, current sections and the overall PDF file.

Introduction

This plugin is ported from existing papersaurus project built for Docusaurus 1.x to use in Docusaurus 2.x.

It is a Docusaurus 2.x plugin and can be triggered automatically after docusaurus builds or on docusaurus command line.

It uses Puppeteer to convert html pages to PDF.

Please note

1. Puppeteer does not yet support individual headers / footers for the cover page. Therefore this plugin generates a PDF with just uses easy-pdf-merge See this SO question

2. Puppeteer does not yet support the generation of TOCs. See this feature request and this Chromium bug. Therefore this package renders TOC and content once with placeholder page numbers, reads the page of every heading from that PDF, and renders the document again with the real page numbers. The TOC entries are links, and the PDF carries an outline (bookmarks) built from the headings.

Installation

yarn add docusaurus-plugin-papersaurus

or

npm install docusaurus-plugin-papersaurus --save

Configuration

Then adapt your docusaurus.config.js with the following block:

plugins: [
    [
      'docusaurus-plugin-papersaurus',
      {
        keepDebugHtmls: false,
        sidebarNames: ['someSidebar'],
        addDownloadButton: true,
        autoBuildPdfs: true,
        ignoreDocs: ['licenses'],
        author: 'Author name'
      },
    ],
  ],

autoBuildPdfs

Set this parameter to true, if you want the plugin to automatically build the PDF files after each docusaurus build. If this is not set the environment variable BUILD_PDF needs to be set before running docusaurus build.

Default: true

keepDebugHtmls

The plugin creates one temporary HTML file per generated PDF file that is then converted using Puppeteer to a PDF file. This HTML file also contains the table of contents including page numbers. After generating the PDF file, these temporary HTML files are deleted. You may want to keep these HTML files to debug your printing CSS file in a browser.

Set this parameter to true to keep the files.

Default: false

puppeteerTimeout

Large PDFs might cause a timeout error on puppeteer. Use this parameter to set the puppeteer timeout in ms. It applies to loading the site, setting the content and printing the PDF.

Default: 30000

concurrency

Number of PDFs rendered in parallel. Section and complete PDFs are large; too many parallel renders exhaust the machine and run into timeouts.

Default: the number of CPUs, at most 4

sidebarTitles

Title of each sidebar's PDF, keyed by sidebar name. The value is a string or a map from locale to string. Without a title the sidebar name is used. Before 3.6.5 every sidebar PDF was titled with the projectName and all of them were written to the same file.

  sidebarTitles: {
    setupSidebar: { en: 'Setup', de: 'Einrichtung' },
    apiSidebar: 'API',
  },

The file name of a sidebar's PDF is derived from the sidebar name, e.g. setup-complete.pdf for setupSidebar.

Default: {}

completePdf

Generates one additional PDF over all sidebars and offers it as the "complete version" in the download menu of every page, including the site root (baseUrl). Each sidebar's PDF is then listed as a section.

  completePdf: {
    title: { en: 'Complete documentation', de: 'Gesamtdokumentation' },
    fileName: 'complete',
  },

title is a string or a map from locale to string, fileName (without extension) defaults to complete.

Default: false

structureBySidebar

Structures the PDFs like the sidebar instead of giving every page its own top level:

• every page sits at its sidebar depth; its headings move down accordingly (the h1 of a page two levels deep becomes an h3, capped at h6)
• categories without a page of their own get a heading with their label
• page titles no longer carry their parent titles in front ("Admin / Gateway / Key Management")
• the TOC nests along the sidebar (page titles plus their h2 and h3), and so do the PDF bookmarks
• only top-level headings (h1) start a new page, so the PDFs get considerably shorter

Style the shifted headings with your print CSS; the lower levels (h4-h6) should not get smaller than the body text.

Default: false

numberPagesAfterToc

Renders the TOC separately from the content, so the page numbers start at 1 on the first content page and the TOC pages are not counted; the TOC entries show these numbers. The TOC links still jump to their headings, and the bookmarks come from the content.

The page functions (getPdfCoverPage, getPdfPageHeader, getPdfPageFooter) get the part they render as sixth argument: 'cover', 'toc' or 'content'. Leave the page number out of the footer for 'toc'; the default footer does.

Default: false

sidebarNames

The plugin is using your sidebars.js file to find the sections and documents. Since the file can contain multiple sidebars, add the name(s) of the sidebar(s) that should be used to generate files. If none is specified all will be used.

Default: []

versions

Specify documentation versions to generate pdfs for. If none is specified pdfs will be generated for all versions.

Default: []

productVersion

In case the documentation is not versioned, but an external (product) version should be added to the PDFs, inject it using this parameter.

Default: ""

subfolders

If you are using multiple sidebars your files are located in different subfolders. Enter the names of the subfolders located in your docs folder. In case your main sidebar is directly in the docs directory enter an empty string and the names of the other folders.

Example for different directories for the sidebars:

  subfolders: ['mainDoc', 'otherDoc'],

Example if the main sidebar content is located directly in /doc:

  subfolders: ['', 'otherDoc'],

Default: []

productTitles

Add the product name for the different sidebars. This title will be included on the cover page as well as in the header.

The following example shows the configuration if you want to display the product title for the second sidebar but not the first:

  sidebarNames: ['someSidebar', 'otherSidebar'],
  productTitles: ['', 'Other'],

This would display the 'Other' name on the cover page and the header for all documentation downloaded from the 'otherSidebar' sidebar but not from the 'someSidebar'

Default: []

addDownloadButton

Set this parameter to true, if you want the plugin to add a PDF download button to the documentation website. The button appears on every page that has an entry in the generated pdfs.json, docs pages and (with completePdf) the site root.

Default: true

downloadButtonText

Use this parameter to define the text of the download button. If you prefer to have an icon instead of a text button, you can replace the text with a button in CSS stylesheet.

Default: Download as PDF

ignoreDocs

If you want to exclude some documents from the section or overall PDF's and want to have it only available as individual chapter PDF, add the id to this parameter.

The parameter type is a string array.

Default: []

stylesheets

Add the style sheets you would use for printing here. Add the same as in stylesheets if you want to use the styles used on the docusaurus web page.

The parameter type is a string array.

Default: []

alwaysIncludeSiteStyles

Set this parameter to true, if you want the plugin to include the styles generated by docusaurus even when you have specified your own stylesheets.

Default: false

scripts

Add the scripts you would use for printing here. Add the same as in scripts if you want to use the scripts used on the docusaurus web page.

The parameter type is a string array.

Default: []

coverPageHeader

String containing HTML code which will be displayed as the header of the cover page.

Default: '...'

coverPageFooter

String containing HTML code which will be displayed as the footer of the cover page

Default: '...'

getPdfCoverPage

Function which returns the Cover Page as HTML. Example:

getPdfCoverPage: (siteConfig, pluginConfig, pageTitle, version) => {
  return `
    <!DOCTYPE html>
    <html>
    <head>
      
    </head>

      <body>
        <div style="margin: 2cm;">
          <h1 style="color:#005479;font-size:28px;font-family:sans-serif;font-weight:bold">${siteConfig.projectName}<h1>
          <h2 style="color:#005479;font-size:16px;font-family:sans-serif;">${(pageTitle || siteConfig.tagline)}<h2>

          <dl style="font-family:sans-serif;margin-top:10em;display: flex; flex-flow: row; flex-wrap: wrap; width: 600px; overflow: visible;color:#005479;font-size:12px;font-weight:normal;">
            <dt style="margin-top:1em;flex: 0 0 20%; text-overflow: ellipsis; overflow: hidden;">Author:</dt>    
            <dd style="margin-top:1em;flex:0 0 80%; margin-left: auto; text-align: left;text-overflow: ellipsis; overflow: hidden;">Your name</dd>
            <dt style="margin-top:1em;flex: 0 0 20%; text-overflow: ellipsis; overflow: hidden;">Date:</dt>
            <dd style="margin-top:1em;flex:0 0 80%; margin-left: auto; text-align: left;text-overflow: ellipsis; overflow: hidden;">${new Date().toISOString().substring(0,10)}</dd>
          </dl>
        </div>
      </body>

    </html>
  `;
}

getPdfPageHeader

Function which returns the Header of the content pages as HTML. Example:

getPdfPageHeader: (siteConfig, pluginConfig, pageTitle) => {
    return `
      <div style="justify-content: center;align-items: center;height:2.5cm;display:flex;margin: 0 1.5cm;color: #005479;font-size:9px;font-family:sans-serif;width:100%;">
        <div style="flex-grow: 1; width: 50%; text-align:left;margin-left:-3px">
          <img 
            style='display:block; width:2cm;' 
            id='base64image'                 
            src='data:image/svg+xml;base64, <Your Logo as base64>' 
          />
        </div>
        <span style="flex-grow: 1; width: 50%; text-align:right;">${pageTitle}</span>
      </div>
    `;
  },

getPdfPageFooter

Function which returns the Footer of the content pages as HTML. Example:

getPdfPageFooter: (siteConfig, pluginConfig, pageTitle) => {
  return `
    <div style="height:1cm;display:flex;margin: 0 1.5cm;color: #005479;font-size:9px;font-family:sans-serif;width:100%;">
      <span style="flex-grow: 1; width: 33%;">© You</span>
      <span style="flex-grow: 1; width: 33%; text-align:center;">${new Date().toISOString().substring(0,10)}</span>
      <span style="flex-grow: 1; width: 33%; text-align:right;">Page <span class='pageNumber'></span> / <span class='totalPages'></span></span>
    </div>`;
},

Puppeteer uses classes to inject values at print time. See: https://pptr.dev/#?product=Puppeteer&version=v3.0.4&show=api-pagepdfoptions

author

String you would like to use as author.

The value may be used in getPdfCoverPage, getPdfPageHeader or getPdfPageFooter with pluginConfig.author.

footerParser

Deprecated and ignored since 3.6.5. The TOC page numbers are read from a render of the final layout, so no footer text has to be parsed any more. The option is still accepted so existing configurations keep validating.

coverMargins

Margins for the cover page.

Default:

{
  top: "10cm",
  right: "0",
  bottom: "3cm",
  left: "0",
}

margins

Margins for content pages.

Default:

{
  top: "5cm",
  right: "2cm",
  bottom:"2.3cm",
  left: "2cm",
}

useExtraPaths

In case you have stylesheets or scripts that needs to be included from some other folder than the output folder specify them here.

Example: useExtraPaths: [{serverPath: "/", localPath: ".."}]

Default: []

ignoreCssSelectors

A list of css selectors that can be used to remove elements of the html before rendering it to pdf.

Example: ignoreCssSelectors: [".breadcrumbs", ".theme-doc-version-badge"]

Default: []

jQueryUrl

This plugin requires jQuery to insert a download button if addDownloadButton is set to true. Leave empty in case you provide jQuery some other way.

Default: https://code.jquery.com/jquery-3.6.0.min.js

getPdfFileName

Override this function to customize the file name of the generated pdfs. By default the names are based on the page ids.

Example:

getPdfFileName: (siteConfig, pluginConfig, pageTitle, pageId, parentTitles, parentIds, version, versionPath) => {
  let verString = version;
  if (verString == "current" || verString == "next") {
    verString = versionPath;
  }
  verString = verString.replace(".", "_");
  if (parentIds.length == 0) {
    return "mydoc-" + verString;
  }
  let pdfFilename = he.decode(pageId);
  if (parentIds.length > 1) {
    pdfFilename = parentIds.slice(1).filter(id => id != "").join('-') + '-' + pdfFilename;
  }
  return "mydoc-" + verString + pdfFilename;
}

Limitation

• Just documentations are generated, no pages or blog posts
• No support for translations