added more detail about the pdf generation process and also updated the pdfs
This commit is contained in:
@ -11,13 +11,9 @@ folder: mydoc
|
||||
|
||||
|
||||
## PDF overview
|
||||
This process for creating a PDF relies on Prince XML to transform the HTML content into PDF. Prince costs about $500 per license. That might seem like a lot, but if you're creating a PDF, you're probably working for a company that sells a product, so you likely have access to some resources.
|
||||
This process for creating a PDF relies on Prince XML to transform the HTML content into PDF. Prince costs about $500 per license. That might seem like a lot, but if you're creating a PDF, you're probably working for a company that sells a product, so you likely have access to some resources. There's also a free license that prints a small "P" watermark on your title page, so if you're fine with that, great.
|
||||
|
||||
The basic approach is to generate a list of all pages that need to be added to the PDF, and then add leverage Prince to package them up into a PDF.
|
||||
|
||||
It may seem like the setup is somewhat cumbersome, but it doesn't take long. Once you set it up, building a pdf is just a matter of running a couple of commands.
|
||||
|
||||
Also, creating a PDF this way gives you a lot more control and customization capabilities than with other methods for creating PDFs. If you know CSS, you can entirely customize the output.
|
||||
The basic approach is to generate a list of all web pages that need to be added to the PDF, and then add leverage Prince to package them up into a PDF. Once you set it up, building a pdf is just a matter of running a couple of commands. Also, creating a PDF this way gives you a lot more control and customization capabilities than with other methods for creating PDFs. If you know CSS, you can entirely customize the output.
|
||||
|
||||
## Demo
|
||||
|
||||
@ -25,6 +21,49 @@ You can see an example of the finished product here:
|
||||
|
||||
<a target="\_blank" class="noCrossRef" href="{{ "pdf/mydoc.pdf"}}"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>
|
||||
|
||||
To generate the PDF, browse to the theme's directory in your terminal and run this script:
|
||||
|
||||
```bash
|
||||
. pdf-mydoc.sh
|
||||
```
|
||||
|
||||
This builds a PDF for the documentation in the theme. Look in the **pdf** folder for the output, and see the "last generated date" to confirm that you generated the PDF.
|
||||
|
||||
To build a PDF for the other sample projects, run these commands:
|
||||
|
||||
```bash
|
||||
. pdf-product1.sh
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```bash
|
||||
. pdf-product2.sh
|
||||
```
|
||||
|
||||
You can see the details of the script in these files in the theme's root directory. For example, open pdf-mydoc.sh. It contains the following:
|
||||
|
||||
```bash
|
||||
# Note that .sh scripts work only on Mac. If you're on Windows, install Git Bash and use that as your client.
|
||||
|
||||
echo 'Kill all Jekyll instances'
|
||||
kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}')
|
||||
clear
|
||||
|
||||
echo "Building PDF-friendly HTML site for Mydoc ...";
|
||||
bundle exec jekyll serve --detach --config _config.yml,pdfconfigs/config_mydoc_pdf.yml;
|
||||
echo "done";
|
||||
|
||||
echo "Building the PDF ...";
|
||||
prince --javascript --input-list=_site/pdfconfigs/prince-list.txt -o pdf/mydoc.pdf;
|
||||
|
||||
echo "Done. Look in the pdf directory to see if it printed successfully."
|
||||
```
|
||||
|
||||
After stopping all Jekyll instances, we build Jekyll using a special configuration file that specifies a unique stylesheet. The build contains a file (prince-list.txt) that contains a list of all pages to be included in the PDF. We feed this list into a Prince command to build the PDF.
|
||||
|
||||
The following sections explain more about the setup.
|
||||
|
||||
## 1. Set up Prince
|
||||
|
||||
Download and install [Prince](http://www.princexml.com/doc/installing/).
|
||||
@ -66,6 +105,8 @@ Also note that there's a `output: pdf` property in case you want to make some of
|
||||
|
||||
In the configuration file, customize the values for the `print_title` and `print_subtitle` that you want. These will appear on the title page of the PDF.
|
||||
|
||||
We will access this configure file in the PDF generation script.
|
||||
|
||||
## 3. Make sure your sidebar data file has titlepage.html and tocpage.html entries
|
||||
|
||||
There are two template pages in the root directory that are critical to the PDF:
|
||||
@ -292,7 +333,7 @@ Because the theme uses JavaScript in the CSS, you have to add the `--javascript`
|
||||
|
||||
## 5. Customize and run the PDF script
|
||||
|
||||
Duplicate the pdf-mydocf.sh file in the root directory and customize it for your specific configuration files.
|
||||
Duplicate the pdf-mydoc.sh file in the root directory and customize it for your specific configuration files.
|
||||
|
||||
```
|
||||
echo 'Killing all Jekyll instances'
|
||||
|
Reference in New Issue
Block a user