We’re releasing a formal specification of the syntax for GitHub Flavored Markdown, and its corresponding reference implementation.
Overview
The article discusses the formal specification of GitHub Flavored Markdown (GFM) and its implementation based on the CommonMark specification. It highlights the challenges faced in transitioning from the previous parser, Sundown, to the new cmark implementation while ensuring compatibility and performance.
What You'll Learn
1
How to implement GitHub Flavored Markdown (GFM) in your applications
2
Why using CommonMark improves Markdown rendering consistency across platforms
3
When to apply normalization techniques to existing Markdown content
Prerequisites & Requirements
- Understanding of Markdown syntax and its variations
- Familiarity with GitHub and its content management(optional)
Key Questions Answered
What are the main features of GitHub Flavored Markdown (GFM)?
GitHub Flavored Markdown (GFM) includes features such as tables, strikethrough, autolinks, and task lists, which are not part of the CommonMark specification. These extensions are designed to enhance user experience on GitHub by providing additional formatting options.
How does the transition from Sundown to cmark affect existing Markdown content?
The transition to cmark is expected to affect less than 1% of existing user content, as determined by rendering a large set of documents with both parsers and comparing the outputs. This analysis ensures that most content will render identically, maintaining user experience.
What security measures are in place for the new Markdown parser?
The cmark implementation has been designed to be resistant to common security vulnerabilities, such as stack overflows and arbitrary code execution, by utilizing safe parsing algorithms and an Abstract Syntax Tree (AST) approach to handle document formatting securely.
How does the performance of cmark compare to Sundown?
While cmark has received optimizations, it is still 20% to 30% slower than Sundown in most cases. This is attributed to cmark's additional functionalities, which, despite being slower, provide a more robust parsing experience.
Key Statistics & Figures
Percentage of existing user content affected by new implementation
less than 1%
This statistic was determined through synthetic analysis of GitHub's Markdown corpus, ensuring minimal disruption during the transition.
Performance difference between cmark and Sundown
20% to 30% slower
This performance metric highlights the trade-off between additional functionalities in cmark and the speed of the previous Sundown parser.
Technologies & Tools
Backend
Cmark
cmark is the reference implementation for CommonMark used for parsing Markdown in GitHub.
Backend
Sundown
Sundown was the previous Markdown parser used at GitHub before transitioning to cmark.
Key Actionable Insights
1Implement GitHub Flavored Markdown (GFM) in your projects to enhance content formatting capabilities.GFM provides additional features that can significantly improve user engagement and document readability, especially in collaborative environments like GitHub.
2Utilize the normalization process to ensure existing Markdown content remains visually consistent during transitions.By normalizing user comments before transitioning to the new parser, you can prevent unexpected rendering issues and maintain a seamless user experience.
3Adopt the CommonMark specification for Markdown parsing to ensure compatibility across different platforms.CommonMark offers a standardized approach to Markdown, reducing discrepancies in document rendering across various Markdown parsers.
Common Pitfalls
1
Failing to account for corner cases specified by CommonMark can lead to unexpected rendering results.
This can happen if developers assume that all Markdown content will render the same way across different parsers, leading to potential user dissatisfaction.
Related Concepts
Markdown Syntax Variations
Commonmark Specification
Markdown Parsing Techniques