ScholarlyMarkdown: a Markdown-compatible plaintext format for academic communication

ScholarlyMarkdown math support

Math as (fenced) code blocks

This is a line of text with a simple code block in it.

`this should be just a `normal` inline code block surrounded by literal backticks`

This is another line of text. Here should be some math: \(\mathbf{F = ma}<2\mathbf{ma}\). There should be some displaymath environment on the following line \[ \begin{equation*} \mathbf{F = ma} < 2\mathbf{ma} \end{equation*} \] and there should be no line breaks between the displaymath block and here. This should be bold. This should be italic.

The following is a displaymath with an aligned environment in a separate paragraph (preceded with, and followed by, two blank lines), with identifier matheqn1. It should automatically be wrapped with the aligned environment.

\[ \begin{equation} \label{matheqn1} \begin{aligned} \tag{BIGLABEL} \mbox{minimize}\quad & \fx = \max_{i=1,\ldots,m} (a_i^T x + b_i) \\ & \|x\|_2 \le \sigma. \end{aligned} \end{equation} \]

Here is an implicit align math environment consisting of multiple lines of equations with no newline in between, with at least one & symbol in the whole expression. It should be in the same paragraph as this one. \[ \begin{align} \nonumber \sum_{j_1, j_2, \ldots j_m} \sum_{k_1, k_2, \ldots, k_m} & \widetilde{A}_{j_1,k_1}^{\ast} \widetilde{A}_{j_1,k_2} \tilde{A}_{j_2,k_2}^{\ast} \widetilde{A}_{j_2,k_3} \ldots \widetilde{A}_{j_m,k_m}^{\ast} \widetilde{A}_{j_m,k_1}\\ \label{middleAlignMathNumber} = \sum_{j_1, j_2, \ldots j_m} \sum_{k_1, k_2, \ldots, k_m} & \left( R_{\Lambda} T_{k_1}^{\ast} P_{\Omega} T_{j_1} R_{\Lambda}^{\ast} \right) \left( R_{\Lambda} T_{j_1}^{\ast} P_{\Omega} T_{k_2} R_{\Lambda}^{\ast} \right) \left( R_{\Lambda} T_{k_2}^{\ast} P_{\Omega} T_{j_2} R_{\Lambda}^{\ast} \right)\\ \nonumber & \left( R_{\Lambda} T_{j_2}^{\ast} P_{\Omega} T_{k_3} R_{\Lambda}^{\ast} \right) \ldots \left( R_{\Lambda} T_{k_m}^{\ast} P_{\Omega} T_{j_m} R_{\Lambda}^{\ast} \right) \left( R_{\Lambda} T_{j_m}^{\ast} P_{\Omega} T_{k_1} R_{\Lambda}^{\ast} \right). \end{align} \] And here is an implicit gather math environment consisting of multiple lines of equations with no newline in between, with & symbol not appearing in every statement: \[ \begin{gather} \label{firstGatherMathNumber} \left.\begin{aligned} B'&=-\partial\times E\\ E'&=\partial\times B - 4\pi j \end{aligned} \right\} \quad \textsf{Maxwell's equations}\\ \label{secondGatherMathNumber} A = B\\ \label{thirdgathernumber} AAAAAAA = BBBBBB \end{gather} \]

Single math equations that have line-breaks (the \\ command) are automatically wrapped in a split environment. If alignment commands (symbol &) also exist, they get wrapped in an aligned environment instead. This behaviour can be disabled using the math_plain environment: \[ \begin{equation*} \begin{split} y = ax \\ f = kg^{-1} \end{split} \end{equation*} \] \[ \begin{equation*} \begin{aligned} y &= ax \\ f &= kg^{-1} \end{aligned} \end{equation*} \] The following has an ampersand and line breaks in comma, but is actually a single-line equation that should be untouched: \[ \begin{equation*} |y|\ \&\ |x| % an & and \\ that should be ignored = 99\% z % an & and \\ that should be ignored \end{equation*} \] Below is more internal vertical alignment tests. The first is one that uses cases internally: \[ \begin{equation} \label{matheqn2} P_{r-j}=\begin{cases} 0& \ensuremath\text{if $r-j$ is odd},\\ r!\,(-1)^{(r-j)/2}& \text{if $r-j$ is even}, \end{cases} \end{equation} \] and another one that uses aligned internally. \[ \begin{equation} \label{matheqn3} \left.\begin{aligned} B'&=-\partial\times E\\ E'&=\partial\times B - 4\pi j \end{aligned} \right\} \qquad \text{Maxwell's equations} \end{equation} \]

Math and lists

Here’s a list with both inline and display math environments:

• Item 1 is a famous item
• Item 2 with a code block and \(\mathsf{\text{inline math}}\) with equation \(\mathbf{y=Ax}\)
• Item 3
  • Indented item 4
  • Indented item 5, followed by display math, which cannot be indented: \[ \begin{equation*} \mathbf{F_1 = m_1a} \end{equation*} \] with some text below
  • Indented item 6, which does not recognize list-item display math surrounded by one additional blank line:

\[ \begin{equation*} \mathbf{F_2 = m_2a} \end{equation*} \]

  without breaking this text out of the list and into a pre block

• Item 4
  1. Numerical Item 1
  2. Numerical item 2

Scholarly X-refs

References to figures

This line refers to Figure 3.

This line refers to Figure 2.

This line refers to subfigure (2c).

References to equations

This line refers to Equation \(\eqref{matheqn3}\).

Referencing using the \ref tag: Equation \(\ref{matheqn1}\).

Referencing using the \eqref tag: Equation \(\eqref{middleAlignMathNumber}\).

Automatic non-breaking spaces

Any cross-references (such as Equation \(\ref{middleAlignMathNumber}\)) will automatically be prepended with non-breaking spaces.

Unless, they appear in a list like equations \(\ref{matheqn1}\), \(\ref{matheqn2}\), \(\ref{matheqn3}\), and \(\ref{middleAlignMathNumber}\).

ScholarlyMarkdown Figures

Images with attributes

The following will be a bunch of figures with attributes: Which should all show fine and display a picture with a baby seal.

Below is more text so that the css doesn’t end abruptly! Now we’ll have an explicit Scholarly Figure environment!

ScholarlyMarkdown figure/multifigures

ScholarlyMarkdown Algorithms

Here are some algorithms using various methods. The “most canonical one” is currently just using a line-block:

The should not be a caption

ScholarlyMarkdown Tables

Standard Pandoc tables

The following is a normal Pandoc table

This should not be a caption

Scholarly tables

The following is a floated ScholMD table

ScholarlyMarkdown Code blocks

Standard Pandoc code blocks

fenced blocks

Value   <- [0-9.]+ / '(' Expr ')'
Product <- Expr (('*' / '/') Expr)*
Sum     <- Expr (('+' / '-') Expr)*
Expr    <- Product / Sum / Value

indented blocks

Value   <- [0-9.]+ / '(' Expr ')'
Product <- Expr (('*' / '/') Expr)*
Sum     <- Expr (('+' / '-') Expr)*
Expr    <- Product / Sum / Value

Scholarly code block floats

100
101
102
103

Value   <- [0-9.]+ / '(' Expr ')'
Product <- Expr (('*' / '/') Expr)*
Sum     <- Expr (('+' / '-') Expr)*
Expr    <- Product / Sum / Value

Value   <- [0-9.]+ / '(' Expr ')'
Product <- Expr (('*' / '/') Expr)*
Sum     <- Expr (('+' / '-') Expr)*
Expr    <- Product / Sum / Value