Converts ScholarlyMarkdown documents to HTML5/LaTeX/Docx format

Latest on Hackage:0.1.3

This package is not currently in any snapshots. If you're interested in using it, we recommend adding it to Stackage Nightly. Doing so will make builds more reliable, and allow to host generated Haddocks.

GPL licensed and maintained by Tim T.Y. Lin


Converts ScholarlyMarkdown documents into HTML5, LaTeX, or Docx

Current stable version: 0.1.3

Development build status build status
Stable build status build status

Scholdoc is a command-line utility that converts ScholarlyMarkdown documents into the HTML5, LaTeX, and Docx (OOML) formats. It is intended to facilitate academic writing in a cross-platform, semantic-aware, plaintext format that can be quickly used in modern publishing pipelines.

Scholdoc is implemented as fork of Pandoc, and mostly retains the same user interface (including the custom template and filter system). It essentially understands a new input format markdown_scholarly (implemented in the markdown reader a superset of markdown_pandoc features), and limits itself to HTML5/LaTeX/Docx output. Scholdoc defaults to standalone output and has its own custom templates to ensure output compatibility with ScholarlyMarkdown.

See the Pandoc Guide for more about Pandoc, its usage, and the Markdown dialect that Pandoc (and hence Scholdoc) understands.

Scholdoc is currently up to date with Pandoc version 1.13.1 (commit 8b60d430)

HTML output

Important: A ScholarlyMarkdown core CSS is required for proper formatting of most HTML files output by Scholdoc.

Scholdoc’s HTML output is strictly limited to HTML5 due to its enhanced semantic capabilities (such as the figure and figcaption element), and relies on some CSS3 features for layout (mostly for multi-image figures with subcaptions). It adheres to a fairly straightforward schema. No formatting information is written to the HTML by Scholdoc, so a ScholarlyMarkdown core CSS is required for bare minimum proper formatting. You can also write your own CSS that target the schema.

By default, the html output format generates a complete (but bare-bones) HTML5 document that can be used immediately. To have Scholdoc generate just the bare content (everything inside scholmd-content), use the html_bodyonly output format. By default, Scholdoc will always include proper MathJax settings for the way ScholarlyMarkdown prescribes math content in HTML.

Docx output

The Docx writer currently isn’t fully functional yet. It does not yet output structures specific to ScholarlyMarkdown (such as figures).


Scholdoc changelog

All notable changes to Scholdoc will be documented in this file.

This log pertains to Scholdoc development only. Pandoc’s changelog can be found in the changelog-pandoc file.

Scholdoc’s version numbers reflect Scholdoc changes only, and does not necessarily correspond to Pandoc’s version number. Scholdoc strives to track the latest official Pandoc release. Whenever new Pandoc commits are merged into Scholdoc, it will be noted in the changelog below.

Scholdoc follows semantic versioning with regards to its output schema.

0.1.3-alpha - 2014-10-15

Note: This version largely consists of major cleanups under the hood. It bring the development of Scholdoc up-to-date with the latest Pandoc development version, and removed many unnecessary source files related to unused reader/writers.


  • The Pandoc-derived portion of Scholdoc is now up to date with Pandoc 1.13.1 (commit 8b60d430)
  • The build-chain of Scholdoc have been cleaned-up and is now ready for production. Running make deps && make install under the source directory now fully builds using its own scholdoc-types and scholdoc-texmath packages.
  • Updated documentation to reflect the Scholdoc project:,, BUGS, COPYRIGHT


  • Scholdoc now looks for custom template files under the ~/.scholdoc/ directory, instead of ~/.pandoc
  • The “–no-standalone” option no longer imply “_bodyOnly” writers. Instead “–no-standalone” now strictly stops all template usage.

0.1.2-alpha - 2014-09-09


  • Allow rudimentary Docx output, although most Scholmd elements map to empty


  • The program name is changed from scholpandoc to scholdoc to more accurately reflect the limited input/output options compared to Pandoc.

HTML output

  • Uses HTTPS instead of protocol-relative URLs for default polyfills in the template from CDNJS. This will make previewing local HTML files much easier.
    • Default MathJax CDN URL is also changed to the HTTPS protocol
  • Added an additional variable html-header-includes for inclusion of HTML-specific header tags. This can be specified in YAML metadata blocks, and will be treated as an unformatted string.

LaTeX output

  • Added indentparagraphs variable to template, so you can change between “no indent/line-height paragraph margins” and “indent/no paragraph margins”
  • Added variables natbib-options and biblatex-options to specify loading options for these citation packages
  • Added additional variables to the template for more flexibility in “injection” of custom LaTeX code without resorting to a separate template:
    • latex-before-documentclass-includes
    • latex-before-packages-includes
    • latex-after-packages-includes
    • latex-header-includes
    • latex-after-body-includes
    • latex-after-document-includes
  • All the above variable can be specified in YAML metadata blocks, and will be treated as unformatted strings (along with geometry)

0.1.1-alpha - 2014-05-30


  • Allow output of JSON-style native format


LaTeX output

  • No longer hard-codes the htbp placement of floats. This is now controlled in the template using the Float package.


  • Fixed a bug where figures/floats display captions prefixes when it is not needed

0.1.0-alpha - 2014-04-22


HTML output

  • Conforms to ScholarlyMarkdown HTML5 Schema 0.1


  • The bibliography metadata is now treated like a pure string and will not be formatted
  • Display math and figure/floats now properly parses if delimiters have multiple trailing whitespaces
  • Disabling standalone mode using _bodyonly suffix now works again
  • Minor code cleanup using hlint, refactored various writer monads for floats

0.0.1-alpha - 2014-03-16


  • Display math equations that uses the class math_def instead of math are now appended to a global variable called $math-macros$. In the updated templates this is placed in the header, and enables LaTeX declarations that only work in the header


  • ScholarlyPandoc now has the following arguments enabled by default: -f markdown_scholarly --smart --parse-raw --standalone. Renaming the executable to anything other than scholpandoc reverts this behavior


  • Fixed a bug where templates files are not compiled into the binary, resulting in complaints about “can’t find file …”

0.0.0-alpha - 2014-03-14

Initial Release

comments powered byDisqus