Abstract: This paper records the platform syntax and display differences I encountered in the process of using Markdown, analyzes the differences in support of Markdown by common writing platforms and suggestions for avoiding pitfalls. In this paper, I have my thoughts on the choice between technical freedom and standards.

Markdown’s grammatical features allow people to focus only on the content of the text in the process of writing, and do not need to pay special attention to typesetting, so as not to let the train of thought be interrupted. When publishing, it is necessary to consider the style that readers see, whether it is beautiful.

Markdown features

Introduction of Markdown

Markdown is a lightweight markup language that allows people to write documents in plain text format that is easy to read and write, and then convert them into richly formatted HTML pages. — Wikipedia

Common grammar

The following is a picture that has been widely circulated on the Internet. The basic syntax includes:

Why it’s popular

1. Plain text, easy to edit, cross-platform support
2. The grammar is simple, easy to learn and easy to read
3. Smooth writing does not interfere with focus
4. Easy to convert to Html and PDF, suitable for website writing, become a web writing language
5. Support Html features, you can customize complex styles
6. The popularity of Github, the largest open source site, and StackOverflow, the largest q&A community, is led by techies
7. Mobile devices are popular, and small-size reading experience is optimized

The design philosophy

Markdown is intended to be as easy to read and easy to write as feasible. — By JOHN GRUBER

Easy to read, easy to write, simple idea. Focus on writing, simple avenue.

Tool support

Markdown is a lightweight “markup language” for writing, fulfilling the dream of writing everywhere in one place. There are many tools and products that support Markdown syntax. Here are some common tools and products that support Markdown syntax.

• Support site
  • GitHub
  • StackOverflow
  • CSDN
  • OpenStreetMap
  • Blog garden
  • Jane’s book
  • zhihu
  • The Denver nuggets
• Note taking tool
  • Impression of notes
  • Youdao Cloud Note
  • For know notes
• The editor
  • The Windows platform
    • Typora
    • MarkdownPad
    • MarkPad
    • VS Code
  • Linux platform
    • ReText
    • Haroopad
    • VS Code
  • Mac
    • Bear
    • Mou
    • MacDown
• Online editor
  • stackedit.io
  • Markable.in
  • Dillinger.io
  • maxiang.io
  • mermaid
• Browser plug-in
  • Markdown Here

Visual Studio Code is recommended. As an extension of the most powerful editor in the universe, you deserve it. What, can’t configure, too complicated, want to use everywhere, subway code word? Youdao Cloud notes go.

Version evolution

Now Markdown is developing rapidly, but its disadvantages are also obvious. I believe that people who have used it for a period of time have experienced it, and the slot is full of points.

There is no standard

Gruber has argued that complete standardization would be mistaken: “Different sites (and people) have Different needs. No one syntax would make all happy.”

I don’t agree with the founders’ response to this question. Extensibility and standards are not in conflict, and freedom is within a certain framework. As a result, Markdown’s syntax has been extended more rigorously by language versions since the first Perl release, resulting in a plethora of tools.

Editor and syntax

By choosing a handy editor, you are choosing a Markdown syntax implementation. Therefore, special needs such as flowcharts, generated directories, complex table support, extensive mathematical formula presentation, especially need to know the editor support and the presentation of published site support.

Evolution of version

Please refer to another article I wrote (link) for the main version of the mind map below:

standardized

In March 2016, RFC 7763 proposed adding a MIME type text/markdown, while RFC 7764 discussed standardizating several common types of markdown: MultiMarkdown, GitHub Chinglish Markdown (GFM), Pandoc, CommonMark, and Markdown Extra. This is a welcome development.

Embrace change

The idea behind open source is to allow users to add extensions to provide desired features. But without a standard, just a concept, without embracing change, there is only elimination. No technology is perfect from the start. It’s all about iteration and service to developers. This is another Angle to see why so many different grammarsfollowed CommonMark, including the well-known GitHub converged Markdown (GFM).

The pit of tread

Open source this has no way, walk more people, also became a way, step on the pit more you will give up. — True portrayal of open source projects.

Platform Help Documentation

Must be in the first place, there is no detailed help documentation tools, please give up, otherwise how to climb out of the pit. Toolbar + preview are basically standard, this is nothing to say, want to see the syntax one by one click to support the basic syntax supported by the editor, familiar with this can abandon this inefficient way, free the mouse hand.

