JATS from Markdown

Developer friendly single-source scholarly publishing

Albert Krewinkel, Juanjo BazΓ‘n, Arfon Smith

May 3, 2022

Single-Source Publishing

What?

Produce all publishing artifacts from a single source document.

Why?

  • Single source of truth.
  • Corrections are easy
  • Producing article proofs is quick and simple

Journal of Open Source Software

πŸ‘¨β€πŸ’»πŸ–ΊπŸ–ΉπŸ–»πŸ‘©β€πŸ’»

Markdown to JATS

Architecture

dot graph

Markdown

Markdown JATS Result
*this* <italic>this</italic> this
**that** <bold>that</bold> that
H~2~O H<sub>2</sub>O H2O
Ca^2+^ Ca<sup>2+</sup> Ca2+

pandoc

  • Universal document converter;
  • designed for paper writing;
  • allows flexible document conversion.

Tables

| a | b |
|---|---|
| 1 | 2 |
| 3 | 4 |
<table-wrap>
  <table>
    <thead>
      <tr><th>a</th><th>b</th></tr>
    </thead>
    <tbody>
      <tr><td>1</td><td>2</td></tr>
      <tr><td>3</td><td>4</td></tr>
    </tbody>
  </table>
</table-wrap>

Formulæ

βˆ«βˆ’βˆž+∞eβˆ’x2dx\int_{-\infty}^{+\infty} e^{-x^2} \, dx

$$\int_{-\infty}^{+\infty} e^{-x^2} \, dx$$

<disp-formula>
  <alternatives>
    <tex-math>
<![CDATA[\int_{-\infty}^{+\infty} e^{-x^2} \, dx]]>
    </tex-math>
    <mml:math display="block"
    xmlns:mml="http://www.w3.org/1998/Math/MathML">
    <!-- omitted -->
    </mml:math>
  </alternatives>
</disp-formula>

Citations

@article {Upper1974,
  author = {Upper, Dennis},
  title = {The unsuccessful self-treatment of
           a case of β€œwriter's block”},
  journal = {Journal of Applied Behavior Analysis},
  volume = {7},
  number = {3},
  publisher = {Blackwell Publishing Ltd},
  issn = {1938-3703},
  doi = {10.1901/jaba.1974.7-497a},
  pages = {497--497},
  year = {1974},
}
For a case study on writers
block, see @Upper1974
For a case study on writers block, see Upper
(<xref alt="1974" rid="ref-Upper1974" ref-type="bibr">1974</xref>)

References

<ref id="ref-Upper1974">
  <element-citation publication-type="article-journal">
    <person-group person-group-type="author">
      <name><surname>Upper</surname><given-names>Dennis</given-names></name>
    </person-group>
    <article-title>The unsuccessful self-treatment of a case of
      β€œwriter’s block”</article-title>
    <source>Journal of Applied Behavior Analysis</source>
    <publisher-name>Blackwell Publishing Ltd</publisher-name>
    <year iso-8601-date="1974">1974</year>
    <volume>7</volume>
    <issue>3</issue>
    <issn>1938-3703</issn>
    <pub-id pub-id-type="doi">10.1901/jaba.1974.7-497a</pub-id>
    <fpage>497</fpage>
    <lpage>497</lpage>
  </element-citation>
</ref>

Metadata

Authors & Affiliations

---
authors:
  - name: John Doe
    orcid: 0000-1234-5678-901X
    affiliation: 1

affiliations:
  - name: Federation of Planets
    index: 1
---

Given Names / Surname

Jane Von Doe III

Ludwig van Beethoven

Destructured Names

authors:
  - name:
      given-names: Jane
      surname: Von Doe

  - name:
      given-names: Ludwig
      dropping-particle: van
      surname: Beethoven
<contrib contrib-type="author">
  <name>
    <surname>Von Doe</surname>
    <given-names><!--
    -->Jane</given-names>
  </name>
</contrib>
<contrib contrib-type="author">
  <name>
    <surname>Beethoven</surname>
    <given-names><!--
    -->Ludwig van</given-names>
  </name>
</contrib>

Keywords

tags:
  - space
  - scify

Generated

  • issue, volume, page β„–
  • DOI
  • software archive DOI
  • submission & publishing dates
  • editor
  • reviewers
  • article URLs

Pipeline

Architecture

dot graph

Filters

  • Parse embedded LaTeX,
  • process author names,
  • link author affiliations,
  • set authors’ cor-id,
  • add timestamps,
  • etc.

Containerization

docker run --rm -it \
    -v $PWD:/data \
    -u $(id -u):$(id -g) \
    openjournals/inara \
    -o pdf,crossref \
    path/relative/to/current/directory/paper.md

Future

  • Alternative inputs

    • reStructuredText
    • Quarto
  • JATS as intermediary format

  • Allow easy reuse

Thanks

Appendix

Non-western names

authors:
  - name:
      literal: η«‹θŠ± 瀧
      given-names: 瀧
      surname: η«‹θŠ±
<contrib contrib-type="author">
  <name>
    <surname>η«‹θŠ±</surname>
    <given-names>瀧</given-names>
  </name>
</contrib>

Filter example

function Meta (meta)
  meta.timestamp = os.date('%Y%m%d%H%M%S')
  return meta
end

Formats

Input

  • Markdown,
  • reStructuredText,
  • Jupyter notebooks,
  • Word Docx,
  • LaTeX,
  • JATS,
  • and 30+ more.

Output

  • JATS,
  • LaTeX,
  • EPUB,
  • HTML,
  • and 50+ more.