docs
docs copied to clipboard
cockroachdb
Generate PDF docs
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
FWIW Hugo doesn't natively support this feature:
https://github.com/spf13/hugo/issues/1360
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.
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
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...
@rmloveland, can you provide any details/links about the pdf export experiment you did some time ago?
@rmloveland, it sounds like we'll need to provide a spatial customer offline docs for 20.2. Can we use your tool for this particular case ahead of a final solution from @yingzhuchin? If your tool doesn't do the trick, the customer will accept the raw markdown.
cc @awoods187, @keith-mcclellan
can you provide any details/links about the pdf export experiment you did some time ago?
I wrote a bunch of scripts to clean up the HTML from our Jekyll build, build a giant TOC of all our docs, and make it all one big file, with links that (mostly?) still work.
I have not had great luck exporting this to PDF through Pandoc because of some constructs in our HTML that make Pandoc upset. So far, the route to PDF has been through a browser "print to PDF" workflow from HTML.
Can we use your tool for this particular case
Fine by me - but it may not meet the customer's needs. It outputs (very simplified) HTML that I then print as a PDF from the web browser. It does seem to mostly work in terms of clicking around through links, etc. However there are a couple of bugs in the TOC generation since our TOC structure recently changed.
Looks like I can't add an attachment to this image so I'll email a sample PDF to you, Andy, Keith, and YZ for your perusal.
I think the sample "checks the box" in our case, in particular if we also send the markdown package for them to host something themselves as an alternative. Longer term it'd be great if we had a more professional looking solution here but I don't think that's critical path for what we need to deliver. Thanks!
Thanks, Rich and Keith. I'm glad we're good for now. Programmatically generating professional-looking PDFs remains on our backlog. We'll definitely get to it at some point. It's just a matter of prioritizing our eng time with YZ.
Jesse
On Thu, Sep 17, 2020 at 7:48 AM Keith [email protected] wrote:
I think the sample "checks the box" in our case, in particular if we also send the markdown package for them to host something themselves as an alternative. Longer term it'd be great if we had a more professional looking solution here but I don't think that's critical path for what we need to deliver. Thanks!
— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/cockroachdb/docs/issues/1484#issuecomment-694178337, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADZIH4TGAN2LQRAIT237RS3SGHZQVANCNFSM4DNRZ4HA .
-- Jesse Seldess VP of Education, Cockroach Labs https://www.cockroachlabs.com/
We have closed this issue because it is more than 3 years old. If this issue is still relevant, please add a comment and reopen the issue. Thank you for your contribution to CockroachDB docs!