The next chapter for Markdown
By Z (zdne, z@apiary.io) on 28 Sep 2016
Apiary is moving to CommonMark on October 17th, 2016
Apiary has always stood for Markdown. We love the format for its simplicity and accessibility: we built the incredibly popular API description language, API Blueprint, on top of it. Markdown is in everything we do: from describing an API, doing a code review, or writing this article, Markdown is our DNA.
As the original idea of Markdown evolved over the years, we were happy to embrace the GitHub-flavored Markdown syntax to simplify the writing of an API description even more.
Embracing CommonMark
Today is a milestone in Apiary’s Markdown history: we are completely moving to CommonMark. As of today, CommonMark will be the standard format to be used in API descriptions throughout Apiary. This includes both API description formats we support: API Blueprint and Swagger 2.0.
Embracing CommonMark will help us to continue delivering the best tools for designing, documenting, prototyping, and testing an API. But more importantly, it gives you full control over your documentation through the power of a robust and well-defined Markdown-based format. It will eliminate the the syntax ambiguity that the original Markdown was susceptible to: you will be always in control of formatting your description to produce the desired results. If you haven’t checked out CommonMark already, head over to the CommonMark tutorial to learn more.
New Standard: Strict Syntax
CommonMark strictly defines the Markdown syntax. This is especially important in the areas that were left ambiguous in the original Markdown syntax, such as linking or list rendering.
CommonMark is largely compatible with the original Markdown, but there are subtle details that can product different outputs that may confuse our users.
As the host of more than a quarter million API Documentation Projects, we cannot take this change lightly. While CommonMark is largely compatible with the original Markdown, there are subtle details that can produce different outputs that may confuse our users.
Fortunately, we’ve been able to identify all API Documentation Projects that are affected by this change. Unless you’ve received an email from us, there are no transition steps necessary for you. If your documentation is affected, you will receive an email from us detailing easy tools we’ve built to help you upgrade your existing Markdown to CommonMark.
Action Needed on Your Part by October 17th, 2016
If there are rendering differences in any of your API Documentation Projects, you will have received an email with links to them. Clicking the links will show you differences introduced by the CommonMark renderer.
For each API Documentation Project, you’ll need to edit the Markdown text to fix these differences. See the CommonMark article on our help portal for examples of such differences.
Once you have fixed all differences, Apiary will prompt you to permananently switch over to the new renderer. At this point, no further action is needed on your part for this API Documentation Project.
On October 17th, 2016, we will switch all API Projects over to the new CommonMark renderer, so we urge you to correct differences before that date.
If you want to learn more about the differences between Markdown and CommonMark head over to the CommonMark article on our help portal.
If you have any questions, concerns or feedback regarding this change, please do not hesitate to contact our support. We will be happy to assist you in building your APIs!