commonmark-markdown

Goals of this repo

Just some test what commonmark markdown can do for me. TLDR; not much. Mermaid is not supported by GFM

Background

The problem with Markdown (*.md-files) is the lack of standardization on the most ambiguous details of the language. There are different implementations that do have some documentation (Github-Flavored-Markdown, Sundown, CommonMark, ...)

I'm also working with CommonMark on Gitlab Community edition that is easily installed using this docker image:

docker pull gitlab/gitlab-ce

Today I decided to play around with CommonMark at Github, specifically for technical documentation. Commonmark supports mermaid inline diagramming so this will help me a lot in writing efficient technical documentation in e.g. README.md files.

Here are some articles where I draw my information from:

Examples

A limited list of examples is already written here that include:

Headers
Emphasis: bold, strikethrough, italic
Lists
Images
Links
Blockquotes
Inline code
Syntax highlighting
Hyperlinks
Task lists
Tables
SHA references
links with issues on github
username @mentions
emoji

But what about...

Code hightling in depth
Hyperlink tricks
Table of contents
Warnings
Diagrams
Possibilities of tables
List of Emojis
raw HTML

Extended Examples

Diagrams

Diagrams in Github Readme discussion

Diagrams using Mermaid

graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
  click B "http://gius.nl" "This is a link"

Mermaid doesn't work. @see closed feature request issue#533

Diagrams using yUML

// {type:class}
// {direction:topDown}
// {generate:true}

[note: You can stick notes on diagrams too!{bg:cornsilk}]
[Customer]<>1-orders 0..*>[Order]
[Order]++*-*>[LineItem]
[Order]-1>[DeliveryMethod]
[Order]*-*>[Product|EAN_Code|promo_price()]
[Category]<->[Product]
[DeliveryMethod]^[National]
[DeliveryMethod]^[International]

Diagrams using PlantUML

Diagrams using Google

Abusing the image tag:

![](https://chart.googleapis.com/chart?cht=gv&chl=graph{C_0--H_0[type=s];C_0--H_1[type=s];C_0--H_2[type=s];C_0--C_1[type=s];C_1--H_3[type=s];C_1--H_4[type=s];C_1--H_5[type=s]})

Will generate:

Other mentions

item	description
stackedit.io	online markdown editor that supports scores, formula's, mermaid and more
bramp.github.io	online sequence diagrams to svg
http://flowchart.js.org/	online flowchart > you should use activity diagrams
yUML suntax in VSC	yUML for VSC, not supported by gitlab nor github

rkristelijn/commonmark-markdown