CommonMark: Markdown의 공식 사양

CommonMark는 원래 Markdown 사양을 둘러싼 모호성과 불일치를 제거하는 것을 목표로 하는 사양을 사용하는 합리화된 Markdown 구문 버전입니다. 이 사양에 대해 Markdown 구현을 검증하기 위한 포괄적인 테스트 모음과 함께 언어의 공통 구문을 정의하는 표준화된 사양을 제공합니다.

GitHub는 사용자 콘텐츠의 마크업 언어로 Markdown을 사용합니다.

“CommonMark는 실제 사용을 반영하는 방식으로 인터넷의 많은 웹사이트에서 사용하는 Markdown 구문을 공식적으로 지정하기 위한 야심찬 프로젝트입니다. [...] 사람들이 개발자에게 제공하면서 항상 하던 방식으로 Markdown을 계속 사용할 수 있도록 합니다. 플랫폼 간에 일관된 방식으로 Markdown을 상호 운용하고 표시하기 위한 포괄적인 사양 및 참조 구현입니다."

— "GitHub Flavored Markdown을 위한 공식 사양", GitHub 블로그

2012년에 GitHub는 Markdown 표준화의 부족을 해결하고 필요에 따라 구문을 확장하기 위해 자체적인 Markdown 버전인 GitHub Flavoured Markdown(GFM)을 만들기 시작했습니다. GFM은 당시 기존 Markdown 파서의 일부 단점을 해결하기 위해 GitHub에서 특별히 제작한 파서인 Sundown 위에 구축되었습니다. 5년 후인 2017년에 CommonMark 구문 분석 및 렌더링 라이브러리인 GitHub Flavored Markdown의 공식 사양에서 cmark를 위해 Sundown의 사용 중단을 발표했습니다.

Markdown 및 Visual Studio Code의 일반적인 질문 섹션에는 VSCode의 Markdown이 자체적으로 CommonMark 사양을 따르는 markdown-it 라이브러리를 사용하여 CommonMark Markdown 사양을 대상으로 하는 것으로 문서화되어 있습니다.

CommonMark는 C(예: cmark), C#(예: CommonMark.NET), JavaScript(예: markdown-it) 등과 같은 다양한 언어에서 사용하기 위해 널리 채택되고 구현되었습니다(CommonMark 구현 목록 참조). 이것은 개발자로서 희소식입니다. 그리고 저자는 일관된 구문과 표준화된 사양으로 Markdown을 사용할 수 있는 새로운 영역으로 점차 이동하고 있습니다.

마크다운 파서에 대한 짧은 참고 사항

Markdown 파서는 Markdown 텍스트를 직접 또는 간접적으로 HTML로 변환하는 핵심입니다.

cmark 및 commonmark.js와 같은 파서는 Markdown을 HTML로 직접 변환하지 않고 대신 AST(Abstract Syntax Tree)로 변환한 다음 AST를 HTML로 렌더링하여 프로세스를 더 세분화하고 조작할 수 있습니다. 예를 들어 AST로의 구문 분석과 HTML로의 렌더링 사이에 Markdown 텍스트를 확장할 수 있습니다.

CommonMark의 Markdown 구문 지원

이미 CommonMark 사양을 특정 플레이버의 기준선으로 구현한 프로젝트 또는 플랫폼은 종종 CommonMark Markdown 사양의 엄격한 하위 집합 의 상위 집합 입니다. 대부분의 경우 CommonMark는 구축을 위해 구축된 사양을 구축하여 많은 모호성을 완화했습니다. GFM이 대표적인 예이며 모든 CommonMark 구문을 지원하지만 용도에 맞게 확장하기도 합니다.

CommonMark의 구문 지원은 처음에는 제한될 수 있습니다. 예를 들어 이 테이블 구문을 지원하지 않습니다. 그러나 이 대화 스레드의 이 주석에서 알 수 있듯이 이것이 의도적으로 설계된 것임을 아는 것이 중요합니다. 지원되는 구문 은 엄격 하고 다음과 같습니다. 언어 자체의 핵심 구문이 되는 것 — Markdown: Syntax의 작성자인 John Gruber가 지정한 것과 동일합니다.

작성 당시 지원되는 구문은 다음과 같습니다.

1. 단락 및 줄 바꿈,
2. 헤더,
3. 강조와 강한 강조,
4. 수평 규칙,
5. 기울기,
6. 연결,
7. 이미지,
8. 인용구,
9. 암호,
10. 코드 블록.

