Skip to content

Commit 254d8ea

Browse files
rlanzafamerlanzafame
authored
Merge pull request #31 from rlanzafame/pdf-exercise
PDF Lession updates
2 parents 5c8e68b + 15e3114 commit 254d8ea

4 files changed

Lines changed: 129 additions & 76 deletions

File tree

‎content/lessons/6b_pdfgeneration.md‎

Lines changed: 1 addition & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -47,45 +47,4 @@ Rather than specifying the extension, you can just use the file name and an aste
4747

4848
For YouTube clips and online interactive materials embedded through iframes, you can make use of plugins.
4949
See for instance the [iframe-to-thumbnail plugin](https://github.com/jupyter-book/myst-plugins/tree/main/plugins/iframe-to-thumbnail-pdf).
50-
This plugin replaces the iframe with a thumbnail image that links to the original content as well as a QR code and a link in the caption.
51-
52-
## Additional Considerations
53-
54-
**WIP**
55-
56-
### Excluding and including sections for PDF[^1]
57-
[^1]: Directly copied from the official [Myst documentation](https://mystmd.org/guide/creating-pdf-documents#excluding-content-from-specific-exports).
58-
59-
60-
If you need to inject some LaTeX or Typst-specific content into their respective exports, you may use the {raw:latex} or {raw:typst} role and directive.
61-
For example, to insert a new page in Typst with two columns:
62-
63-
64-
```{raw:typst}
65-
#set page(columns: 2, margin: (x: 1.5cm, y: 2cm),);
66-
```
67-
68-
Or,
69-
70-
`+++ { "page-break": true }` for a page break.
71-
72-
73-
74-
The content in these directives and roles will be included exactly as written in their respective exports, and will be ignored in all other contexts.
75-
76-
You may use block metadata to insert page breaks into your PDF or docx export with `+++ { "page-break": true }`.
77-
This will have no impact on your MyST site build nor other static exports that disregard “pages” (e.g. JATS).
78-
79-
```{note}
80-
+++{"no-pdf": true}
81-
This won't be in the PDF.
82-
+++
83-
```
84-
85-
### Typst
86-
87-
When exporting to Typst format, you can provide Typst-specific math content using the typst option.
88-
This allows you to use native Typst syntax instead of relying on tex-to-typst conversion, which may give incorrect results.
89-
90-
Example with typst argument in a math block:
91-
https://mystmd.org/guide/math#typst-math
50+
This plugin replaces the iframe with a thumbnail image that links to the original content as well as a QR code and a link in the caption.

‎content/lessons/6c_pdfoutput.md‎

Lines changed: 74 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -6,55 +6,76 @@ numbering:
66

77
# Create a PDF 🌶
88

9-
**outline**
10-
- Install Typst and confirm availability on CLI
11-
- generate a PDF using default setup (`lapreprint-typst`)
12-
- set up and use `plain_typst_book`
13-
- set up GHA
14-
- play with configuration of website to use PDF
9+
With a general understanding of document creation using MyST and our choice to use Typst for PDF generation, you are ready to create a PDF from your book repository using Jupyter Book.
1510

11+
In this lesson, we will:
12+
- Install Typst (or use it within a GitHub Action workflow if working online-only)
13+
- Generate a PDF using the `lapreprint-typst` template
14+
- Set up and use the `plain_typst_book` template
15+
- Modify the GitHub Action workflow to generate a PDF
16+
- Explore how the PDF can be customized and shared via the book website
1617

17-
With a general understanding of document creation using MyST and our choice to use Typst for PDF generation, you are ready to create a PDF from your book repository using Jupyter Book.
18+
```{warning}
19+
To complete this lesson locally, you will need to install Typst. If this is not possible, or you are following the online-only path, you can complete the exercises using GitHub Actions. The exercises in this lesson use **Local** and **GitHub Actions** to distinguish instructions for each case.
20+
```
1821

1922
## Install Typst
2023

21-
::::{tab-set}
22-
:::{tab-item} Locally
2324
To produce a PDF output locally, you need to have Typst installed on your system.
2425

2526
````{exercise} Install Typst
26-
Follow [these steps](xref:myst/creating-pdf-documents#typst-install) to install Typst locally.
27+
28+
::::{tab-set}
29+
:::{tab-item} Local
30+
31+
Install Typst using the nstructions available at the [Typst GitHub repo](https://github.com/typst/typst?tab=readme-ov-file#installation) and Jupyter Book 2 context is provided [here](xref:myst-guide/creating-pdf-documents#typst-install).
2732
2833
Check whether Typst is correctly installed by running the following command in your terminal:
2934
3035
```console
3136
typst --version
3237
```
33-
34-
````
3538
:::
3639
:::{tab-item} GitHub Actions
37-
If you are not working locally, you will need to use GHA to generate your PDF. You can proceed through this lesson sequentially, however, skip the steps that ask you to build the PDF using your CLI. Once you have updated your `myst.yml` file to use the `plain_typst_book` you can set up GHA to build and view the PDF.
3840
39-
**WIP**: these instructions need improvement.
41+
Until you get to the Lesson "PDF output with GH Actions" you won't be generating PDF's, but you can still learn how the template is defined and used by Juypter Book.
42+
4043
:::
4144
::::
42-
45+
````
4346

4447
## Generate a PDF
4548

46-
:::{exercise} Generate a PDF using the CLI
47-
**WIP**
48-
- generate a PDF using the command line (will use `lapreprint-typst`)
49-
- answer questions (bullet list below)
50-
- look at the output. Can we do better? (yes)
49+
Once Typst is installed and available in your terminal it can be used with Jupyter Book to generate a PDF file.
5150

52-
The template is...
53-
The PDF is found...
5451

52+
````{exercise} Generate a PDF of your book
53+
54+
::::{tab-set}
55+
:::{tab-item} Local
56+
57+
Generate a PDF using the command `jupyter book build --pdf`.
58+
59+
View the PDF and observe how the contents of your website are formatted in the PDF document.
60+
61+
Next, review the contents of the `myst.yml` file and answer the following questions:
62+
- What template is being used?
63+
- Where is the PDF output file saved after being generated?
64+
:::
65+
:::{tab-item} GitHub Actions
66+
67+
Review the contents of the `myst.yml` file and answer the following questions:
68+
- What template is being used?
69+
- Where is the PDF output file saved after being generated?
5570
:::
71+
::::
72+
````
5673

5774

75+
```{tip} Good practice with PDFs and Git
76+
Git is not intended for use with binary files like PDF's. When working with PDF's locally you may be tempted to commit the generated file to your repository, especially if you intend to share your work online. However, this will lead to unecessary large Git workspace and is not recommended. For this reason the `.gitignore` file already ignores PDF files, and the upcoming exercise with GH Actions illustrates how a PDF can be generated online and saved as a downloadable artifact, rather than committing it to the repository.
77+
```
78+
5879
## Change the PDF template
5980

6081
As seen in the previous exercise, the PDF generated by the `lapreprint-typst` template is not ideal for rendering content designed as a website made with the `book-theme`. Luckily, another Typst template is available: [the Plain Typst Book `plain_typst_book`](https://github.com/myst-templates/plain_typst_book) (not yet listed on the MyST Templates GH Organization). An example YAML snippet that implements this in the `myst.yml` file is illustrated here:
@@ -72,15 +93,24 @@ As seen in the previous exercise, the PDF generated by the `lapreprint-typst` te
7293
```
7394
7495
75-
:::{exercise} Implement the `plain_typst_book` template in your book
76-
**WIP**
77-
change, generate, view output
96+
````{exercise} Change the template
97+
98+
::::{tab-set}
99+
:::{tab-item} Local
100+
101+
Using the example code provided above, update your `myst.yml` file to use the `plain_typst_book` template in your book, then rebuild the PDF.
102+
103+
Observe how the rendered PDF is different than the previous template.
78104
:::
105+
:::{tab-item} GitHub Actions
106+
107+
Using the example code provided above, update your `myst.yml` file to use the `plain_typst_book` template in your book. Although you will commit this in your repository, the PDF still won't be generated until completing the next exercise.
79108

80-
:::{exercise} Customize the template and regenerate the PDF
81-
visit the repo, read doc, change some features of the template
82109
:::
110+
::::
111+
````
83112

113+
(section:pdf-with-gha)=
84114
## PDF output with GH Actions
85115

86116
Building and including your PDF is possible through a GitHub action that automatically builds the PDF when you push changes to GitHub. This has both is pros and cons. For instance, the build of your PDF is done prior to the build of your book, and if there is an error in the workflow your website may not be updated, or the PDF may not be included as a download. On the other hand, you do not need to install anything locally and the PDF is always up to date when you push changes. The workflow steps are:
@@ -97,18 +127,28 @@ Building and including your PDF is possible through a GitHub action that automat
97127
myst build --typst
98128
```
99129

100-
```{tip} Good practice with PDFs and Git
101-
Don't commit PDF's. Hence the `.gitignore`. Don't let your GHA commit PDF's either (hence the artifact upload, which is shown later).
102-
In fact, PDF generation in GHA is a form of software testing: successful generation of the PDF indicates everything is working properly.
103-
```
130+
````{exercise} Change the workflow
104131

105-
:::{exercise} Add PDF generation to GHA workflow
106-
**WIP**
107-
change, view output
132+
::::{tab-set}
133+
:::{tab-item} Local
134+
135+
Using the example code provided above, update your `deploy.yml` file to build the PDF as part of your GitHub Action workflow.
136+
137+
Visit the Actions page of your repository to find where the artifact (PDF) can be downloaded.
138+
:::
139+
:::{tab-item} GitHub Actions
140+
141+
Using the example code provided above, update your `deploy.yml` file to build the PDF as part of your GitHub Action workflow.
142+
143+
Visit the Actions page of your repository to find where the artifact (PDF) can be downloaded.
108144
:::
145+
::::
146+
````
109147

110148
## More fun with PDF's
111149

150+
**WIP**
151+
112152
add MyST action button, add download on page.
113153

114154
Upload as artifact (GHA only). This can be done even if the website build fails.

‎content/lessons/6d_typsttemplate.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
numbering:
3+
title:
4+
offset: 1
5+
---
6+
7+
# Working with the template
8+
9+
This page provides additional information about the [Typst template `plain_typst_book`](https://github.com/myst-templates/plain_typst_book) which was set up for this book as part of the exercises on the previous page.
10+
11+
**WIP**
12+
- brief overview of how the template works (repo, inclusion, etc)
13+
- summary of how to "view" it
14+
- examples of usage (options)
15+
- more advanced explanations, if needed
16+
17+
18+
## Excluding and including sections for PDF[^1]
19+
[^1]: Directly copied from the official [Myst documentation](https://mystmd.org/guide/creating-pdf-documents#excluding-content-from-specific-exports).
20+
21+
22+
If you need to inject some LaTeX or Typst-specific content into their respective exports, you may use the {raw:latex} or {raw:typst} role and directive.
23+
For example, to insert a new page in Typst with two columns:
24+
25+
26+
```{raw:typst}
27+
#set page(columns: 2, margin: (x: 1.5cm, y: 2cm),);
28+
```
29+
30+
Or,
31+
32+
`+++ { "page-break": true }` for a page break.
33+
34+
35+
36+
The content in these directives and roles will be included exactly as written in their respective exports, and will be ignored in all other contexts.
37+
38+
You may use block metadata to insert page breaks into your PDF or docx export with `+++ { "page-break": true }`.
39+
This will have no impact on your MyST site build nor other static exports that disregard “pages” (e.g. JATS).
40+
41+
```{note}
42+
+++{"no-pdf": true}
43+
This won't be in the PDF.
44+
+++
45+
```
46+
47+
## Typst
48+
49+
When exporting to Typst format, you can provide Typst-specific math content using the typst option.
50+
This allows you to use native Typst syntax instead of relying on tex-to-typst conversion, which may give incorrect results.
51+
52+
Example with typst argument in a math block:
53+
https://mystmd.org/guide/math#typst-math

‎myst.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ project:
5555
- file: content/lessons/6a_myst.md
5656
- file: content/lessons/6b_pdfgeneration.md
5757
- file: content/lessons/6c_pdfoutput.md
58+
- file: content/lessons/6d_typsttemplate.md
5859
# - file: content/lessons/7_styling.md
5960
- file: content/lessons/8_init.md
6061

0 commit comments

Comments
 (0)
⚡