Generate PDF docs

[jseldess]

Jesse Seldess commented:

For customers who would prefer offline access to our docs, we should generate PDFs and make them downloadable from our site. We'll need to identify the proper scope (just stable docs, or pdfs or each version? one pdf across CockroachDB and CockroachCloud, or separate PDFs?). We'll need to think about the right UX and styling as well (e.g., where should page's break, etc.).

Static site generators like Sphinx offer this out-of-the-box, but Jekyll does not. So the first step is researching possible approaches. A few initial options listed below.

Via Jekyll:

• http://abemedia.co.uk/jekyll-pdf/

From HTML:

• https://wkhtmltopdf.org/
• https://github.com/pdfkit/PDFKit
• http://www.princexml.com/doc/installing/ (paid)

Jira Issue: DOC-113

[sploiselle]

FWIW Hugo doesn't natively support this feature:

gohugoio/hugo#1360

[jseldess]

Thanks, @sploiselle. If you have other thoughts about the markdown to pdf workflow, please add them. So far, I've just been looking at html to pdf, but there may be other possible trajectories.

[bdarnell]

Sphinx does nice book-like PDF output (as opposed to the more common "printed web page" style of PDFs). It can turn links into page references and footnotes for printed use. Sample

[rdwatters]

FWIW, I've done a combo workflow with Hugo, AppleScript, Word, and Pandoc...the last of which is a serious mind-gasm to those who are unfamiliar. Saying that Hugo doesn't natively support it is a bit of a half truth since custom outputs allows for writing to any text file/extension; it's just up to you write the LaTeX template.

Prince is a great solution but crazy expensive, IMHO...

[jseldess]

cc @j-low