예제를 따라 하려면 commonmark.js dingus 편집기를 사용하여 구문을 시도하고 렌더링된 미리 보기, 생성된 HTML 및 AST를 가져오는 것이 좋습니다.

단락 및 줄 바꿈

Markdown에서 단락은 최소한 빈 줄로 구분된 연속적인 텍스트 줄입니다.

다음 규칙은 단락을 정의합니다.

1. 마크다운 단락은 HTML에서 단락 요소인 <p>로 렌더링됩니다.
2. 다른 단락은 단락 사이에 하나 이상의 빈 줄로 구분됩니다.
3. 줄 바꿈의 경우 단락은 두 개의 공백(또는 이에 상응하는 탭) 또는 백슬래시( \ )로 후위 고정되어야 합니다.

• 단락에 대해 배울 수 있는 대화형 자습서.
• Dingus permalink는 Preview 및 AST로 전체 예제를 확인하십시오.
• 단락에 대해 자세히 알아보세요.

제목

Markdown의 머리글은 HTML 머리글 요소 중 하나를 나타냅니다. 제목을 정의하는 방법에는 두 가지가 있습니다.

1. ATX 방향.
2. 텍스트 제목을 설정합니다.

다음 규칙은 ATX 표제를 정의합니다.

1. 제목 수준 1( h1 )에서 제목 수준 6( h6 )까지 지원됩니다.
2. Atx 스타일 머리글에는 해시( # ) 기호가 접두사로 붙습니다.
3. 텍스트와 해시( # ) 기호를 구분하는 최소한의 공백이 있어야 합니다.
4. 해시 수는 제목의 기본 번호와 같습니다. 하나의 해시는 h1 , 두 개의 해시, h2 , 6개의 해시, h6 입니다.
5. 임의의 수의 해시 기호를 제목에 추가하는 것도 가능하지만 이는 아무 효과도 일으키지 않습니다(예: # Heading 1 # ).

다음 규칙은 Setext 표제를 정의합니다.

1. 제목 수준 1(h1)과 제목 수준 2, (h2)만 지원됩니다.
2. Setext 스타일 정의는 각각 등호(=) 및 대시 기호로 수행됩니다.
3. Setext에는 하나 이상의 등호 또는 대시 기호가 필요합니다.

• 제목에 대해 배울 수 있는 대화형 자습서.
• 미리보기 및 AST로 전체 예제를 확인하려면 Dingus 영구 링크를 클릭하세요.
• ATX 표제에 대해 자세히 알아보십시오.
• Setext 제목에 대해 자세히 알아보십시오.

강조 및 강한 강조

Markdown의 강조는 이탤릭체 또는 볼드체(강한 강조)일 수 있습니다.

다음 규칙은 강조를 정의합니다.

1. 일반 및 강한 강조는 HTML에서 각각 Emphasis, <em> 및 Strong, <strong> 요소로 렌더링됩니다.
2. 단일 별표( * ) 또는 밑줄( _ )로 묶인 텍스트는 강조 표시됩니다.
3. 이중 별표 또는 밑줄로 묶인 텍스트는 강한 강조점이 됩니다.
4. 경계 기호(별표 또는 밑줄)는 일치해야 합니다.
5. 기호와 동봉된 텍스트 사이에는 공백이 없어야 합니다.

• 강조에 대해 배울 수 있는 대화형 튜토리얼.
• 미리보기 및 AST로 전체 예제를 확인하려면 Dingus 영구 링크를 클릭하세요.
• 강조 및 강한 강조에 대해 자세히 알아보십시오.

수평선

가로 규칙 <hr/>은 새 줄에 세 개 이상의 별표( * ), 하이픈( - ) 또는 밑줄( _ )로 만들어집니다. 기호는 임의의 수의 공백으로 구분되거나 전혀 구분되지 않습니다.

• 미리보기 및 AST로 전체 예제를 확인하려면 Dingus 영구 링크를 클릭하세요.
• 주제별 휴식 시간에 대해 자세히 알아보세요.

기울기

Markdown의 목록은 글머리 기호(순서 없는) 목록 또는 정렬된 목록입니다.

다음 규칙은 목록을 정의합니다.

1. 글머리 기호 목록은 HTML에서 정렬되지 않은 목록 요소인 <ul>로 렌더링됩니다.
2. 정렬된 목록은 HTML에서 정렬된 목록 요소인 <ol>로 렌더링됩니다.
3. 글머리 기호 목록은 별표, 더하기 및 하이픈을 마커로 사용합니다.
4. 정렬된 목록은 숫자 다음에 마침표 또는 닫는 괄호를 사용합니다.
5. 마커는 일관성이 있어야 합니다(나머지 목록 항목 정의에 대해 시작하는 마커만 사용해야 함).

• 목록에 대해 배우기 위한 대화형 자습서.
• 미리보기 및 AST로 전체 예제를 확인하려면 Dingus 영구 링크를 클릭하세요.
• 목록 항목에 대해 자세히 알아보세요.

연결

링크는 인라인 및 참조 형식으로 지원됩니다.

다음 규칙은 링크를 정의합니다.

1. 링크는 HTML Anchor 요소인 <a>로 렌더링됩니다.
2. 인라인 형식은 대괄호 사이에 공백이 없는 [value](URL "optional-title") 구문을 사용합니다.
3. 참조 형식에는 참조의 경우 [value][id] 구문이 있고 하이퍼링크 레이블의 경우 [id]: href "optional-title" 구문이 있으며 최소한 한 줄로 구분됩니다.
4. id 는 정의 식별자 이며 문자, 숫자, 공백 및 구두점으로 구성될 수 있습니다.
5. 정의 식별자는 대소문자를 구분하지 않습니다.
6. URL이 보다 작음(<) 및 보다 큼(>) 기호로 경계가 지정되고 문자 그대로 표시되는 자동 링크도 지원됩니다.

 <!--Markdown--> [Google](https://google.com “Google”) <!--Rendered HTML--> <a href="https://google.com" title="Google">Google</a> <!--Markdown--> [Google](https://google.com) <!--Rendered HTML--> <a href="https://google.com">Google</a> <!--Markdown--> [Comparing Styling Methods in Next.js](/2020/09/comparing-styling-methods-next-js) <!--Rendered HTML--> <a href="/2020/09/comparing-styling-methods-next-js">Comparing Styling Methods In Next.js</a> <!--Markdown--> [Google][id] <!--At least a line must be in-between--> <!--Rendered HTML--> <a href="https://google.com" title="Google">Google</a> <!--Markdown--> <https://google.com> <!--Rendered HTML--> <a href="https://google.com">google.com</a> <!--Markdown--> <[email protected]> <!--Rendered HTML--> <a href="mailto:[email protected]">[email protected]</a>

• 링크에 대해 배울 수 있는 대화형 자습서.
• 미리보기 및 AST로 전체 예제를 확인하려면 Dingus 영구 링크를 클릭하세요.
• 링크에 대해 자세히 알아보세요.

이미지

Markdown의 이미지는 링크에 대한 인라인 및 참조 형식을 따릅니다.

다음 규칙은 이미지를 정의합니다.

1. 이미지는 HTML 이미지 요소인 <img>로 렌더링됩니다.
2. 인라인 형식의 구문은 ![alt text](image-url "optional-title") 입니다.
3. 참조 형식에는 참조의 경우 ![alt text][id] 구문이 있고 이미지 레이블의 경우 [id]: image-url "optional-title" 구문이 있습니다. 둘 다 최소한 빈 줄로 구분해야 합니다.
4. 이미지 제목은 선택 사항이며 image-url은 상대적일 수 있습니다.

 <!--Markdown--> ![alt text](image-url "optional-title") <!--Rendered HTML--> <img src="image-url" alt="alt text" title="optional-title" /> <!--Markdown--> ![alt text][id] <!--At least a line must be in-between--> <!--Markdown--> <!--Rendered HTML--> <img src="image-url" alt="alt text" title="optional-title" />

• 이미지에 대해 배울 수 있는 대화형 자습서.
• 미리보기 및 AST로 전체 예제를 확인하려면 Dingus 영구 링크를 클릭하세요.
• 이미지에 대해 자세히 알아보세요.

인용구

HTML 블록 인용 요소인 <blockquote>는 새 줄 앞에 보다 큼 기호( > )를 추가하여 생성할 수 있습니다.

 <!--Markdown--> > This is a blockquote element > You can start every new line > with the greater than symbol. > That gives you greater control > over what will be rendered. <!--Rendered HTML--> <blockquote> <p>This is a blockquote element You can start every new line with the greater than symbol. That gives you greater control over what will be rendered.</p> </blockquote>

블록 따옴표는 다음과 같이 중첩될 수 있습니다.

 <!--Markdown--> > Blockquote with a paragraph >> And another paragraph >>> And another <!--Rendered HTML--> <blockquote> <p>Blockquote with a paragraph</p> <blockquote> <p>And another paragraph</p> <blockquote> <p>And another</p> </blockquote> </blockquote> </blockquote>

헤더, 코드, 목록 항목 등과 같은 다른 Markdown 요소를 포함할 수도 있습니다.

 <!--Markdown--> > Blockquote with a paragraph > # Heading 1 > Heading 2 > - > 1. One > 2. Two <!--Rendered HTML--> <blockquote> <p>Blockquote with a paragraph</p> <h1>Heading 1</h1> <h2>Heading 2</h2> <ol> <li>One</li> <li>Two</li> </ol> </blockquote>

• 인용 부호에 대해 배울 수 있는 대화형 자습서.
• 미리보기 및 AST로 전체 예제를 확인하려면 Dingus 영구 링크를 클릭하세요.
• 인용 부호에 대해 자세히 알아보십시오.

암호

HTML 인라인 코드 요소인 <code>도 지원됩니다. 하나를 만들려면 백틱(`)으로 텍스트를 구분하거나, 둘러싸는 텍스트에 리터럴 백틱이 필요한 경우 이중 백틱으로 구분합니다.

 <!--Markdown--> `inline code snippet` <!--Rendered HTML--> <code>inline code snippet</code> <!--Markdown--> `<button type='button'>Click Me</button>` <!--Rendered HTML--> <code><button type='button'>Click Me</button></code> <!--Markdown--> `` There's an inline back-tick (`). `` <!--Rendered HTML--> <code>There's an inline back-tick (`).</code>

• 코드에 대해 배울 수 있는 대화형 자습서.
• 미리보기 및 AST로 전체 예제를 확인하려면 Dingus 영구 링크를 클릭하세요.
• 코드 범위에 대해 자세히 알아보세요.

코드 블록

HTML Preformatted Text 요소인 <pre>도 지원됩니다. 이것은 적어도 3개와 동일한 수의 경계 백틱( ` ) 또는 물결표( ~ )로 수행할 수 있습니다. 일반적으로 코드 펜스라고 하거나 최소 4개 공백의 들여쓰기를 시작하는 새 줄이라고 합니다.

 <!--Markdown--> ``` const dedupe = (array) => [...new Set(array)]; ``` <!--Rendered HTML--> <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre> <!--Markdown--> const dedupe = (array) => [...new Set(array)]; <!--Rendered HTML--> <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre>

• 코드에 대해 배울 수 있는 대화형 자습서.
• 미리보기 및 AST로 전체 예제를 확인하려면 Dingus 영구 링크를 클릭하세요.
• 분리 및 들여쓰기 코드 블록에 대해 자세히 알아보십시오.

인라인 HTML 사용

인라인 HTML에 대한 John Grubers의 원래 사양 노트에 따르면 Markdown의 구문에서 다루지 않는 모든 마크업은 HTML 자체를 사용하기 만 하면 됩니다 . 유일한 제한 사항은 블록 수준 HTML 요소(예: <div> , <table> , <pre> , <p> 등 — 주변 콘텐츠와 공백 줄로 구분해야 하며 블록의 시작 및 끝 태그는 탭이나 공백으로 들여쓰지 않아야 합니다.

그러나 CommonMark 자체 또는 그와 관련된 사람이 아닌 한 현재 CommonMark에서 지원하지 않는 많은 구문을 처리하도록 이미 확장된 특징을 사용하여 Markdown을 작성할 가능성이 큽니다.

앞으로

CommonMark는 2019년 4월 6일에 마지막으로 업데이트된 사양으로 지속적인 작업이 진행 중입니다. Markdown 도구 풀에서 이를 지원하는 인기 있는 응용 프로그램이 많이 있습니다. 표준화를 위한 CommonMark의 노력에 대한 인식으로, Markdown의 단순성에는 배후에서 많은 작업이 진행되고 있으며 GitHub Flavored Markdown의 공식 사양이 사양을 기반으로 합니다.

CommonMark 표준화 노력을 향한 움직임은 지원되는 구문을 확장하기 위한 풍미 생성을 방해하지 않으며 CommonMark가 해결해야 하는 문제와 함께 릴리스 1.0을 준비함에 따라 다음을 위해 사용할 수 있는 지속적인 노력에 대한 몇 가지 흥미로운 리소스가 있습니다. 숙독.

자원

• John Gruber의 Markdown 소개
• 커먼마크 공식 홈페이지
• GitHub 맛 마크다운 사양
• 씨마크 공식 레포
• GitHub의 cmark 포크
• 위키피디아의 마크다운
• 마크다운 가이드