doc: improve rendering of example books (#79)

Decrease margins, set `hosted-html`, and configure fallback fonts for rendered example books

.github/workflows/release.yml

@@ -151,7 +151,7 @@ jobs:
     needs:
       - plan
       - build-local-artifacts
-    runs-on: "ubuntu-20.04"
+    runs-on: ubuntu-latest
     env:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       BUILD_MANIFEST_NAME: target/distrib/global-dist-manifest.json

Cargo.toml

@@ -64,6 +64,8 @@ installers = ["shell", "powershell"]
 targets = ["x86_64-unknown-linux-gnu", "aarch64-apple-darwin", "x86_64-apple-darwin", "x86_64-unknown-linux-musl", "x86_64-pc-windows-msvc"]
 # Publish jobs to run in CI
 pr-run-mode = "plan"
+# TODO: When cargo-dist allows specifying custom runners for the global artifacts job, remove this
+allow-dirty = ["ci"]
 
 [workspace.metadata.dist.dependencies.apt]
 pandoc = { stage = ["run"] }

README.md

@@ -125,7 +125,7 @@ variable-name = "value"
 #### Rendered books
 
 The following table links to sample books rendered with `mdbook-pandoc`.
-PDFs are rendered with LaTeX ([xelatex](https://en.wikipedia.org/wiki/XeTeX)).
+PDFs are rendered with LaTeX ([LuaTeX](https://en.wikipedia.org/wiki/LuaTeX)).
 
 | Book | Rendered |
 | ---- | -------- |

scripts/cargo-dist-render-books

@@ -2,9 +2,7 @@
 
 set -e
 
-# Use xelatex when building books since texlive-luatex is missing lua-ul.sty on Ubuntu 20.04,
-# which cargo-dist uses for its runner
-PDF_ENGINE=xelatex cargo nextest run --no-fail-fast || true
+cargo nextest run
 
 cp books/cargo/src/doc/book/pdf/book.pdf rendered-cargo-book.pdf
 cp books/mdBook/guide/book/pdf/book.pdf rendered-mdBook-guide.pdf

scripts/install-ci-deps

@@ -9,15 +9,15 @@ sudo apt-get update
 curl -LsSf https://get.nexte.st/0.9/linux | tar zxf - -C ${CARGO_HOME:-~/.cargo}/bin
 
 # Pandoc
-curl -LsSf https://github.com/jgm/pandoc/releases/download/3.1.11/pandoc-3.1.11-linux-amd64.tar.gz | tar zxf -
-echo "$PWD/pandoc-3.1.11/bin" >> $GITHUB_PATH
-export PATH="$PWD/pandoc-3.1.11/bin:$PATH"
+curl -LsSf https://github.com/jgm/pandoc/releases/download/3.1.12.3/pandoc-3.1.12.3-linux-amd64.tar.gz | tar zxf -
+echo "$PWD/pandoc-3.1.12.3/bin" >> $GITHUB_PATH
+export PATH="$PWD/pandoc-3.1.12.3/bin:$PATH"
 
 # rsvg-convert (SVG support)
 sudo apt-get install -y librsvg2-bin
 
 # TeX Live and fonts
-sudo apt-get install -y texlive texlive-luatex texlive-xetex texlive-fonts-extra fonts-font-awesome fonts-noto
+sudo apt-get install -y texlive texlive-luatex texlive-lang-cjk texlive-fonts-extra fonts-font-awesome fonts-noto fonts-noto-cjk fonts-noto-color-emoji
 
 # mdBook preprocessors needed by example books
 cargo install mdbook-i18n-helpers --locked

src/lib.rs

@@ -189,6 +189,7 @@ mod tests {
     use once_cell::sync::Lazy;
     use regex::Regex;
     use tempfile::{tempfile, TempDir};
+    use toml::toml;
 
     use super::*;
 
@@ -479,93 +480,59 @@ mod tests {
     }
 
     impl Config {
-        fn default() -> Self {
-            Self {
-                keep_preprocessed: false,
-                profiles: Default::default(),
-                hosted_html: None,
-                code: CodeConfig {
-                    show_hidden_lines: false,
-                },
-            }
-        }
-
         fn latex() -> Self {
-            Self {
-                keep_preprocessed: true,
-                profiles: HashMap::from_iter([("latex".into(), pandoc::Profile::latex())]),
-                ..Self::default()
-            }
-        }
-
-        fn pdf() -> Self {
-            Config {
-                profiles: HashMap::from_iter([("pdf".into(), pandoc::Profile::pdf())]),
-                ..Self::default()
-            }
-        }
-
-        fn markdown() -> Self {
-            Self {
-                profiles: HashMap::from_iter([("markdown".into(), pandoc::Profile::markdown())]),
-                ..Self::default()
-            }
-        }
-    }
+            toml! {
+                [profile.latex]
+                output-file = "output.tex"
+                standalone = false
 
-    impl pandoc::Profile {
-        fn latex() -> Self {
-            Self {
-                columns: 72,
-                file_scope: true,
-                number_sections: true,
-                output_file: PathBuf::from("output.tex"),
-                pdf_engine: None,
-                standalone: false,
-                to: Some("latex".into()),
-                table_of_contents: true,
-                variables: FromIterator::from_iter([("documentclass".into(), "report".into())]),
-                rest: Default::default(),
+                [profile.latex.variables]
+                documentclass = "report"
             }
+            .try_into()
+            .unwrap()
         }
 
         fn pdf() -> Self {
-            Self {
-                columns: 72,
-                file_scope: true,
-                number_sections: true,
-                output_file: "book.pdf".into(),
-                pdf_engine: Some(
-                    env::var_os("PDF_ENGINE")
-                        .map(Into::into)
-                        .unwrap_or("lualatex".into()),
-                ),
-                standalone: true,
-                to: Some("latex".into()),
-                table_of_contents: true,
-                variables: FromIterator::from_iter([
-                    ("documentclass".into(), "report".into()),
-                    ("mainfont".into(), "Noto Serif".into()),
-                    ("sansfont".into(), "Noto Sans".into()),
-                    ("monofont".into(), "Noto Sans Mono".into()),
-                ]),
-                rest: Default::default(),
+            toml! {
+                keep-preprocessed = false
+
+                [profile.pdf]
+                output-file = "book.pdf"
+                to = "latex"
+                pdf-engine = "lualatex"
+
+                [profile.pdf.variables]
+                documentclass = "report"
+                mainfont = "Noto Serif"
+                sansfont = "Noto Sans"
+                monofont = "Noto Sans Mono"
+                mainfontfallback = [
+                  "NotoColorEmoji:mode=harf",
+                  "NotoSansMath:",
+                  "NotoSerifCJKSC:",
+                ]
+                monofontfallback = [
+                  "NotoColorEmoji:mode=harf",
+                  "NotoSansMath:",
+                  "NotoSansMonoCJKSC:",
+                ]
+                geometry = ["margin=1.25in"]
             }
+            .try_into()
+            .unwrap()
         }
 
         fn markdown() -> Self {
-            Self {
-                columns: 72,
-                file_scope: true,
-                number_sections: true,
-                output_file: PathBuf::from("book.md"),
-                pdf_engine: None,
-                standalone: false,
-                to: Some("markdown".into()),
-                table_of_contents: true,
-                variables: Default::default(),
-                rest: Default::default(),
+            toml! {
+                keep-preprocessed = false
+
+                [profile.markdown]
+                output-file = "book.md"
+                standalone = false
             }
+            .try_into()
+            .unwrap()
         }
     }
 
@@ -587,6 +554,26 @@ mod tests {
         "###);
     }
 
+    #[test]
+    fn broken_links() {
+        let book = MDBook::init()
+            .chapter(Chapter::new(
+                "Getting Started",
+                "[broken link](foobarbaz)",
+                "getting-started.md",
+            ))
+            .build();
+        insta::assert_snapshot!(book, @r###"
+        ├─ log output
+        │  INFO mdbook::book: Running the pandoc backend    
+        │  WARN mdbook_pandoc::preprocess: Unable to normalize link 'foobarbaz' in chapter 'Getting Started': Unable to canonicalize path: $ROOT/src/foobarbaz: No such file or directory (os error 2)    
+        │  WARN mdbook_pandoc: Unable to resolve one or more relative links within the book, consider setting the `hosted-html` option in `[output.pandoc]`    
+        │  INFO mdbook_pandoc::pandoc::renderer: Wrote output to book/markdown/book.md    
+        ├─ markdown/book.md
+        │ [broken link](foobarbaz)
+        "###);
+    }
+
     #[test]
     fn strikethrough() {
         let book = MDBook::init()
@@ -1267,7 +1254,10 @@ include-in-header = ["file-in-root"]
     #[test]
     fn mdbook_guide() {
         let logs = MDBook::load(BOOKS.join("mdBook/guide"))
-            .config(Config::pdf())
+            .config(Config {
+                hosted_html: Some("https://rust-lang.github.io/mdBook/".into()),
+                ..Config::pdf()
+            })
             .build()
             .logs;
         insta::assert_snapshot!(logs);
@@ -1290,7 +1280,10 @@ include-in-header = ["file-in-root"]
     #[test]
     fn rust_book() {
         let logs = MDBook::load(BOOKS.join("rust-book"))
-            .config(Config::pdf())
+            .config(Config {
+                hosted_html: Some("https://doc.rust-lang.org/book/".into()),
+                ..Config::pdf()
+            })
             .build()
             .logs;
         insta::assert_snapshot!(logs);
@@ -1299,7 +1292,10 @@ include-in-header = ["file-in-root"]
     #[test]
     fn nomicon() {
         let logs = MDBook::load(BOOKS.join("nomicon"))
-            .config(Config::pdf())
+            .config(Config {
+                hosted_html: Some("https://doc.rust-lang.org/nomicon/".into()),
+                ..Config::pdf()
+            })
             .build()
             .logs;
         insta::assert_snapshot!(logs);
@@ -1308,7 +1304,10 @@ include-in-header = ["file-in-root"]
     #[test]
     fn rust_by_example() {
         let logs = MDBook::load(BOOKS.join("rust-by-example"))
-            .config(Config::pdf())
+            .config(Config {
+                hosted_html: Some("https://doc.rust-lang.org/rust-by-example/".into()),
+                ..Config::pdf()
+            })
             .build()
             .logs;
         insta::assert_snapshot!(logs);
@@ -1317,7 +1316,10 @@ include-in-header = ["file-in-root"]
     #[test]
     fn rust_edition_guide() {
         let logs = MDBook::load(BOOKS.join("rust-edition-guide"))
-            .config(Config::pdf())
+            .config(Config {
+                hosted_html: Some("https://doc.rust-lang.org/edition-guide/".into()),
+                ..Config::pdf()
+            })
             .build()
             .logs;
         insta::assert_snapshot!(logs);
@@ -1326,7 +1328,10 @@ include-in-header = ["file-in-root"]
     #[test]
     fn rust_embedded() {
         let logs = MDBook::load(BOOKS.join("rust-embedded"))
-            .config(Config::pdf())
+            .config(Config {
+                hosted_html: Some("https://docs.rust-embedded.org/book/".into()),
+                ..Config::pdf()
+            })
             .build()
             .logs;
         insta::assert_snapshot!(logs);
@@ -1335,7 +1340,10 @@ include-in-header = ["file-in-root"]
     #[test]
     fn rust_reference() {
         let logs = MDBook::load(BOOKS.join("rust-reference"))
-            .config(Config::pdf())
+            .config(Config {
+                hosted_html: Some("https://doc.rust-lang.org/reference/".into()),
+                ..Config::pdf()
+            })
             .build()
             .logs;
         insta::assert_snapshot!(logs);
@@ -1344,7 +1352,10 @@ include-in-header = ["file-in-root"]
     #[test]
     fn rustc_dev_guide() {
         let logs = MDBook::load(BOOKS.join("rustc-dev-guide"))
-            .config(Config::pdf())
+            .config(Config {
+                hosted_html: Some("https://rustc-dev-guide.rust-lang.org/".into()),
+                ..Config::pdf()
+            })
             .build()
             .logs;
         insta::assert_snapshot!(logs);

src/preprocess.rs

@@ -13,6 +13,7 @@ use std::{
 
 use aho_corasick::AhoCorasick;
 use anyhow::{anyhow, Context as _};
+use log::log;
 use mdbook::{
     book::{BookItems, Chapter},
     BookItem,
@@ -293,7 +294,13 @@ impl<'book> Preprocessor<'book> {
                                 hosted.push("/");
                                 hosted.push(&path);
                                 let hosted = os_to_utf8(hosted)?;
-                                log::debug!(
+                                log!(
+                                    // In tests, log at a higher level to detect link breakage
+                                    if cfg!(test) {
+                                        log::Level::Info
+                                    } else {
+                                        log::Level::Debug
+                                    },
                                     "Unable to resolve relative path '{}' in chapter '{}', \
                                     linking to hosted HTML book at '{hosted}'",
                                     link_path.display(),