Look into publishing PDFs with mdbook-typst

[mgeisler]

There is a new tool which can convert an mdbook to Typst format, and thus also to high-quality PDFs: https://github.com/LegNeato/mdbook-typst

[LegNeato]

This exposed some bugs in my libraries, thanks! Attached is a generated PDF with the unreleased changes. Obviously there is more work to do, and I haven't yet styled on the typst side so presentation is lacking.

book.pdf

The TOC and headings and stuff are a bit wonky as I tuned the heuristics on the mdBook guide. That area is pretty hacky and I am going to be beefing it up in the coming weeks so it works for most / all cases.

There are escape hatches that let you directly insert typst markup before and after mdbook-typst does its thing. That is a potential stop gap solution if you can't find time to contribute improvements directly yet still want to tweak the output.

[simonsan]

That looks awesome already! Much better than the normal pdf print output! That's great!

[mgeisler]

Yeah, wow, thank you for producing this!

People have asked for a PDF version once or twice — I suggest we publish this when we publish the course and replace the print page with a link directly to the PDF.

[max-heller]

Sorry to hijack this thread, but it seems to be gaining traction. I recently released a similar tool, mdbook-pandoc, that can generate PDFs (and other formats) using pandoc. It doesn't have the potential to be 100% Rust that mdbook-typst has, but seems more mature at the moment. Here's a PDF of the book generated with the following config:

[output.pandoc.profile.pdf]
output = "Comprehensive Rust.pdf"
pdf-engine = "lualatex"

Two notes on generating the book

