Introduction

MyST Markdown is an extended flavor of Markdown that supports additional syntax features like directives and roles, familiar to users of reStructuredText. It’s designed to enhance the expressiveness of standard Markdown for technical documentation while retaining Markdown’s simplicity and readability

Usage

To convert to/from MyST Markdown, use the .myst file extension, or the --to myst or --from myst options e.g.

stencila convert doc.smd doc.myst

Implementation

Stencila support bi-directional conversion between Stencila documents and MyST Markdown. See our CommonMark documentation for implementation details.

Support

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

See the Rust crate codec-markdown for more details.