Pandoc 2.14: update HTML plugins, CSL style, citekey syntax

merges #427 Co-authored-by: Daniel Himmelstein <[email protected]> Co-authored-by: Anthony Gitter <[email protected]>
manubot · Jun 10, 2021 · defe787 · defe787
1 parent 95bf5b2
commit defe787
Show file tree

Hide file tree

Showing 10 changed files with 51 additions and 31 deletions.
diff --git a/USAGE.md b/USAGE.md
@@ -133,14 +133,23 @@ Note that multiple citations must be semicolon separated.
 Be careful not to cite the same study using identifiers from multiple sources.
 For example, the following citations all refer to the same study, but will be treated as separate references: `[@doi:10.7717/peerj.705; @pmc:PMC4304851; @pubmed:25648772]`.
 
-Citation keys must adhere to the syntax described in the [Pandoc manual](https://pandoc.org/MANUAL.html#citations):
-
-> The citation key must begin with a letter, digit, or `_`, and may contain alphanumerics, `_`, and internal punctuation characters (`:.#$%&-+?<>~/`).
-
-To evaluate whether a citation key fully matches this syntax, try [this online regex](https://regex101.com/r/mXZyY2/latest).
-If the citation key is not valid, use the [citation aliases](#citation-aliases) workaround below.
-This is required for citation keys that contain forbidden characters such as `;` or `=` or end with a non-alphanumeric character such as `/`.
-<!-- See [jgm/pandoc#6026](https://github.com/jgm/pandoc/issues/6026) for progress on a more flexible Markdown citation key syntax. -->
+The citation key syntax is described in the [Pandoc manual](https://pandoc.org/MANUAL.html#citation-syntax):
+
+> Unless a citation key start with a letter, digit, or `_`,
+> and contains only alphanumerics and internal punctuation characters (`:.#$%&-+?<>~/`),
+> it must be surrounded by curly braces,
+> which are not considered part of the key.
+> In `@Foo_bar.baz.`, the key is `Foo_bar.baz`.
+> The final period is not *internal* punctuation,
+> so it is not included in the key.
+> In `@{Foo_bar.baz.}`, the key is `Foo_bar.baz.`, including the final period.
+> The curly braces are recommended if you use URLs as keys:
+> `[@{https://example.com/bib?name=foobar&date=2000}, p. 33]`.
+
+If a citation key does not fully match [this online regex](https://regex101.com/r/mXZyY2/latest)
+(for example, contains characters such as `;` or `=` or end with a non-alphanumeric character such as `/`),
+make sure to surround it with curly braces or use the [citation aliases](#citation-aliases) workaround below.
+<!-- See [jgm/pandoc#6026](https://github.com/jgm/pandoc/issues/6026) on the curly-brace syntax for Markdown citation keys, which was introduced in Pandoc 2.14. -->
 
 Prior to Rootstock commit [`6636b91`](https://github.com/manubot/rootstock/commit/6636b912c6b41593acd2041d34cd4158c1b317fb) on 2020-01-14, Manubot processed citations separately from Pandoc.
 Switching to a Pandoc filter improved reliability on complex documents, but restricted the syntax of citation keys slightly.

diff --git a/build/assets/style.csl b/build/assets/style.csl
@@ -47,7 +47,7 @@
       <text variable="citation-number"/>
     </layout>
   </citation>
-  <bibliography hanging-indent="true" second-field-align="flush">
+  <bibliography second-field-align="flush">
     <layout>
       <text variable="citation-number" suffix=". "/>
       <group delimiter=" ">

diff --git a/build/environment.yml b/build/environment.yml
@@ -5,11 +5,10 @@ dependencies:
   - cairo=1.14.12
   - cairocffi=0.8.0
   - cffi=1.12.3
-  - ghp-import=0.5.5
+  - ghp-import=1.0.0
   - jinja2=2.11.2
   - jsonschema=3.2.0
-  - pandoc=2.9.2
-  - panflute=1.12.5
+  - pandoc=2.14
   - pango=1.40.14
   - pip=20.2
   - psutil=5.7.3
@@ -21,14 +20,15 @@ dependencies:
   - yamllint=1.25.0
   - pip:
     - errorhandler==2.0.1
-    - git+https://github.com/manubot/manubot@553090a16ac24a9fdc3f8df241a91b790c140865
+    - git+https://github.com/manubot/manubot@2c028a7a87be24a76e2dec3ac7db6e8754ae6d4a
     - isbnlib==3.10.3
     - opentimestamps-client==0.7.0
     - opentimestamps==0.4.1
-    - pandoc-eqnos==2.3.0
-    - pandoc-fignos==2.3.1
-    - pandoc-tablenos==2.2.2
-    - pandoc-xnos==2.4.3
+    - pandoc-eqnos==2.5.0
+    - pandoc-fignos==2.4.0
+    - pandoc-tablenos==2.3.0
+    - pandoc-xnos==2.5.0
+    - panflute==2.1.0
     - pybase62==0.4.3
     - pysha3==1.0.2
     - python-bitcoinlib==0.10.2

diff --git a/build/pandoc/defaults/common.yaml b/build/pandoc/defaults/common.yaml
@@ -6,7 +6,7 @@ filters:
 - pandoc-eqnos
 - pandoc-tablenos
 - pandoc-manubot-cite
-- pandoc-citeproc
+- citeproc
 wrap: preserve
 metadata:
   csl: build/assets/style.csl

diff --git a/build/pandoc/defaults/html.yaml b/build/pandoc/defaults/html.yaml
@@ -25,6 +25,7 @@ include-after-body:
 - build/plugins/mathjax.html
 #- build/plugins/scite.html
 variables:
+  document-css: false
   math: ""
 html-math-method:
   method: mathjax
diff --git a/build/plugins/anchors.html b/build/plugins/anchors.html
@@ -10,7 +10,8 @@
 <script type="module">
   // which types of elements to add anchors next to, in "document.querySelector"
   // format
-  const typesQuery = 'h1, h2, h3, [id^="fig:"], [id^="tbl:"], [id^="eq:"]';
+  const typesQuery =
+    'h1, h2, h3, div[id^="fig:"], div[id^="tbl:"], span[id^="eq:"]';
 
   // start script
   function start() {

diff --git a/build/plugins/jump-to-first.html b/build/plugins/jump-to-first.html
@@ -15,9 +15,11 @@
 
   // start script
   function start() {
-    if (references !== "false") makeButtons("ref-", "p", "reference");
-    if (figures !== "false") makeButtons("fig:", "figcaption", "figure");
-    if (tables !== "false") makeButtons("tbl:", "caption", "table");
+    if (references !== "false")
+      makeButtons(`div[id^="ref-"]`, ".csl-left-margin", "reference");
+    if (figures !== "false")
+      makeButtons(`div[id^="fig:"]`, "figcaption", "figure");
+    if (tables !== "false") makeButtons(`div[id^="tbl:"]`, "caption", "table");
   }
 
   // when jump button clicked
@@ -45,7 +47,7 @@
 
   // add button next to each reference entry, figure, or table
   function makeButtons(query, containerQuery, subject) {
-    const elements = document.querySelectorAll(`[id^="${query}"`);
+    const elements = document.querySelectorAll(query);
     for (const element of elements) {
       const id = element.id;
       const buttonContainer = element.querySelector(containerQuery);

diff --git a/build/plugins/tooltips.html b/build/plugins/tooltips.html
@@ -230,6 +230,7 @@
       "data-selected",
       "data-highlighted",
       "data-glow",
+      "class",
     ];
     for (const attribute of attributes) {
       sourceCopy.removeAttribute(attribute);
@@ -290,9 +291,8 @@
     prevButton.classList.add("icon_button");
     nextButton.classList.add("icon_button");
     prevButton.innerHTML = document.querySelector(".icon_caret_left").innerHTML;
-    nextButton.innerHTML = document.querySelector(
-      ".icon_caret_right"
-    ).innerHTML;
+    nextButton.innerHTML =
+      document.querySelector(".icon_caret_right").innerHTML;
     navBar.appendChild(prevButton);
     navBar.appendChild(document.createTextNode(text));
     navBar.appendChild(nextButton);
@@ -336,7 +336,7 @@
     if (!target) return;
 
     // if ref or figure, modify target to get expected element
-    if (id.indexOf("ref-") === 0) target = target.querySelector("p");
+    if (id.indexOf("ref-") === 0) target = target.querySelector(":nth-child(2)");
     else if (id.indexOf("fig:") === 0) target = target.querySelector("figure");
 
     return target;

diff --git a/build/themes/default.html b/build/themes/default.html
@@ -267,8 +267,7 @@
   }
 
   /* table auto-number */
-  table > caption > span:first-of-type,
-  div.table_wrapper > table > caption > span:first-of-type {
+  table > caption > span:first-of-type {
     font-weight: bold;
     margin-right: 5px;
   }
@@ -495,6 +494,15 @@
     top: 0.125em;
   }
 
+  /* -------------------------------------------------- */
+  /* references */
+  /* -------------------------------------------------- */
+
+  .csl-entry {
+    margin-top: 15px;
+    margin-bottom: 15px;
+  }
+
   /* -------------------------------------------------- */
   /* print control */
   /* -------------------------------------------------- */
@@ -626,7 +634,6 @@
 
   /* tablenos wrapper */
   .tablenos {
-    /* show scrollbar on tables if necessary to prevent overflow */
     width: 100%;
     margin: 20px 0;
   }

diff --git a/content/02.delete-me.md b/content/02.delete-me.md
@@ -107,7 +107,7 @@ Citation by Wikidata ID [@wikidata:Q56458321].
 
 Citation by ISBN [@isbn:9780262517638].
 
-Citation by URL [@https://greenelab.github.io/meta-review/].
+Citation by URL [@{https://greenelab.github.io/meta-review/}].
 
 Citation by alias [@deep-review].