Quick Syntax
| 목적 | 예시 | 결과 |
|---|---|---|
| ampersand 표시 | & | & |
| pipe 표시 | | | | |
| backtick 표시 | ` | ` |
| less-than 표시 | < | < |
| greater-than 표시 | > | > |
AT&T
표 안의 pipe: <code>A|B</code>
HTML 태그를 문자로 보기: <div>일반 Markdown 기호는 backslash escape를 먼저 쓰고, HTML 문자 자체를 렌더링해야 하거나 escape가 문맥상 부족할 때만 entity reference를 씁니다. entity는 문자 출력 방식일 뿐 raw HTML sanitize를 우회하거나 code 원문을 보존하는 보안 기능이 아닙니다.
구조
Entity reference는 Markdown 문법 문자가 아니라 HTML 문자 참조입니다. CommonMark 렌더러는 이름 기반 entity와 10진수, 16진수 numeric reference를 해석해 실제 문자로 바꿉니다.
이름 기반: &
10진수: |
16진수: |Backslash escape와 역할이 겹치는 경우도 있습니다. 예를 들어 일반 문단에서 pipe를 문자로 보이게 하려면 \|가 더 읽기 쉽습니다. 하지만 Markdown 표 안에서 inline code와 pipe가 같이 섞이면 <code>|</code>처럼 entity가 더 안전할 수 있습니다.
| 표현 | 의미 |
| --- | --- |
| <code>A|B</code> | pipe 문자 포함 |Entity는 HTML 출력 단계에서 문자로 바뀌므로, 코드 예시를 그대로 보여 주고 싶다면 entity보다 fenced code block이나 inline code를 먼저 검토합니다.
선택 기준
| 상황 | 선택 |
|---|---|
| 일반 문단의 Markdown 기호 표시 | backslash escape |
| 코드나 명령어 표시 | inline code 또는 code fence |
| 표 셀 안의 pipe 표시 | | 또는 <code>|</code> |
| HTML 태그를 문자로 설명 | <tag> |
| 렌더링 후 실제 문자가 필요 | entity reference |
| 원본 그대로 보존 필요 | code fence |
문서 원본을 읽는 사람에게도 의도가 보여야 합니다. entity를 많이 쓰면 원문 가독성이 떨어지므로, escape와 code fence로 해결 가능한 곳에는 entity를 남용하지 않는 편이 좋습니다.
주의할 점
Entity reference는 렌더링 결과를 바꾸는 문법입니다. 원본에 &라고 적어도 화면에는 &로 보일 수 있으므로, entity 자체를 설명해야 하는 문서에서는 code fence 안에 넣어야 합니다.
또 모든 named entity를 독자가 바로 이해하는 것은 아닙니다. &, <, >처럼 널리 알려진 항목 외에는 numeric reference가 왜 필요한지 짧게 설명하세요.
참고 링크
1 sources