The CSDN editor is the best in this respect in China. Come in is an example for the text, double column support preview, there is a clear question mark help icon in the upper right corner, click after the sub-theme help small examples.

The second is Youdao Cloud notes, the interface double-column preview, the question mark in the upper right corner after clicking to jump to the pipe network help document, the first and high order two, enough to get started. Unfortunately, the link to reference study in this article has been invalid and has not been updated in time.

I have tried it, and found that the formula is also supported. The footnote is not supported. Basically, it is similar to Pandoc, but not Markdown Extra.

The worst is Jane book and blog park. Get a feel for the blogosphere: You can customize rich CSS and templates, but the background is ugly.

Until now, Jane has not found any obvious help or specific implementation dependence. By pasting several examples, it should be CommonMark and Github chinglish Markdown.

Syntax differences

The syntax difference really depends on which implementation of Markdown is supported and the corresponding configuration choices. The good news is that the CommonMark format supports all basic markup, just plain text and images that are almost universally usable.

There is a dedicated open source project Babelmark 3 that categorises the results of different Markdown implementations, currently collecting 33 versions

Most editing tools now allow you to choose how to implement it, whether to turn on styles or not. On the web, there are fixed rules to follow.

The list has a blank line effect problem

This is a common problem with Markdown, and the behavior is not strictly defined when defining lists. See CommonMark Spec V0.28 for details. What happens when Markdown accidentally adds blank lines? Resulting in different styles of transformed Html. Different parser implementations differ on whether to use paragraphs to add

or

to the transformation list. There is no right or wrong, just what you need, so it is necessary to say that the final release needs to be carefully read and adjusted, and you can find the problem at a glance after a trip to the pit.

Image insert tag attribute display problem

For the following Markdown code:

! [tag picture] (https://ws1.sinaimg.cn/large/66cf5bc0ly1fve6pmxkfrj20u605uwet.jpg)Copy the code

There are different interpretations of text tags inside tags, and there is a disagreement over whether attributes are also displayed when converted to Html. Common implementations are Only Multimarkdown 5.1.0 and PanDoc 2.3.

The effect of the simple book is the display, so it is possible that it is a variation of these two implementations.

The effect of supported extensions is inconsistent

The most typical examples are tables and flow charts. Most implementations support tabular functionality, and Babelmark 3 allows you to see six different types of converted Html, which is even worse if you use bold in the table, and 12 different effects that you would never expect to see on a different site.

According to the effect

This is also a sinkhole, hard to write, the final need to face the reader. The cause is nothing more than the implementation of the extension function is inconsistent and the site CSS style differences affect the layout.

Inconsistent extension functionality implemented

This is where you have to focus on effectiveness. It’s best to have a preview function, like CSDN, simple book, otherwise you have to publish it again and again and then view and modify it, like blog garden. Therefore, the compatibility of the tool you choose and the platform you distribute comes into question, preferably with a variant implementation of the same core source code.

CSS style differences affect

The table function is most prominent. First look at the effect comparison:

Therefore, it is recommended not to use tables to extend the syntax, or to use custom CSS after converting to images.

My best practices

The goal is to write a book, publish it everywhere. The following are based on personal favorite, just for reference. Windows platform uses Youdao Cloud notes to synchronize materials and unfinished articles.

1. Use Visual Studio Code for writing

2. Plugin to install Markdown All in One

   According to the need to configure the version and function support, rich shortcut keys, is absolutely efficient artifact. You are advised to enable the preview function to view the effect.

3. Syntax checking Install MarkDownLint, real-time syntax checking is a must for ides
4. Tubed uses Sina Weibo or Qiniuyun

5. Use Pangu-Markdown to check Chinese typesetting

   Check whether the effect of mixing Chinese and English is consistent with general practice.

6. Publish using Markdown Here after conversion to see if the effect meets the intent and then carefully check and paste

1. The blog is the output of my learning process. I hope you find it rewarding.
2. Have idea please leave a message, discuss study together.
3. Due to the limited capacity of the blogger, the description may be incorrect, welcome correction, supplement!
4. You can also follow my official account:ProgramLife042, the name:The wind of programming lifeTo receive the latest content.