• I had to comment out the badges in src/index.md since pandoc doesn't know what to do with them--it usually handles remote images well, but I think the non-image extensions (e.g. .yml are confusing it):

  diff --git a/src/index.md b/src/index.md
  index bcff48c..d35360d 100644
  --- a/src/index.md
  +++ b/src/index.md
  @@ -1,8 +1,10 @@
   # Welcome to Comprehensive Rust 🦀
  
  +<!--
   [![Build workflow](https://img.shields.io/github/actions/workflow/status/google/comprehensive-rust/build.yml?style=flat-square)](https://github.com/google/comprehensive-rust/actions/workflows/build.yml?query=branch%3Amain)
   [![GitHub contributors](https://img.shields.io/github/contributors/google/comprehensive-rust?style=flat-square)](https://github.com/google/comprehensive-rust/graphs/contributors)
   [![GitHub stars](https://img.shields.io/github/stars/google/comprehensive-rust?style=flat-square)](https://github.com/google/comprehensive-rust/stargazers)
  +-->
  
   This is a free Rust course developed by the Android team at Google. The course covers
   the full spectrum of Rust, from basic syntax to advanced topics like generics

• The book contains unicode characters that the default LaTeX font doesn't support (e.g. 🦀), so you may want to swap out the fonts.

[LegNeato]

Awesome, that looks great!

[mgeisler]

Thanks for posting this @max-heller! Seeing the course in this form makes me nostalgic for my old university days!

I don't have a lot of bandwidth to experiment with this right now, but I would be supportive of us publishing a PDF along with the HTML. It's probably just a matter of adding a few lines to our publish.yml file.

[simonsan]

I don't have a lot of bandwidth to experiment with this right now, but I would be supportive of us publishing a PDF along with the HTML. It's probably just a matter of adding a few lines to our publish.yml file.

Shouldn't it be able to be built into the /book directory and then linked in the html template instead of the browser print dialogue if that value is set in the book.toml? At least this would be what I would expect from a rendered pdf.

Unfortunately that is less mobile compatible: https://caniuse.com/?search=pdf as fewer browsers seems to have a built-in pdf viewer. :/

The alternative could be to introduce another link on the top menu right-hand side for opening it as a pdf-book, or an Export dropdown where different rendered books are mentioned. pdf and epub for example.

[mgeisler]

I don't have a lot of bandwidth to experiment with this right now, but I would be supportive of us publishing a PDF along with the HTML. It's probably just a matter of adding a few lines to our publish.yml file.

Shouldn't it be able to be built into the /book directory and then linked in the html template instead of the browser print dialogue if that value is set in the book.toml? At least this would be what I would expect from a rendered pdf.

Right, I think I agree: we can remove the 🖨️ button from the pages and instead link to the PDF.

Unfortunately that is less mobile compatible: https://caniuse.com/?search=pdf as fewer browsers seems to have a built-in pdf viewer. :/

If the print.html page is no longer generated, then I suppose people lose a way of easily getting a concatenated version of the HTML for the course. A PDF would be a concatenated version, but it would of course look different.

I don't think much is lost if we don't link to print.html and replace it with a well-formatted PDF.

The alternative could be to introduce another link on the top menu right-hand side for opening it as a pdf-book, or an Export dropdown where different rendered books are mentioned. pdf and epub for example.

I would prefer to add a new page in the course which links to the PDF (and perhaps other formats if we generate those). Horizontal space is a costly resource, so this would allow us to remove the 🖨️ icon on every page.

[simonsan]

I don't have a lot of bandwidth to experiment with this right now, but I would be supportive of us publishing a PDF along with the HTML. It's probably just a matter of adding a few lines to our publish.yml file.

Shouldn't it be able to be built into the /book directory and then linked in the html template instead of the browser print dialogue if that value is set in the book.toml? At least this would be what I would expect from a rendered pdf.

Right, I think I agree: we can remove the 🖨️ button from the pages and instead link to the PDF.

Yes, although it would be interesting to keep the print button and create a modal when clicking on it with an overview of all possible print-friendly resources of the book, including pdf. Personally, I would find that more inclusive, as pdf for example is not really searchable (which is a problem e.g. in academics papers). That is not much of an issue in this case, though, as the book is html, and is being indexed by search engines.

Unfortunately that is less mobile compatible: https://caniuse.com/?search=pdf as fewer browsers seems to have a built-in pdf viewer. :/

If the print.html page is no longer generated, then I suppose people lose a way of easily getting a concatenated version of the HTML for the course. A PDF would be a concatenated version, but it would of course look different.

I don't think much is lost if we don't link to print.html and replace it with a well-formatted PDF.

The alternative could be to introduce another link on the top menu right-hand side for opening it as a pdf-book, or an Export dropdown where different rendered books are mentioned. pdf and epub for example.

I would prefer to add a new page in the course which links to the PDF (and perhaps other formats if we generate those). Horizontal space is a costly resource, so this would allow us to remove the 🖨️ icon on every page.

I agree, that on mobile and in areas, where horizontal space is a costly resource, the printing symbol is definitely a nuisance:

Though I would say, that it would be more intriguing to optimize the mdbook themes for mobile friendliness. There is a hamburger menu on the top left menu bar, although I would say, that it's better to hide all the menu items in a hamburger menu on the top right side, including the printer icon. And then have the TOC slide in/out from the left side. What I want to say: I'm not really sure, if it would be that nice to remove the printer icon and I personally would be more in favour of a modal or something showing all printable resources when clicking on the printer icon.

I personally would see that as better UI/UX because this is what people would expect (IMHO). And the printer icon is a bit of an essential way to interact with the user, when having a book, ebook whatever. I would even say in case of mdbook it's an empowering status symbol: "Ey, you! Hold on! You know you can print this book and get all that knowledge right here?".

I think it's worth to keep and work with the value it has.

[mgeisler]

Yes, although it would be interesting to keep the print button and create a modal when clicking on it with an overview of all possible print-friendly resources of the book, including pdf.

That sounds somewhat complicated 🙂 — the course doesn't have a dedicated web developer associated with it, so it would likely be me who would maintain this.

Though I would say, that it would be more intriguing to optimize the mdbook themes for mobile friendliness.

Similarly, while this is a great goal, it is unfortunately outside the scope of what I can do on the course. In general, mdbook seems like a project that could use more resources. It's become an essential part of the Rust ecosystem, but I think there is only a tiny developer community around it.

[mgeisler]

Thanks to the work of @max-heller, high-quality PDFs are now published on every merge to main! See https://google.github.io/comprehensive-rust/comprehensive-rust.pdf for the English one. They are generated with LaTeX and they're generated for all languages.

There are a few things to fix (emojis are not rendered), but I think the result looks very nice already. I suggest we try fixing the emojis and then start linking to the PDFs.

[mgeisler]

Thanks @max-heller for implementing this, people are liking it a lot on Mastodon: https://elk.zone/ohai.social/@mgeisler/112054837248737025 🙂

[simonsan]

This is really awesome! Would be cool actually, to have some easy to follow instructions how to do that for mdbooks in general. Would like to spread that knowledge a bit.

[max-heller]

This is really awesome! Would be cool actually, to have some easy to follow instructions how to do that for mdbooks in general. Would like to spread that knowledge a bit.

The README for mdbook-pandoc talks about how to get started. It doesn't go into details of what was needed for Comprehensive Rust (fallback fonts, translation, etc.) so it could probably use some fleshing out.

[simonsan]

This is really awesome! Would be cool actually, to have some easy to follow instructions how to do that for mdbooks in general. Would like to spread that knowledge a bit.

The README for mdbook-pandoc talks about how to get started. It doesn't go into details of what was needed for Comprehensive Rust (fallback fonts, translation, etc.) so it could probably use some fleshing out.

Would you be able to help us to get started over at rust-unofficial/patterns#380 to set that up for the Rust Patterns book? 😬

[max-heller]

Would you be able to help us to get started over at rust-unofficial/patterns#380 to set that up for the Rust Patterns book? 😬

rust-unofficial/patterns#394

[simonsan]

• The book contains unicode characters that the default LaTeX font doesn't support (e.g. 🦀), so you may want to swap out the fonts.

@max-heller Do you have any recommendation there which work well with unicode characters from your own experience?

[max-heller]

Do you have any recommendation there which work well with unicode characters from your own experience?

Depends a lot on which characters are needed in which contexts, unfortunately there's no mega font that includes every single glyph. For this book, we added Noto Color Emoji, Noto Sans Math, and Noto CJK fonts as necessary for non-English characters:

comprehensive-rust/book.toml

Lines 37 to 42 in c633f85

	mainfontfallback = ["NotoColorEmoji:mode=harf"]
	monofontfallback = [
	"NotoColorEmoji:mode=harf",
	"NotoSansMath:",
	"NotoSansMonoCJKSC:",
	]