feat(template): render html and docx output formats and verify in CI

.github/workflows/render.yaml

@@ -0,0 +1,31 @@
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    types: [opened, synchronize, labeled, reopened]
+
+name: Render
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  render:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@c1b50d36cf3c22b3dc7e530bd1b36634e824e545 # v2
+        with:
+          tinytex: true 
+      - name: Render
+        run: |
+          make render
+      - name: Upload artifacts
+        uses: actions/upload-artifact@0b2256b8c012f0828dc542b3febcab082c67f72b # v4
+        with:
+          name: quarto-output-${{ github.ref_name }}-${{ github.sha }}
+          path: "${{ github.workspace }}/example.*"

.gitignore

@@ -4,11 +4,16 @@
 .httr-oauth
 .DS_Store
 /template_files/
+/example_files/
 *.aux
 *.fdb_latexmk
 *.fls
 *.log
 /*.bst
 /*.cls
 template.*
-!template.{qmd,pdf}
+!template.pdf
+!template.qmd
+example.*
+!example.pdf
+!example.qmd

.quartoignore

@@ -1,5 +1,7 @@
-*.pdf
 *.png
 *.rproj
 *.Rproj
+example.qmd
+example.pdf
+template.pdf
 Makefile

Makefile

@@ -66,7 +66,7 @@ download-csl-files: ## Download citation style files. Pass FORCE=1 to download e
 ##@ render article
 #-----------------
 
-DOCUMENT_NAME ?= template
+DOCUMENT_NAME ?= example
 
 render-latex: ## Render the article via LaTeX
 	quarto render $(DOCUMENT_NAME).qmd --to nature-pdf

README.md

@@ -88,23 +88,24 @@ Note that this template does not contribute a `html` or `docx` format itself.
   html:
     code-fold: true
     html-math-method: katex
-csl: _extensions/nature/christopherkenny/csl/springer-basic-author-date.csl
+csl: _extensions/christopherkenny/nature/csl/springer-basic-author-date.csl
 ```
+
 ```yaml
   docx: default
-csl: _extensions/nature/christopherkenny/csl/springer-basic-author-date.csl
+csl: _extensions/christopherkenny/nature/csl/springer-basic-author-date.csl
 ```
 
 [^1]: The vendored Citation Style Language (CSL) files are copyrighted by the [Citation Style Language project](https://citationstyles.org/). These files have not been modified and are redistributed as licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License ([CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/)).
 
 ## Example
 
-Here is the source code for a minimal sample document: [template.qmd](template.qmd).
+Here is the source code for a minimal sample document: [example.qmd](example.qmd).
 
 <!-- pdftools::pdf_convert('template.pdf',pages = 1) -->
 <div style="width: 100%; text-align: left;">
-  <a href="template.pdf">
-    <img src="template_1.png" width="500" alt="link to template.pdf" style="max-width:100%;height:auto;">
+  <a href="example.pdf">
+    <img src="example_1.png" width="500" alt="link to example.pdf" style="max-width:100%;height:auto;">
   </a>
 </div>
 

example.qmd

@@ -0,0 +1,129 @@
+---
+title: Quarto Template for Springer Nature
+format:
+  nature-pdf:
+    # journal.cite-style is included in the tex file but ignored by pandoc if 
+    # cite-method is not `natbib`.
+    journal:
+      cite-style: sn-nature
+    # `citeproc` is the pandoc default. Set `cite-method: natbib` if required
+    # to use the bst styles from the upstream template.
+    cite-method: citeproc
+    keep-tex: true
+    equal-margins: false
+  html:
+    code-fold: true
+    html-math-method: mathjax
+  docx: default
+# The `csl` style will be used with LaTeX-based rendering of`nature-pdf`
+# if cite-method is `citeproc`. This is also the default if cite-method
+# is not specified.
+#
+# If attempting to render this extension template in an end-user project,
+# where you have executed a command like
+# $ quarto add christopherkenny/nature
+# you will need to modify the csl path to point to the correct location, e.g.
+# csl: _extensions/christopherkenny/nature/csl/springer-basic-author-date.csl
+# where `christopherkenny` will be used as the namespace for the extension.
+# see: https://quarto.org/docs/extensions/distributing.html#github-distribution
+csl: _extensions/nature/csl/springer-basic-brackets-no-et-al.csl
+author:
+  - name: Author One
+    affiliations:
+      - name: Harvard University
+        id: 1
+        department: Department of Government
+        address: 1737 Cambridge Street
+        city: Cambridge
+        state: MA
+        postal-code: 02138
+      - name: Harvard University
+        id: 2
+        department: Department of Statistics
+        address: 1 Oxford Street
+        city: Cambridge
+        state: MA
+        postal-code: 02138
+    attributes:
+      equal-contributor: true
+  - name: Author Two
+    affiliations:
+      - name: Yale University
+        id: 3
+        department: Department of Political Science
+        address: 115 Prospect Street
+        city: New Haven
+        state: CT
+        postal-code: 06511
+    email: [email protected]
+    attributes:
+      equal-contributor: true
+      corresponding: true
+  - name: Author Three
+    affiliations:
+      - ref: 1
+abstract: |
+  The abstract serves both as a general introduction to the topic and as a brief, non-technical summary of the main results and their implications. Authors are advised to check the author instructions for the journal they are submitting to for word limits and if structural elements like subheadings, citations, or equations are permitted.
+keywords: [template, demo]
+bibliography: bibliography.bib  
+---
+
+# Introduction {#sec-intro}
+
+The Introduction section, of referenced text [@greenwade93] expands on the background of the work (some overlap with the Abstract is acceptable). The introduction should not include subheadings.
+
+Springer Nature does not impose a strict layout as standard however authors are advised to check the individual requirements for the journal they are planning to submit to as there may be journal-level preferences. When preparing your text please also be aware that some stylistic choices are not supported in full text XML (publication version), including coloured font. These will not be replicated in the typeset article if it is accepted. 
+
+# Using this template {#sec-template}
+
+This Quarto template is unofficial and built out of Springer Nature's template. 
+Some examples of commonly used commands and features are listed below, to help you get started.
+
+As seen below, you can mix markdown and Latex with each other, though it's likely best to mostly use markdown.
+
+## Cross Referencing
+
+To reference a figure with example label "plot", use `@fig-plot`. 
+Analogously, to reference a table with example label "data", use `@tbl-data`.
+To reference a section, such as the Introduction (@sec-intro), use `@sec-intro`.
+
+For complete information on cross referencing with Quarto, see <https://quarto.org/docs/authoring/cross-references.html>.
+
+## Citations
+
+Quarto formats citations and references automatically using the bibliography records in your .bib file. For a single citation use [@greenwade93]. For multiple citations use [@greenwade93;@knuth1984texbook]. If using an author-date-based citation style, then for a citation in parentheses use `[@greenwade93]` and for a text citation use `@greenwade93`. You can drop the author using `[-@greenwade93]`. If the tex output is to be included in a submission to a preprint server or publisher, the default citation method, `citeproc`, may not always produce bibliographies compatible with the provided `bst` styles. In this case, you can set `cite-method: natbib`. See <https://quarto.org/docs/authoring/footnotes-and-citations.html#sec-biblatex>. In this case, you may either restrict usage to the default bracketed key citation formats supported by pandoc, such as [@greenwade93] or [@greenwade93;@knuth1984texbook]. Or, use a CSL file, several of which are vendored in [_extensions/nature/csl](./_extensions/nature/csl/). The advantage of the latter is that references will be consistent across html, docx, and pdf outputs. See <https://pandoc.org/MANUAL.html#citation-syntax> for additional details on pandoc citation styles.
+
+# Tables and Figures
+
+To include figures, you can use Quarto syntax.
+
+![An example figure (an empty plot)](fig.pdf){#fig-plot}
+
+For both figures and tables, you can use LaTeX syntax if you need additional customizability. 
+
+For example, to use footnotes within a table, you may want to use LaTeX.
+
+\begin{table}[h]
+\caption{LaTeX caption text}\label{tbl-data}%
+\begin{tabular}{@{}llll@{}}
+\toprule
+Column 1 & Column 2  & Column 3 & Column 4\\
+\midrule
+row 1    & data 1   & data 2  & data 3  \\
+row 2    & data 4   & data 5\footnotemark[1]  & data 6  \\
+row 3    & data 7   & data 8  & data 9\footnotemark[2]  \\
+\botrule
+\end{tabular}
+\footnotetext{Source: This is an example of table footnote. This is an example of table footnote.}
+\footnotetext[1]{Example for a first table footnote. This is an example of table footnote.}
+\footnotetext[2]{Example for a second table footnote. This is an example of table footnote.}
+\end{table}
+
+# References
+<!-- the pattern below controls the placement of the references -->
+:::{#refs}
+:::
+
+# Appendix {.appendix}
+
+{{< lipsum 5 >}}

template.qmd

@@ -8,9 +8,25 @@ format:
       cite-style: sn-nature
     # `citeproc` is the pandoc default. Set `cite-method: natbib` if required
     # to use the bst styles from the upstream template.
-    cite-method: natbib
+    cite-method: citeproc
     keep-tex: true
     equal-margins: false
+  html:
+    code-fold: true
+    html-math-method: mathjax
+  docx: default
+# The `csl` style will be used with LaTeX-based rendering of`nature-pdf`
+# if cite-method is `citeproc`. This is also the default if cite-method
+# is not specified.
+#
+# If attempting to render this extension template in an end-user project,
+# where you have executed a command like
+# $ quarto add christopherkenny/nature
+# you will need to modify the csl path to point to the correct location, e.g.
+# csl: _extensions/christopherkenny/nature/csl/springer-basic-author-date.csl
+# where `christopherkenny` will be used as the namespace for the extension.
+# see: https://quarto.org/docs/extensions/distributing.html#github-distribution
+csl: _extensions/christopherkenny/nature/csl/springer-basic-brackets-no-et-al.csl
 author:
   - name: Author One
     affiliations:
@@ -75,13 +91,13 @@ For complete information on cross referencing with Quarto, see <https://quarto.o
 
 ## Citations
 
-Quarto formats citations and references automatically using the bibliography records in your .bib file. For a citation in parentheses use [@greenwade93]. Multiple citations can be given as [@greenwade93;@knuth1984texbook]. If the tex output is to be included in a submission to a preprint server or publisher, the default citation method, `citeproc`, may not always produce bibliographies compatible with the provided `bst` styles. In this case, you can set `cite-method: natbib`. See <https://quarto.org/docs/authoring/footnotes-and-citations.html#sec-biblatex>. In this case, you may either restrict usage to the default bracketed key citation formats supported by pandoc, such as [@greenwade93] or [@greenwade93;@knuth1984texbook]. Or, use a CSL file, several of which are vendored in [_extensions/nature/csl](https://github.com/christopherkenny/nature/tree/main/_extensions/nature/csl). The advantage of the latter is that references will be consistent across html, docx, and pdf outputs. See <https://pandoc.org/MANUAL.html#citation-syntax> for additional details on pandoc citation styles.
+Quarto formats citations and references automatically using the bibliography records in your .bib file. For a single citation use [@greenwade93]. For multiple citations use [@greenwade93;@knuth1984texbook]. If using an author-date-based citation style, then for a citation in parentheses use `[@greenwade93]` and for a text citation use `@greenwade93`. You can drop the author using `[-@greenwade93]`. If the tex output is to be included in a submission to a preprint server or publisher, the default citation method, `citeproc`, may not always produce bibliographies compatible with the provided `bst` styles. In this case, you can set `cite-method: natbib`. See <https://quarto.org/docs/authoring/footnotes-and-citations.html#sec-biblatex>. In this case, you may either restrict usage to the default bracketed key citation formats supported by pandoc, such as [@greenwade93] or [@greenwade93;@knuth1984texbook]. Or, use a CSL file, several of which are vendored in [_extensions/nature/csl](./_extensions/nature/csl/). The advantage of the latter is that references will be consistent across html, docx, and pdf outputs. See <https://pandoc.org/MANUAL.html#citation-syntax> for additional details on pandoc citation styles.
 
 # Tables and Figures
 
 To include figures, you can use Quarto syntax.
 
-![An example figure (an empty plot)](fig.eps){#fig-plot}
+![An example figure (an empty plot)](fig.pdf){#fig-plot}
 
 For both figures and tables, you can use LaTeX syntax if you need additional customizability. 
 
@@ -110,4 +126,4 @@ row 3    & data 7   & data 8  & data 9\footnotemark[2]  \\
 
 # Appendix {.appendix}
 
-{{< lipsum 5 >}}
+{{< lipsum 5 >}}