build: configure pandoc using --defaults files

merges #290

The options for the pandoc commands in build/build.sh are now configured
in YAML files that are passed to Pandoc using --defaults.

export PANDOC_DEFAULTS_DIR to override the directory with pandoc --defaults files

build/README.md

@@ -1,7 +1,7 @@
 # Building the manuscript
 
 [`build.sh`](build.sh) builds the repository.
-`sh build/build.sh` should be executed from the root directory of the repository.
+`bash build/build.sh` should be executed from the root directory of the repository.
 By default, `build.sh` creates HTML and PDF outputs.
 However, setting the `BUILD_PDF` environment variable to `false` will suppress PDF output.
 For example, run local builds using the command `BUILD_PDF=false bash build/build.sh`.
@@ -10,8 +10,11 @@ To build a DOCX file of the manuscript, set the `BUILD_DOCX` environment variabl
 For example, use the command `BUILD_DOCX=true bash build/build.sh`.
 To export DOCX for all Travis builds, set a [Travis environment variable](https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings).
 Currently, equation numbers via `pandoc-eqnos` are not supported for DOCX output.
-There is varying support for embedding images in DOCX output.
-Please reference [Pull Request #40](/~https://github.com/manubot/rootstock/pull/40) for possible solutions and continued discussion.
+
+Format conversion is done using [Pandoc](https://pandoc.org/MANUAL.html).
+`build.sh` calls `pandoc` commands using the options specified in [`pandoc-defaults`](pandoc-defaults).
+Each file specifies a set of pandoc `--defaults` options for a given format.
+To change the options, either edit the YAML files directly or add additional `--defaults` files.
 
 ## Environment
 

build/build.sh

@@ -19,42 +19,19 @@ manubot process \
   --cache-directory=ci/cache \
   --log-level=INFO
 
-# pandoc settings
-CSL_PATH=build/assets/style.csl
-BIBLIOGRAPHY_PATH=output/references.json
-INPUT_PATH=output/manuscript.md
+# Pandoc's configuration is specified via files of option defaults
+# located in the PANDOC_DEFAULTS_DIR directory.
+PANDOC_DEFAULTS_DIR="${PANDOC_DEFAULTS_DIR:-build/pandoc-defaults}"
 
 # Make output directory
 mkdir -p output
 
 # Create HTML output
-# http://pandoc.org/MANUAL.html
+# https://pandoc.org/MANUAL.html
 echo >&2 "Exporting HTML manuscript"
 pandoc --verbose \
-  --from=markdown \
-  --to=html5 \
-  --filter=pandoc-fignos \
-  --filter=pandoc-eqnos \
-  --filter=pandoc-tablenos \
-  --bibliography="$BIBLIOGRAPHY_PATH" \
-  --csl="$CSL_PATH" \
-  --metadata link-citations=true \
-  --include-after-body=build/themes/default.html \
-  --include-after-body=build/plugins/anchors.html \
-  --include-after-body=build/plugins/accordion.html \
-  --include-after-body=build/plugins/tooltips.html \
-  --include-after-body=build/plugins/jump-to-first.html \
-  --include-after-body=build/plugins/link-highlight.html \
-  --include-after-body=build/plugins/table-of-contents.html \
-  --include-after-body=build/plugins/lightbox.html \
-  --include-after-body=build/plugins/attributes.html \
-  --mathjax \
-  --variable math="" \
-  --include-after-body=build/plugins/math.html \
-  --include-after-body=build/plugins/hypothesis.html \
-  --include-after-body=build/plugins/analytics.html \
-  --output=output/manuscript.html \
-  "$INPUT_PATH"
+  --defaults="$PANDOC_DEFAULTS_DIR/common.yaml" \
+  --defaults="$PANDOC_DEFAULTS_DIR/html.yaml"
 
 # Return null if docker command is missing, otherwise return path to docker
 DOCKER_EXISTS="$(command -v docker || true)"
@@ -66,20 +43,9 @@ if [ "${BUILD_PDF:-}" != "false" ] && [ -z "$DOCKER_EXISTS" ]; then
   if [ -L images ]; then rm images; fi  # if images is a symlink, remove it
   ln -s content/images
   pandoc \
-    --from=markdown \
-    --to=html5 \
-    --pdf-engine=weasyprint \
-    --pdf-engine-opt=--presentational-hints \
-    --filter=pandoc-fignos \
-    --filter=pandoc-eqnos \
-    --filter=pandoc-tablenos \
-    --bibliography="$BIBLIOGRAPHY_PATH" \
-    --csl="$CSL_PATH" \
-    --metadata link-citations=true \
-    --webtex=https://latex.codecogs.com/svg.latex? \
-    --include-after-body=build/themes/default.html \
-    --output=output/manuscript.pdf \
-    "$INPUT_PATH"
+    --defaults="$PANDOC_DEFAULTS_DIR/common.yaml" \
+    --defaults="$PANDOC_DEFAULTS_DIR/html.yaml" \
+    --defaults="$PANDOC_DEFAULTS_DIR/pdf-weasyprint.yaml"
   rm images
 fi
 
@@ -111,18 +77,8 @@ fi
 if [ "${BUILD_DOCX:-}" = "true" ]; then
   echo >&2 "Exporting Word Docx manuscript"
   pandoc --verbose \
-    --from=markdown \
-    --to=docx \
-    --filter=pandoc-fignos \
-    --filter=pandoc-eqnos \
-    --filter=pandoc-tablenos \
-    --bibliography="$BIBLIOGRAPHY_PATH" \
-    --csl="$CSL_PATH" \
-    --metadata link-citations=true \
-    --reference-doc=build/themes/default.docx \
-    --resource-path=.:content \
-    --output=output/manuscript.docx \
-    "$INPUT_PATH"
+    --defaults="$PANDOC_DEFAULTS_DIR/common.yaml" \
+    --defaults="$PANDOC_DEFAULTS_DIR/docx.yaml"
 fi
 
 echo >&2 "Build complete"

build/environment.yml

@@ -9,7 +9,7 @@ dependencies:
   - jinja2=2.10.3
   - jsonschema=3.1.1
   - pandas=0.25.2
-  - pandoc=2.7.3
+  - pandoc=2.9
   - pango=1.40.14
   - pip=19.3
   - psutil=5.6.3

build/pandoc-defaults/common.yaml

@@ -0,0 +1,13 @@
+# Pandoc --defaults shared between Manubot output formats.
+from: markdown
+input-file: output/manuscript.md
+filters:
+- pandoc-fignos
+- pandoc-eqnos
+- pandoc-tablenos
+- pandoc-citeproc
+wrap: preserve
+metadata:
+  bibliography: output/references.json
+  csl: build/assets/style.csl
+  link-citations: true

build/pandoc-defaults/docx.yaml

@@ -0,0 +1,8 @@
+# Pandoc --defaults for DOCX output.
+# Load on top of common defaults.
+to: docx
+output-file: output/manuscript.docx
+reference-doc: build/themes/default.docx
+resource-path:
+ - '.'
+ - content

build/pandoc-defaults/html.yaml

@@ -0,0 +1,21 @@
+# Pandoc --defaults for HTML output.
+# Load on top of common defaults.
+to: html5
+output-file: output/manuscript.html
+include-after-body:
+- build/themes/default.html
+- build/plugins/anchors.html
+- build/plugins/accordion.html
+- build/plugins/tooltips.html
+- build/plugins/jump-to-first.html
+- build/plugins/link-highlight.html
+- build/plugins/table-of-contents.html
+- build/plugins/lightbox.html
+- build/plugins/attributes.html
+- build/plugins/math.html
+- build/plugins/hypothesis.html
+- build/plugins/analytics.html
+variables:
+  math: ''
+html-math-method:
+  method: mathjax

build/pandoc-defaults/pdf-weasyprint.yaml

@@ -0,0 +1,9 @@
+# Pandoc --defaults for PDF output via weasyprint.
+# Load on top of HTML defaults.
+output-file: output/manuscript.pdf
+pdf-engine: weasyprint
+pdf-engine-opts:
+- '--presentational-hints'
+html-math-method:
+  method: webtex
+  url: 'https://latex.codecogs.com/svg.latex?'