Update pdf output instructions #772
Conversation
|
Why does this include commits from PR #770? |
|
Shoot, I must have branched off your branch accidentally. If/when we merge #770 in, the commits from there will fall off of this PR. What's that status of that one? Are you waiting on me? |
|
|
||
| The resulting PDF file will be added to the project's `_site/_assets/downloads/` directory. | ||
|
|
||
| The generated PDF file in the `_site` directory will be deleted every time you re-run `quire build`. If instead, you would like to keep the file, move it into the project’s `content/_assets/` directory. We recommend `content/_assets/downloads/`. The file will then be included in your project every time you run `quire build` or `quire preview` without also having to run `quire pdf`. Note, however, that if saved in the `content` directory, **the PDF will NOT be updated** with any future changes made to the project. When changes are made, the PDF files must be re-generated with `quire build` followed by `quire pdf` and once again moved into the appropriate directory. |
There was a problem hiding this comment.
This is confusing. I would remove or rework this sentence: "The file will then be included in your project every time you run quire build or quire preview without also having to run quire pdf." because it feels vaguely contradictory to the sentence that follows.
| When `pagePDF.output` is set to `true`, PDFs will be generated for all individual pages in your book. There are two ways to remove select markdown pages from the PDF outputs: | ||
|
|
||
| 1. Rename the `pagedjs.pdf` (or `prince.pdf`) file if you would like | ||
| 1. If a markdown page has been set to output only in HTML, EPUB, or both but not PDF, the page will not be included in the full publication PDF output, nor will an individual page PDF be created for it. |
There was a problem hiding this comment.
Am I understanding this correctly... you can use Page YAML to override the config settings on a markdown file by markdown file basis?
| ``` | ||
|
|
||
| 3. Confirm that the `resource_link` information in your `content/_data/publication.yaml` file to points to the PDF file you just generated | ||
| 2. If a markdown page has `page_pdf_output: false` set, it WILL be included in the full publication PDF output, but an individual page PDF will not be created for it. |
There was a problem hiding this comment.
For these two options for excluding page-level PDFs, I would make the goals of each of these options more explicit. "Use this if..."
| ``` | ||
|
|
||
| 4. Run `quire build` again to generate new `_site` files with the PDF included inside | ||
| Conversely, when `pagePDF.output` is set to `false`, you can use `page_pdf_output: true` in any markdown page to selectively output it as an individual page PDF. |
There was a problem hiding this comment.
I would clarify that the first half of this sentence is referring to the config file.
|
|
||
| #### Using an Alternative PDF Generator | ||
|
|
||
| Quire’s PDF output is generated by [Paged.js](https://pagedjs.org/), an open source HTML-to-PDF generator. |
There was a problem hiding this comment.
Maybe add "When running the command quire pdf. Paged.js is the default PDF generator..." or something to that effect.
|
|
||
| The generated PDF file in the `_site` directory will be deleted every time you re-run `quire build`. If instead, you would like to keep the file, move it into the project’s `content/_assets/` directory. We recommend `content/_assets/downloads/`. The file will then be included in your project every time you run `quire build` or `quire preview` without also having to run `quire pdf`. Note, however, that if saved in the `content` directory, **the PDF will NOT be updated** with any future changes made to the project. When changes are made, the PDF files must be re-generated with `quire build` followed by `quire pdf` and once again moved into the appropriate directory. | ||
|
|
||
| #### Outputting Individual Page PDFs |
There was a problem hiding this comment.
I think it's worth reiterating here somewhere that when you have individual page downloads set in the config.yaml (or Page YAML) and you run quire pdf, the individual PDFs will automatically appear in the _site/_assets/downloads/.
| #### Linking to individual PDFs | ||
| When you generate a PDFs for individual pages, links can automatically be added to each of those pages in the online edition for readers to download the PDFs. These download `accessLinks` will appear in the header or footer of the pages, or both. |
There was a problem hiding this comment.
See note above regarding where the individual files will appear once they are generated with quire pdf
|
|
||
| #### Setting where the PDF file is output | ||
|
|
||
| This default file location where PDFs are generated can be changed with the `pdf.outputDir` value in the `content/_data/config.yaml` file. The filepath given there is always considered to be within the `_site` directory. |
There was a problem hiding this comment.
I don't understand this phrasing "the filepath given is considered to be within the _site directory..." but it looks like you can change the path to /_assets/downloads/.
Also, if that is where the PDFs ultimately need to go (maybe I'm misunderstanding that part), why not always have that be the default folder rather than _site which in my opinion is a confusing place for them to go by default.
| ### Use Pre-Defined Variables to Modify and Style the PDF | ||
| #### Crop Marks and Bleeds | ||
|
|
||
| As mentioned above, by default, the PDF is output with full bleed and crop marks. This default setting can be altered in the `content/_assets/styles/variables.scss` file. Adding the following lines to the "Print/PDF stylesheet" section removes the crop marks that are automatically applied to the PDF. |
There was a problem hiding this comment.
Is this mentioned above?
|
|
||
| ### PDF Accessibility | ||
|
|
||
| Information to come ... |
There was a problem hiding this comment.
We have used TK in other parts of the docs, which we may want to rethink. And I would like to keep either "TK" or "information to come" so we remember it needs to go there (in addition to an issue in the docs repo), but also so the community knows there's more helpful information on the way.
Thank you for contributing to the Quire Documentation & Website! Please complete the form below to submit your pull request for review.
For the Title of this pull request, please use the format "Type/Issue-#: Brief description." For Type, the options are Edit, Add, Translate. Issue-# is only needed if this pull request addresses an existing issue.
Checklist
Please put an X within the brackets that apply
[X].I have read the CONTRIBUTING.md file.
I have made my changes in a new branch and not directly in the main branch
I am requesting feedback on a draft pull request
Is this pull request related to an open issue? If so, what is the issue number?
#737
Please describe the goal of this pull request and the changes that were made.
This is updated documentation for PDF output that now (finally) includes instructions about individual page PDFs, and the new configurations and workflows associated with that feature.
Additional Comments
For now, I have left it all within the main update page, but I think it would be better breaking this into an EPUB and a PDF page. The documentation is only going to get longer, and having them on their own pages would help with navigation as the heading jump links on the top of the page would be more specific.
Note too that I've left placeholder at the bottom of the page for sections on PDF accessibility and producing a print edition. I couldn't remember how we handle placeholders like this. It was my instinct to leave the headings and a "to come" note there, but perhaps it's preferable to pull them out until they're actually written?