빠른 비교
| 목적 | 예시 | 결과 |
|---|---|---|
| ampersand 표시 | & | & |
| pipe 표시 | | | | |
| backtick 표시 | ` | ` |
| less-than 표시 | < | < |
| greater-than 표시 | > | > |
AT&T
표 안의 pipe: <code>A|B</code>
HTML 태그를 문자로 보기: <div>구조
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