-
Notifications
You must be signed in to change notification settings - Fork 77
Wish list
Specification for Markdown appropriate for scholarly content. This document is work in progress.
Optional metadata about a document. Typically used for title, authors (including affiliation), and publication date, but should be flexible enough to handle any kind of metadata (keywords, copyright, etc.).
Scholarly markdown should support superscript and subscript text, and provide an easy way to enter greek letters.
Tables should work as anchors (i.e. you can link to them) and table captions should support styled text. Unless the table is very simple, tables are probably better written as CSV files with another tool, and then imported into the scholarly markdown document similar to figures.
Figures in scholarly works are separated from the text, and have a figure caption (which can contain styled text). Figures should work as anchors (i.e. you can link to them). Figures can be in different file formats, including TIFF and PDF, and those formats have to be converted into web-friendly formats when exporting to HTML (e.g. PNG and SVG).
Scholarly articles typically don't have inline links, but rather citations. The external links (both scholarly identifiers such as DOIs and regular web URLs) are collected in a bibliography at the end of the document, and the citations in the text link to this bibliography. This functionality is similar to footnotes.
Citations should include a citation key in the text (e.g. [@Smith2006] or [#Smith2006]) and a separate bibliography file in BibTeX (or RIS) format that contains references for all citations. Inserting citations and creating the bibliography can best be done with a reference manager.
Cross-links – i.e. links within a document – are important for scholarly texts. It should be possible to link to section headers (e.g. the beginning of the discussion section), figures and tables, plus equations, theorems, etc..
Mathematical formulas are out of scope of the markdown syntax. However, there are a number of excellent tools available that make it possible to add support for mathematical formulas to markdown documents. Scholarly markdown should establish best practices and recommend tools for handling math formulas - both inline and as block elements.
Comments are important for multi-author documents and if reviewer feedback should be included. Comments should be linked to a particular part of a document to provide context, or attached at the end of a document for general comments. It would also be helpful to "comment out" parts of a document, e.g. to indicate parts that are incomplete and need more work. Revisions of a markdown document are best handled using a version control system such as git.