Github markdown diagram 지원 소식

github blog에 신박한 소식이 있어서 소개한다.

https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

Include diagrams in your Markdown files with Mermaid | The GitHub Blog

 

Github의 Markdown 문법 사용

github은 markdown 문법의 파일인 경우(확장자가 .md 같은) 해당 파일을 클릭하면 미리보기를 지원한다.

가장 대표적인 예가 README.md인데 repository 최상위 또는 '.github' 디렉터리에 해당 파일을 만들어 markdown 문법으로 작성하면 해당 repository 접근 시 markdown 문서를 rendering 하여 repository 첫 화면에 보여준다.

https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes

About READMEs - GitHub Docs

 

예를 들면 아래 링크의 repository에서 README.md가 해석되어 화면에 보이게 된다.

https://github.com/luversof/bluesky-boot-autoconfigure-devcheck

GitHub Flavored Markdown Spec

github에서는 markdown 문법을 기반으로 github이 좀 더 다듬은 GitHub Flavored Markdown 문법을 사용하면 된다.

https://github.github.com/gfm/

GitHub Flavored Markdown Spec

이렇게 따로 markdown spec을 정한 이유는 기본적인 markdown 문법(CommonMark Spec)이 너무 간단하다 보니 지원되지 않는 것이 있기 때문이다.

예를 들면 테이블 지원, Task list item 목록, 취소선, 자동 링크, raw html 비허용과 같은 확장된 기능을 GitHub Flavored Markdown 문법이 지원한다.

Github의 Markdown 문법 Diagram 지원

이러한 지원에 이번에 새로 추가된 것이 바로 diagram 지원이다.

diagram을 지원하기 위해 githug은 Mermaid를 사용하였다.

https://mermaid-js.github.io/mermaid/#/

mermaid - Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams, gantt charts and git graphs.

Mermaid는 markdown과 비슷한 mermaid의 문법을 사용하면 diagram으로 rendering 하도록 도와주는 javascript library이다.

문서에 다음과 같이 사용하면

```mermaid
  graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;
```

이렇게 diagram으로 변환되어 화면에 표시된다.

mermaid가 작성된 text를 기반으로 flowchart, Sequence diagram, class diagram, state diagram, entity relationship diagram, gantt, pie chart 등 다양한 diagram을 만들어주기 때문에 앞으로 github의 md 문서가 풍요로워질 듯하다.