php markdown extra - nolboo/wiki-syntax GitHub Wiki
Markdown Extra는 순수 마크다운 문법에서 제공하지 않는 몇 가지 기능을 제공하는 PHP 마크다운 확장이다. 이 문서를 읽기 전에 마크다운 문법에 이미 친숙해야 한다.
마크다운에선 텍스트 중간에 HTML을 입력할 수 있으나, 블럭 엘리먼트에선 심각한 제한을 가지고 있다. 마크다운 문법 문서에서:
블럭 엘리먼트 - 예.
<div>,<table>,<pre>,<p>등 - 는 주변 콘텐츠와 빈 줄로 구분하고(한 칸씩 띄어주고) 블럭의 시작과 끝 태그는 탭이나 공백으로 들여쓰면 안된다.
이 제한은 PHP Markdown Extra에서 해제되고 다음의 덜 제한적인 두 가지로 대치된다:
-
블럭 엘리먼트의 시작 태그 세 개 이상의 여백으로 들여 쓰지 말아야 한다. 그 이상으로 들여쓴 태그는 표준 마크다운 규칙에 따라 코드블럭으로 다루어진다.
-
목록 안에서의 블럭 엘리먼트는 목록 항목이 들여쓰기 된 같은 크기의 여백으로 들여 쓰여야 한다.(추가적인 들여쓰기는 첫 시작 태그가 너무 많이 들여 쓰지 않는 한 코드블럭이 된다. - 첫 번째 규칙을 보라)
블럭레벨 태그 안에서 마크다운 형식의 텍스트를 넣을 수 있다. markdown 속성에 1 값을 줌으로 써 - markdown="1" 준다 - 다음은:
<div markdown="1">
This is *true* markdown text.
</div>
다음으로 바뀐다:
<div>
<p>This is <em>true</em> markdown text.</p>
</div>
PHP Markdown Extra는 markdown 속성을 넣은 블럭 엘리먼트에 따른 정확한 포매팅을 제공할 정도로 똑똑하다. 예를 들어 <p>태그에 markdown 속성을 적용하면, 스팬레벨 엘리먼트만을 만들어낸다. - 목록, 블럭인용, 코드블럭은 허용하지 않는다.
그러나, 몇 가지 애매모호한 경우가 있다. 예를 들면:
<table>
<tr>
<td markdown="1">This is *true* markdown text.</td>
</tr>
</table>
테이블 셀은 스팬과 블럭 엘리먼트를 모두 포함할 수 있다. 위의 예에선 PHP Markdown Extra에선 스팬 레벨 규칙만을 적용한다. 블럭이 되길 원하면, markdown="block"을 대신 입력한다.
속성 블럭을 이용하여 id와 클래스 속성을 설정할 수 있다. 예로, 줄의 끝에서 헤더 다음에 중괄호안 해쉬로 시작하는 원하는 id를 다음과 입력한다:
Header 1 {#header1}
========
## Header 2 ## {#header2}
그런 후에 동일한 문서의 다른 부분에서 다음과 같이 링크를 만들 수 있다:
[Link back to header 1](#header1)
클래스 이름을 넣으려면, 다음과 같이 하나의 점을 사용한다:
## The Site ## {.main}
같은 특정 속성 블럭을 추가하여 id와 여러 클래스 이름을 결합할 수 있다.
## The Site ## {.main .shine #the-site}
이 경우, 특정 속성 블럭은 다음과 함께 사용될 수 있다.
- headers,
- fenced code blocks,
- links, and
- images.
이미지와 링크에선 특정 속성 블럭을 주소 괄호 바로 다음에 넣는다.
[link](url){#id .class}
{#id .class}
또는 참조 스타일의 링크와 이미지를 사용할 경우엔, 다음과 같이 참조 라인 끝에 넣는다:
[link][linkref] or [linkref]
![img][linkref]
[linkref]: url "optional title" {#id .class}
울타리 코드블럭은 마크다운의 코드블럭과 유사하나, 코드블럭을 구분하기 위해 들여 쓰지 않고 시작과 끝 울타리 라인을 넣는다. 코드블럭은 3 새 이상의 물결표 ~ 문자로 시작하고, 같은 수의 물결표 ~로 끝난다. 예로:
This is a paragraph introducing:
~~~~~~~~~~~~~~~~~~~~~
a one-line code block
~~~~~~~~~~~~~~~~~~~~~
물결표 대신에 ``` 문자를 사용할 수도 있다:
``````````````````
another code block
``````````````````
들여쓰기와 다르게, 울타리 코드 블럭은 빈줄로 시작하고 끝낼 수 있다.
~~~
blank line before
blank line after
~~~
들여쓴 코드블럭은 목록 들여쓰기가 우선하기 때문에 목록 다음에 바로 사용될 수 없다; 울타리 코드블럭은 그런 제한이 없다:
1. List item
Not an indented code block, but a second paragraph
in the list item
~~~~
This is a code block, fenced-style
~~~~
울타리 코드블럭은 편집기에서 코드를 붙여 넣을 필요가 있을 때 텍스트 블럭의 들여쓰기를 증가시키지 않기 때문에 이상적이다.
드블럭에 적용할 클래스 이름을 특정할 수 있다. 이것은 언어에 따른 스타일을 달리 적용할 때 유용한다. 혹은 사용한 문법에 문법 강조를 지정할 때도 유용하다.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .html
<p>paragraph <b>emphasis</b>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
클래스 이름은 첫 울타리의 마지막에 둔다. 점이 시작할 수 있으나 필수는 아니다. 특정 속성 블럭을 사용할 수도 있다:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.html #example-1}
<p>paragraph <b>emphasis</b>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
더 자세한 것은 configuration를 참조한다.
PHP Markdown Extra는 간단한 표를 위한 고유 문법이 있다. "간단한" 표는 다음과 같다:
First Header | Second Header
------------- | -------------
Content Cell | Content Cell
Content Cell | Content Cell
첫번째 줄은 행 제목이고; 두번째 줄은 제목과 내용 사이의 구분줄이다; 뒤따르는 줄은 테이블의 열이다. 행은 파이프(|) 문자로 나뉜다. HTML로 변환된 결과는 다음과 같다:
<table>
<thead>
<tr>
<th>First Header</th>
<th>Second Header</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content Cell</td>
<td>Content Cell</td>
</tr>
<tr>
<td>Content Cell</td>
<td>Content Cell</td>
</tr>
</tbody>
</table>
원한다면, 테이블 각 줄에 머리와 꼬리 파이프를 추가할 수 있다. 다음은 위와 같은 결과를 줄 것이다:
| First Header | Second Header |
| ------------- | ------------- |
| Content Cell | Content Cell |
| Content Cell | Content Cell |
주의: 각 줄에 적어도 하나의 파이프가 필요하다. 즉, 하나의 행만을 가진 표를 만들려면 각 줄에 머리나 꼬리 파이프 또는 둘다를 추가해야 한다.
구분선에 콜론을 추가해서 각 행의 정렬을 지정할 수 있다. 구분선의 왼쪽에 콜론은 왼쪽 정렬될 것이며; 오른쪽의 콜론은 오른쪽 정렬이 될 것이다; 양쪽 모두의 콜론은 중앙 정렬된다.
| Item | Value |
| --------- | -----:|
| Computer | $1600 |
| Phone | $12 |
| Pipe | $1 |
관련 행의 각 셀에 align HTML 속성이 적용된다.
마크다운 문법을 사용하여 각 셀의 컨텐츠에 스팬레벨 형식을 적용할 수 있다:
| Function name | Description |
| ------------- | ------------------------------ |
| `help()` | Display the help window. |
| `destroy()` | **Destroy your computer!** |
정의 목록은 사전과 같이 용어(term)와 용어의 정의(definition)로 구성된다.
PHP Markdown Extra에서 간단한 정의 목록은 한 줄의 용어와 이어지는 콜론과 그 용어에 대한 정의로 이루어진다.
Apple
: Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.
Orange
: The fruit of an evergreen tree of the genus Citrus.
용어는 앞의 정의로부터 빈 줄로 구분되어야 한다. 정의는 여러 줄에 걸쳐 쓸 수 있으며, 이 경우 반드시 들여쓰여야 한다. 그러나 반드시 그렇게 하지 않아도 작동한다.
Apple
: Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.
Orange
: The fruit of an evergreen tree of the genus Citrus.
위의 정의 목록은 각각 같은 HTML 결과를 가져온다:
<dl>
<dt>Apple</dt>
<dd>Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.</dd>
<dt>Orange</dt>
<dd>The fruit of an evergreen tree of the genus Citrus.</dd>
</dl>
정의 표시자로서의 콜론은 왼쪽 마진에서 시작하고 세 개까지 들여 쓰일 것이다. 정의 표시자는 반드시 하나의 이상의 여백과 하나의 탭이 이어져야 한다.
정의 목록은 하나의 용어에 하나 이상의 정의를 가질 수 있다:
Apple
: Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.
: An American computer company.
Orange
: The fruit of an evergreen tree of the genus Citrus.
하나의 정의에 하나 이상의 용어를 결부시킬 수도 있다:
Term 1
Term 2
: Definition a
Term 3
: Definition b
정의 앞에 빈줄이 있다면 PHP Markdown Extra는 <p> 태그로 정의를 감쌀 것이다. 예를 들면:
Apple
: Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.
Orange
: The fruit of an evergreen tree of the genus Citrus.
는 다음과 같이 변환된다:
<dl>
<dt>Apple</dt>
<dd>
<p>Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.</p>
</dd>
<dt>Orange</dt>
<dd>
<p>The fruit of an evergreen tree of the genus Citrus.</p>
</dd>
</dl>일반적인 목록 항목과 같이, 정의는 여러 문단을 포함할 수 있으며, 블럭인용, 목록, 다른 정의 목록과 같은 블럭레벨 엘리먼트를 포함할 수 있다.
Term 1
: This is a definition with two paragraphs. Lorem ipsum
dolor sit amet, consectetuer adipiscing elit. Aliquam
hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet
vitae, risus.
: Second definition for term 1, also wrapped in a paragraph
because of the blank line preceding it.
Term 2
: This definition has a code block, a blockquote and a list.
code block.
> block quote
> on two lines.
1. first list item
2. second list item
각주(footnote)는 참조 링크처럼 작동한다. 각주는 두 가지로 이루어진다: 위첨자 숫자가 될 문자가 들어있는 표시자; 문서의 끝에 각주의 목록으로 위치되는 각주 정의. 각주는 다음과 같이 보인다:
That's some text with a footnote.[^1]
[^1]: And that's the footnote.
각주 정의는 문서의 아무 곳에나 있을 수 있으나, 각주는 텍스트 안에 링크될 순서대로 나열되어야 한다. 같은 각주에 두 개의 링크를 만들 수 없다는 것을 주의하라: 그렇게 한다면 두번째 각주 참조는 그냥 일반 텍스트로 남겨질 것이다.
각 각주는 다른 이름을 가져야 한다. 그 이름은 각주 정의에 각주 참조를 링크하기 위해 사용될 것이나, 각주의 번호부여에는 영향이 없다. 이름은 HTML의 ID 속성에 유효한 모든 문자를 사용할 수 있다.
각주는 블럭레벨 엘리먼트를 포함할 수 있다, 즉, 여러 단락, 목록, 블럭인용 등을 사용할 수 있다. 목록 항목에서 처럼 작동한다: 각주 정의에서 네 개의 여백으로 단락을 들여쓰기만 하라:
That's some text with a footnote.[^1]
[^1]: And that's the footnote.
That's the second paragraph.
더 낫게 정렬하려면, 아래와 같이 각주의 첫 줄을 비우고 첫 번째 단락을 그 밑에 넣는다:
[^1]:
And that's the footnote.
That's the second paragraph.
현재 버전에서 출력은 존 그루버 방식을 따른다. 위의 첫번째 예의 기본 출력은 다음과 같다:
<p>That's some text with a footnote.
<sup id="fnref-1"><a href="#fn-1" class="footnote-ref">1</a></sup></p>
<div class="footnotes">
<hr />
<ol>
<li id="fn-1">
<p>And that's the footnote.
<a href="#fnref-1" class="footnote-backref">↩</a></p>
</li>
</ol>
</div>링크에서 class="footnote-ref" 와 class="footnote-backref"> 속성은 링크하고 있는 엘리먼트에 대한 관계를 표현한다. 다음과 같은 CSS 규칙으로 엘리먼트를 스타일링할 수 있다.
a.footnote-ref { ... }
a.footnote-backref { ... }
각주 링크와 백링크에서 class와 title 속성을 커스터마이징할 수 있다. 자세한 내용은 환경설정을 참조하라.
HTML tag <abbr>에 해당하는 약어를 지원한다. 다음과 같이 약어 정의를 만든다:
*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium
그리고 문서의 어딘가에 텍스트를 쓴다:
The HTML specification
is maintained by the W3C.
그러면 해당 단어들은 다음과 같이 된다:
The <abbr title="Hyper Text Markup Language">HTML</abbr> specification
is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.
약어는 대소문자를 구별하고 정의될 때 여러 단어에 걸칠 수 있다. 빈 정의도 가질 수 있으며, 이 경우 <abbr> 태그는 추가되고 title 속성은 생략된다.
Operation Tigra Genesis is going well.
*[Tigra Genesis]:
약어 정의는 문서 어디에나 있을 수 있으며, 최종 문서에선 제거된다.
한 단어 중간의 밑줄은 문자 그래도 취급된다. 밑줄 강조는 전체 단어에 대해서만 작동한다. 단어의 어떤 부분만 강조할 필요가 있으면, 별표(*)를 사용할 수 있다.
예로, 다음은:
Please open the folder "secret_magic_box".
PHP Markdown Extra는 단어의 중간에 밑줄이 있기 때문에 강조하지 않는다. HTML 결과는 다음과 같다:
<p>Please open the folder "secret_magic_box".</p>
밑줄 강조는 다음과 같이 전체 단어들을 강조할 때만 작동한다:PHP
I like it when you say _you love me_.
PHP Markdown Extra는 콜론(:)과 파이프(|)를 백슬래쉬 예외처리에 추가한다. 정의 목록과 표로 변환되는 것을 예방한다.