Basic Formatting

Markdown supports both asterisk and underscore methods to express <em> and <strong> elements. In Jatdown, there is only one way to express bold or italic content; the other forms are used for underline and overline. A listing of inline formatting syntax and their corresponding JATS equivalents are given in Table 1.

External Links and Cross References

Markdown implementation typically support three or more forms of linking: these are known as inline links , reference links , and autolinks . Depending on the link destination (the URL), an <ext-link> or <xref> element is created.

• Inline link : [JATS](http://jats.nlm.nih.gov/ "JATS Homepage") becomes <ext-link xlink:href="http://jats.nlm.nih.gov/" alt="JATS homepage">JATS</ext-link>
• Reference link : [JATS][1] becomes <ext-link xlink:href="http://jats.nlm.nih.gov/" alt="JATS homepage">JATS</ext-link> assuming there is a link reference definition line such as [1]: http://jats.nlm.nih.gov "JATS homepage" somewhere in the document.
• Autolink : <http://jats.nlm.nih.gov> becomes <ext-link xlink:href="http://jats.nlm.nih.gov">http://jats.nlm.nih.gov</ext-link> .

If the link destination starts with a hash-character, it is interpreted as an internal link (similar to HTML) and rendered as an <xref> , using the Camel-Cased label as the linking mechanism. For example:

• Inline cross-reference : [Figure 1](#Figure1) becomes <xref ref-type="figure" rid="Figure1">Figure 1</xref> assuming there is a <fig><label>Figure 1</label>...</fig> block in the document.

Citations

Markdown parsers officially recognize a subset of possible URI schemes as valid links. Jatdown processes pmid: and doi: link schemes in a special manner. If links of these types are discovered, Pubmed or Crossref (respectively) are queried for citation metadata and the corresponding reference is constructed in the <ref-list> .

For example, <http://doi.org/10.1038/nphys1170> , having the scheme http , is interpreted as a typical external link that happens to point to a digital object identifier.

However, <doi:10.1038/nphys1170> is interpreted as a request to fetch the metadata for that DOI from crossref, construct a <ref id="bibr-doi_10.1038-nphys1170"><element citation>... for the citation (if one does not exist already), and generate an <xref ref-type="bibr" rid="bibr-doi_10.1038-nphys1170">(Aspelmeyer 2009)</xref> , using a pre-configured CSL style to format the xref content.

Multiple citations can be specified to generate a citation cluster (an xref having multiple IDREFs). A simplified example: <doi:A,doi:B,doi:C> becomes <xref rid="bibr-doi_A bibr-doi_B bibr-doi_C">[1-3]</xref> .

Additional metadata providers other than pubmed.org (pmid:) and http://crossref.org (doi:) can be implemented in the future.

Footnotes

Footnotes in Jatdown work like PHP-Markdown and hence like reference-style links. A footnote is made of two elements: a footnote marker in the text that will become a superscript number and a footnote definition that will be placed in a list of footnotes in the nearest footnote-compatible block. See the <table-wrap> wrapper block example (given below) for an example.

Footnotes bubble up into the nearest containing footnote-compatible block (content model supports <fn-group> ). These include <table-wrap> , <sec> , <abstract> , <front> , and <back> .

Sections

A Markdown document is can be partitioned into sections via the use of ATX or Setext style headers. These map relatively easily to JATS <sec> elements, but one then needs to convert to a nested structure. For example, consider the the following Markdown:

# Materials & Methods
...

### Description of Study
...

## Protocol for Data Collection
...

# Results
...

A Markdown parser will typically not assign nested structure according to the header level. For example, the following HTML will typically be generated:

<H1>Materials &amp; Methods</H1>
<p>...</p>
<H2>Description of Study</H2>
<p>...</p
<H2>Protocol for Data Collection</H2>
<p>...</p>
<H1>Results</H1>
<p>...</p>

JATS expects a nested structure. In Jatdown, a post-processing step is applied to assign the correct nesting based on the relative ordering of header levels:

<sec disp-level="1">
 <title>Materials &amp; Methods</title>
 <p>...</p>

 <sec disp-level="2">
  <title>Description of Study</title>
  <p>...</p>
 </sec>

 <sec disp-level="2">
  <title>Protocol for Data Collection</title>
  <p>...</p>
 </sec>

</sec>

<sec disp-level="1">
 <title>Results</title>
  <p>...</p>
</sec>

Although section nesting is done by the relative ordering of header levels, the original header level numeric value (the number of pound-sign characters) is preserved in the disp-level attribute.

Lists

Lists in Markdown are recognized by common list prefixes given in Table 2. Sublists are expressed by indenting a list item by four spaces relative to the previous list item.

A significant difference between JATS and HTML is that list items cannot contain inline elements, but are instead buffered by an additional paragraph element. Also, sublists must exist within a list-item. Therefore, in transforming Jatdown to JATS, care must be taken to ensure that sublists are contained with list-items and list-items are padded with paragraph elements. For example:

1. Item 1
2. Item 2
    * Bullet A
    * Bullet B

Is transformed to:

<list list-type="order">
 <list-item><p>Item 1</p></list-item>
 <list-item><p>Item 2</p></list-item>
 <list-item>
  <list list-type="bullet">
   <list-item><p>Bullet A</p></list-item>
   <list-item><p>Bullet B</p></list-item>
  </list>
 </list-item>
</list>

An optional alternative rendering would explicitly assign a <label/> element to each list item according to the JATS content model for list-item: (label?, title?, (p | def-list | list)+)) however in the current Jatdown implementation this is not done as the list-item label is implied by the list-type.

Definition Lists

Work on definition lists is not complete, but is likely to use a bracketed list item prefix to define the list structure in conjunction with a wrapper section (see below) to indicate the <def-list> label and title. For example:

# [Definitions 1] Abbreviations

- [PAP-1] poly(A)polymerase I 
- [PNPase] polynucleotide phosphorylase

Woud be tranformed to:

<def list>
 <label>Definitions 1</label>
 <title>Abbreviations</title>

 <def-item>
  <term>PAP-1</term>
  <def><p>poly(A)polymerase I</p></def>
 </def-item>

 <def-item>
  <term>PNPase</term>
  <def><p>polynucleotide phosphorylase</p></def>
 </def-item>

</def-list>

Code Blocks

Blocks of preformatted text are expressed in Markdown as either indented code blocks (each line is indented by four spaces) or fenced code blocks (delimited by lines with three or more fence characters (typically a backtick or tilde character). These are usually converted to <pre><code>...</code></pre> HTML. In Jatdown, these are converted to <preformat> blocks. If the fenced code block is used (preferred), the info-string (the text on the opening fence line) is passed to the preformat-type attribute. For example:

```javascript
var sayHello = function() {
    alert('Hello World!')
}
```

Is converted to:

<preformat preformat-type="javascript" xml:space="preserve">
var sayHello = function() {
    alert('Hello World!')
}
</preformat>

The preformat-type can be used to facilitate syntax highlighting. As Pubref uses Prism.js, the recommended attribute values to identify programming languages for syntax highlighting is given in Table 3:

Block Quotes

Markdown blockquotes (a line starting with a open-angle bracket > ) are converted to <disp-quote> elements. If the last line of a blockquote starts with two dashes, this is translated to the attribution.

> Dead flies cause the ointment of the apothecary to send forth a
> stinking savor; so doth a little folly him that is in reputation
> for wisdom and honour.
> -- Ecclesiastes 10:1

Becomes:

<disp-quote>
 <p>
  Dead flies cause the ointment of the apothecary to send forth a
  stinking savor; so doth a little folly him that is in reputation
  for wisdom and honour.
 </p>
 <attrib>Ecclesiastes 10:1</attrib>
</disp-quote>

Equations

Jatdown follows the example of other Markdown processors by borrowing the inline and display math delimiters native to LaTeX. These are converted to <inline-formula> and <disp-formula> , respectively. For example, the inline math equation $V = IR$ ($V = IR$) becomes:

<inline-formula>
 <alternatives>
  <tex-math notation="LaTeX">V = IR</tex-math>
  <mml:math>...</mml:math>
 </alternatives>
</inline-formula>

Note that the LaTeX syntax is preserved in the <tex-math> element, and the corresponding MathML is included (not shown for brevity in the example). Display math $E = mc^2$ follows a similar pattern:

<disp-formula>
 <alternatives>
  <tex-math notation="LaTeX">E = mc^2</tex-math>
  <mml:math>...</mml:math>
 </alternatives>
</disp-formula>

Tables

Currently GitHub-flavored Markdown table syntax is supported. Support for more complex tables is an ongoing area of study. Clearly, good table support is important in scholarly publishing. One observation is that many tables generally resemble nested lists, and a possible hybrid list + table syntax is being considered. An alternative is to adapt concepts from LaTeX.

Currently, Jatdown generates XHTML-based <table> with a formal structure that always includes a <colgroup> , a <thead> , and a <tbody> .

For example:

|  A  |  B  |  C  | <-- thead
|:----|:---:|----:| <-- colgroup (optional alignment specifiers)
|  1  |  2  |  3  | <-- tbody

Becomes (abbreviated):

```jats
<table>
 <colgroup>
  <col style="align: left"/>
  <col style="align: center"/>
  <col style="align: left"/>
 </colgroup>
 <thead>...</thead>
 <tbody>...</tbody>
</table>

Labeled Sections

<sec> , <fig> , <table-wrap> (and others) have the same basic content model that includes an optional label, and optional title, and some other content. Jatdown re-uses the ATX header syntax to denote these kind of blocks if the header content begins with the general pattern (WHITESPACE, OPEN_BRACKET, NOT_CLOSE_BRACKET+, CLOSE_BRACKET) . For example, a <fig> can be expressed as:

# [Figure 1] Type II CRISPR-Cas

![](./figures/type-2-crispr.tif)

Genetic organization of the type II-A CRISPR-Cas system...

Which becomes:

<fig id="fig-Figure1">
<label>Figure 1</label>
<graphic xlink:href="figures/type-2-crispr.tif" mimetype="image" mime-subtype="tiff"/>
<caption>
 <title>Type II CRISPR-Cas</title>
 <p>Genetic organization of the type II-A CRISPR-Cas system...</p>
</caption>

Similarly, a table-wrap block:

# [Table 1]: Patient Characteristics

|         | Pre (n=151) | Post (n=146)[^1] |
|---------|-------------|------------------|
| Ascites | 89 (59%)    | 34 (22%)         |

Number of patients with ascites pre- and post- treatment.

[^1]: Data not available for 1 trial.

Becomes:

<table-wrap id="table-wrap-Table1">
 <label>Table 1</label>
 <table>...</table>
 <caption>
  <title>Patient Characteristics</title>
  <p>Number of patients with ascites pre- and post- treatment.</p>
 </caption>
 <table-wrap-foot>
  <fn-group>
   <fn id="TF1-150"><p>Data not available for 1 trial.</p></fn>
  </fn-group>
 </table-wrap-foot>
</table-wrap>

A similar section labeling pattern will be applied for special sections such as <abstract> , <ack> , <license> , <notes> , <statement> .

JATS-XML Blocks

Similar to HTML blocks in Markdown, Jatdown optionally supports inclusion of raw JATS XML when needed. It is the onus of the author to ensure that the XML is well-formed and sensible for the document context.