Mik-TF
commented
1 year ago Updates on PDF Creation of Books
Mdbook-pdf
So the current mdbook's print.html ([output.html]) option will render a PDF where the links will lead to the website (or local files, if the mdbook was served locally). This means that the PDF created isn't really usable as clicking on the ToC's links won't lead to inner links.
A fix for this is to use a forked mdbook:
cargo install --git https://github.com/HollowMan6/mdBook.git mdbookWith this forked mdbook, when you print the book, the inner links will work.
But the print.html version (printed book) won't render proper code blocks (e.g. ``` text here ```). A solution would be to use the pdf creation function of mdbook-pdf ([output.pdf]), but as tested, the timeout error gets triggered and the pdf can't be rendered.
You can read more here.
Markdown PDF
Something that works well, but just for 1 markdown file, is to use the yzane.markdown-pdf extension on VS Code.
The PDF looks good, with code blocks properly displayed. But we can't do a whole mdbook with this function, as it's only for 1 file at a time.
What was done previously for the farmers documentation, was to put all the different markdown files into one big markdown file. Then you can create a PDF easily and it looks good, links work, and you can adjust easily the header and footer. Obviously, this takes time since we'd need to put all the markdown files into one. Also the sections with the same name (e.g. Introduction) will only have the first instance working.
Possible Solutions
-
A possible solution would be to make the function [output.pdf] of mdbook to work with a large mdbook. So we'd need to explore how to further adjust the timeout. Disadvantage: the rendering is not as good and permissible as using Markdown PDF.
-
A possible solution would be to take one book (e.g. farmers book) and put the many md files into one files then use Markdown PDF in VScode/codium. This would give a great rendering with proper header and footer. We'd need to change the \<h1> and \<h2> tags for # and ## respectively, and modify the subsections with same name (e.g. introduction would become introduction of
). To get this more automatic, we could create a small program/script to do such changes. Thus, we could periodically (say once a month), update the 4 books available for download.
EDIT: Option (2) seems the more fitting. It will give the best result. the mdbook output.pdf isn't as effective as Markdown PDF for many reasons discussed above.
Solution (2) Proposal: Turn each main book into a single .md file
We propose an algorithm to take each book and organize them in one single markdown file. This markdown file is then turned into a PDF with defined footer and header, with date of release. Every month/quater/given frequency, we can deploy in CI/CD the new versions of each book (farmers, devs, sysadmins, 3bot). It can also be done at each push/pull request.
The script basically clones src, organize it as per summary.md, copy the content in one single file, adjust the text for PDF-format, then use Markdown PDF to set in final printable book format.
Text manipulation method:
- Turn \<h1>...\ to # ... same for all heading levels
- Make dictionary of all heading levels, each level has a list.
- If a word repeats itself, add something relative to the current subsection to differentiate the versions
- e.g. in Terraform VPN and SSH guides
- Introduction to Terraform VPN
- Introduction to SSH Guides
- pattern: name_of_subsection + "to" + "name_of_section
- simpler pattern: name_of_subection + counter_repetition
- If a word repeats itself, add something relative to the current subsection to differentiate the versions
Here's a list of tasks to do in order to properly upgrade the manual with the new main books (farmers, sysadmins, developers). Note that we will also add a book "3bot" very soon.
If you have some ideas on new tasks, feel free to reply in this issue.
TF MANUAL UPDATE STEPS:
This is to update the manual. We also create new contents and guides.