Create layout for exporting docs to PDF manually

[apaskulin]

User stories

• As a maintainer, I can archive a past version of the docs by creating a downloadable PDF. This can be a manual process.
• As a user needing docs for a past version of Sensu, I can download a PDF with copy-and-paste-able code sample, working links, and readable styles.

To do

Create a version of the docs that is suitable for export to PDF using Adobe Acrobat Pro's recursive output-to-PDF feature, including these considerations:

• Fonts are adjusted to work well within PDF
• Code samples are forced to wrap within text blocks instead of using a horizontal scrollbar
• Content within language toggle blocks is accessible.

Resources

• Test PDF generated using Adobe Acrobat Pro in May 2019
• Meeting notes from 7/30/2019

[rnevius]

After thoroughly investigating and testing Adobe Acrobat Pro's PDF exporting tool set, I've encountered the following issues which would need to be resolved if we are to go this route:

1. Standardization of internal links. Linking to headings is consistently broken (likely because multiple elements with the same id attribute exist in the same PDF document. These elements are on completely different pages on the website). Some internal links also try to open in a browser.
2. Occasional broken images.
3. Broken third-party assets.
4. Print-only styles are not rendered. This means that we would have to use something other than @media print to redefine styles (e.g. an environment variable that is injected when the local server runs and which is checked for in partials to determine which CSS files are required).
5. Broken tables.
6. Incorrect Table of Contents.
7. Footer content is printed multiple times.

[rnevius]

A solution is currently being worked on in the feature/ebook branch.

[cwjohnston]

Thanks @rnevius! One question regarding this point:

1. Standardization of internal links. Linking to headings is consistently broken (likely because multiple elements with the same id attribute exist in the same PDF document. These elements are on completely different pages on the website). Some internal links also try to open in a browser.

I can see how this would happen if we were generating a PDF containing the content for multiple versions of the same product. Does that explain what you are seeing or is there more to it?

[rnevius]

@cwjohnston

Linking to headings is consistently broken

This was probably just me getting unlucky with a few actual broken links during my original testing. Here's an example: https://docs.sensu.io/sensu-go/5.12/guides/plan-maintenance/#what-is-sensu-silencing ("event handlers" links to nowhere). This doesn't actually seem to be an issue with PDF export as originally suspected.

Some internal links also try to open in a browser.

This actually seems to be the main issue. I believe switching to relative links wherever possible should fix this.

[cwjohnston]

@rnevius any updates on this?

We've recently discovered that our search functionality is impacted by the increasing number of versions we have documented (see #1761). I'd love for us to resolve this by using export docs to PDF as a way to deprecate and remove old documentation from this project.