Introduction

Markdown is a lightweight markup language widely used for formatting plain text documents. It provides a simple and human-readable way to structure text and add basic styling, such as headers, lists, links, and emphasis. Markdown's benefits include ease of use, and compatibility with various web and documentation platforms.

CommonMark is a formal specification that defines a consistent, unambiguous syntax for Markdown, addressing the inconsistencies found in the original Markdown implementation. It serves as a standardization effort to ensure that Markdown content is processed uniformly across different platforms and tools.

In addition to supporting CommonMark, Stencila supports several 'flavors' of Markdown each with extensions to support document elements that are not part of the Commonmark specification:

Usage

To convert to/from CommonMark, use the .md file extension, or the --to md or --from md options e.g.

stencila convert doc.smd doc.md

Implementation

Stencila supports bi-directional conversion between Stencila documents and CommonMark. Parsing of CommonMark is powered by the markdown Rust crate. Extensions to CommonMark are either supported by the markdown crate, or by our own parsing functions, mostly written using the winnow Rust crate.

Support

Stencila supports these operations for Markdown:

decoding from a file
decoding from a string
encoding to a file
encoding to a string

Support and degree of loss by node type:

Node type	Encoding	Decoding	Notes
Works
Article	🔷 Low loss	🔷 Low loss	Encoded using implemented function
AudioObject	🔷 Low loss	🔷 Low loss	Encoded using implemented function
AuthorRole	⚠️ High loss
Chat	⚠️ High loss		Encoded using implemented function
ChatMessage	⚠️ High loss		Encoded using implemented function
ChatMessageGroup	⚠️ High loss		Encoded using implemented function
Claim	⚠️ High loss		Encoded using implemented function
Collection	⚠️ High loss
Comment	⚠️ High loss
CreativeWork	⚠️ High loss
Directory	⚠️ High loss
Figure	⚠️ High loss		Encoded using implemented function
File	⚠️ High loss
ImageObject	🔷 Low loss	🔷 Low loss	Encoded using implemented function
MediaObject	🔷 Low loss	🔷 Low loss
Periodical	⚠️ High loss
Prompt	⚠️ High loss		Encoded using implemented function
PublicationIssue	⚠️ High loss
PublicationVolume	⚠️ High loss
Review	⚠️ High loss
SoftwareApplication	⚠️ High loss
SoftwareSourceCode	⚠️ High loss
Table	🔷 Low loss	🔷 Low loss	Encoded using implemented function
TableCell	🔷 Low loss	🔷 Low loss
TableRow	🔷 Low loss	🔷 Low loss
VideoObject	⚠️ High loss		Encoded using implemented function
Prose
Admonition	🟢 No loss	🟢 No loss	Encoded using implemented function
Annotation	⚠️ High loss		Encoded as `=={{content}}==`
Cite	⚠️ High loss		Encoded using implemented function
CiteGroup	⚠️ High loss
DefinedTerm	⚠️ High loss
Emphasis	🟢 No loss	🟢 No loss	Encoded as `_{{ content }}_`
Heading	🟢 No loss	🟢 No loss	Encoded using implemented function
Link	🔷 Low loss	🔷 Low loss	Encoded using implemented function
List	🔷 Low loss	🔷 Low loss	Encoded using implemented function
ListItem	🔷 Low loss	🔷 Low loss	Encoded using implemented function
Note	🔷 Low loss	🔷 Low loss	Encoded using implemented function
Paragraph	🟢 No loss	🟢 No loss	Encoded as `}\n\n`{{content exec}
QuoteBlock	🟢 No loss	🟢 No loss	Encoded using implemented function
QuoteInline	⚠️ High loss		Encoded as `<q>{{content}}</q>`
Section	🟢 No loss	🟢 No loss	Encoded using implemented function
Strikeout	⚠️ High loss		Encoded as `~~{{content}}~~`
Strong	🟢 No loss	🟢 No loss	Encoded as `{{ content }}`
Subscript	🟢 No loss	🟢 No loss	Encoded as `~{{content}}~`
Superscript	🟢 No loss	🟢 No loss	Encoded as `^{{content}}^`
Text	🟢 No loss	🟢 No loss	Encoded using implemented function
ThematicBreak	🟢 No loss	🟢 No loss	Encoded as `***\n\n`
Underline	🟢 No loss	🟢 No loss	Encoded as `<u>{{content}}</u>`
Math
MathBlock	🟢 No loss	🟢 No loss	Encoded using implemented function
MathInline	🟢 No loss	🟢 No loss	Encoded using implemented function
Code
CodeBlock	🟢 No loss	🟢 No loss	Encoded using implemented function
CodeChunk	🔷 Low loss	🔷 Low loss	Encoded using implemented function
CodeExpression	🔷 Low loss	🔷 Low loss	Encoded using implemented function
CodeInline	🟢 No loss	🟢 No loss	Encoded using implemented function
CompilationMessage	⚠️ High loss
ExecutionMessage	⚠️ High loss
Data
Array	⚠️ High loss
ArrayHint	⚠️ High loss
ArrayValidator	⚠️ High loss		Encoded using implemented function
Boolean	🔷 Low loss	🔷 Low loss
BooleanValidator	⚠️ High loss		Encoded using implemented function
ConstantValidator	⚠️ High loss		Encoded using implemented function
Cord	🟢 No loss	🟢 No loss
Datatable	⚠️ High loss		Encoded using implemented function
DatatableColumn	⚠️ High loss
DatatableColumnHint	⚠️ High loss
DatatableHint	⚠️ High loss
Date	⚠️ High loss
DateTime	⚠️ High loss
DateTimeValidator	⚠️ High loss		Encoded using implemented function
DateValidator	⚠️ High loss		Encoded using implemented function
Duration	⚠️ High loss
DurationValidator	⚠️ High loss		Encoded using implemented function
EnumValidator	⚠️ High loss		Encoded using implemented function
Integer	🔷 Low loss	🔷 Low loss
IntegerValidator	⚠️ High loss		Encoded using implemented function
Null	🔷 Low loss	🔷 Low loss
Number	🔷 Low loss	🔷 Low loss
NumberValidator	⚠️ High loss		Encoded using implemented function
Object	⚠️ High loss
ObjectHint	⚠️ High loss
String	🟢 No loss	🟢 No loss
StringHint	⚠️ High loss
StringValidator	⚠️ High loss		Encoded using implemented function
Time	⚠️ High loss
TimeValidator	⚠️ High loss		Encoded using implemented function
Timestamp	⚠️ High loss
TimestampValidator	⚠️ High loss		Encoded using implemented function
TupleValidator	⚠️ High loss		Encoded using implemented function
Unknown	⚠️ High loss
UnsignedInteger	🔷 Low loss	🔷 Low loss
Flow
Button	⚠️ High loss
CallArgument	⚠️ High loss		Encoded using implemented function
CallBlock	⚠️ High loss		Encoded using implemented function
CodeLocation	⚠️ High loss
CompilationDigest	⚠️ High loss
ExecutionDependant	⚠️ High loss
ExecutionDependency	⚠️ High loss
ExecutionTag	⚠️ High loss
ForBlock	⚠️ High loss		Encoded using implemented function
Form	⚠️ High loss
Function	⚠️ High loss
IfBlock	⚠️ High loss		Encoded using implemented function
IfBlockClause	⚠️ High loss		Encoded using implemented function
IncludeBlock	⚠️ High loss		Encoded using implemented function
Parameter	🔷 Low loss	🔷 Low loss	Encoded using implemented function
Variable	⚠️ High loss
Walkthrough	⚠️ High loss		Encoded using implemented function
WalkthroughStep	⚠️ High loss		Encoded using implemented function
Style
StyledBlock	🟢 No loss	🟢 No loss	Encoded using implemented function
StyledInline	⚠️ High loss		Encoded using implemented function
Edits
InstructionBlock	⚠️ High loss		Encoded using implemented function
InstructionInline	⚠️ High loss		Encoded using implemented function
InstructionMessage	⚠️ High loss		Encoded using implemented function
PromptBlock	⚠️ High loss		Encoded using implemented function
SuggestionBlock	⚠️ High loss		Encoded using implemented function
SuggestionInline	⚠️ High loss		Encoded using implemented function
Config
Config	⚠️ High loss
Other
Brand	⚠️ High loss
ContactPoint	⚠️ High loss
Enumeration	⚠️ High loss
Grant	⚠️ High loss
ModelParameters	⚠️ High loss		Encoded using implemented function
MonetaryGrant	⚠️ High loss
Organization	⚠️ High loss
Person	⚠️ High loss
PostalAddress	⚠️ High loss
Product	⚠️ High loss
PropertyValue	⚠️ High loss
ProvenanceCount	⚠️ High loss
RawBlock	⚠️ High loss		Encoded using implemented function
Thing	⚠️ High loss

See the Rust crate codec-markdown for more details.