나는 플러그인 README, 변경 로그, 문서 등 수년 동안 매일 Markdown을 작성했습니다 Toolz.devWP Adminify 의 릴리스 노트,내 커밋 메시지의 절반. 그리고 그 시간의 대부분 동안 나는 렌더링 단계를 마법으로 취급했습니다. 별표를 쓰면 GitHub 는 굵게 표시됩니다. 괜찮아. 계속 진행하세요.
그리고는 데이터베이스에서 마크다운을 꺼내어 Next.js 페이지로 렌더링하는 docs 섹션을 만들었고,마법은 내가 내려야 했던 매우 구체적인 결정의 목록으로 바뀌었다. 하나의 개행이 a 가 되는가 <br>? (GitHub 댓글은 그렇다고 답했습니다. Markdown 사양은 그렇지 않다고 답했습니다.) 그렇습니다 <div> 소스 렌더링에서 div 또는 리터럴 텍스트로? (누가 묻고 있는지,저자를 신뢰하는지에 따라 다릅니다.) 울타리가 있는 코드 블록에 어떤 클래스가 들어가므로 형광펜이 이를 집어들까요? 왜 하나의 파서가 돌아서는가 **bold**text 굵게 표시하면 다른 사람이 그대로 두나요?
그 어느 것도 이국적이지 않습니다. 그것은 단지 아무도 당신에게 말하지 않는 것들입니다. 왜냐하면 Markdown 은 너무 단순 해 보이기 때문에 사람들은 그 아래에 아무것도 없다고 가정합니다. 그 아래에는 꽤 많은 것이 있습니다. The 마크다운에서 HTML로 Toolz.dev의 변환기는 이러한 결정을 숨기기보다는 스위치로 노출합니다. 이는 줄 바꿈이 계속 사라지는 이유를 디버깅할 때 원했던 이 도구의 버전입니다.
TL;DR: 마크다운은 쓰기 형식이다; HTML 은 디스플레이 형식이다. 어떤 것은 하나를 다른 것으로 컴파일해야 한다. 사람들을 넘어뜨리는 규칙: 연속적인 줄은 두 칸으로 줄을 끝내지 않는 한 (또는 "breaks" 옵션을 켜지 않는 한) 한 단락으로 결합되며,원시 HTML 은 파서's 신뢰 설정에 따라 통과되거나 이스케이프되며,GitHub's 방언 (GFM) 은 테이블,작업 목록, 취소선 및 맨 URL 자동 연결을 그 위에 추가합니다 커먼마크 기준선. 울타리가 있는 코드는 다음과 같이 컴파일됩니다
<pre><code class="language-js">후크 프리즘인 는.js와 Shiki가 찾는 하이라이트입니다. 그만큼 HTML 변환기로 마크다운 모든 스위치가 노출된 상태에서 브라우저에서 이 모든 작업을 수행합니다.
Markdown이란 무엇이며 왜 전환이 필요한가요?
마크다운은 존 그루버가 2004 년에 발표한 평문 문법인데, 한가지 명시된 디자인 목표를 가지고 있다: 마크다운 문서는 태그로 마크업된 것처럼 보이지 않고 그대로 출판할 수 있고, 평문으로 읽을 수 있어야 한다. 그래서 그 문법은 사람들이 이미 이메일에 사용한 관례에서 차용한 것이다 - 강조를 위한 단어 주위의 별표, 제목 아래의 대시줄, a > 견적을 위해.
그 결과 Markdown 은 렌더링 형식이 아닙니다. 아무것도 Markdown 을 표시하지 않습니다. 브라우저는 HTML 을 표시하고,당신이 이제까지 가지고있는 모든 장소 본 Markdown 렌더링 - GitHub, 정적 사이트, 문서 포털, 채팅 앱 - 먼저 파서를 실행하고 화면에 HTML을 넣었습니다.
그래서 변환은 어딘가에서 일어나야 합니다. 당신의 선택지는 대략:
- 빌드 타임에정적 사이트 생성기 또는 번들러에서. 콘텐츠가 repo에 있으면 괜찮습니다.
- 요청 시간에서버에서. 콘텐츠가 데이터베이스에서 나올 때 필요하며 캐싱 없이 모든 요청에 대해 수행하는 경우 비용이 많이 듭니다.
- 브라우저에서, 당신이 그것을 필요로 하는 순간에. "I에 대한 대답이 단지 이 한 가지에 대한 HTML이 필요할 때 당신이 원하는 것입니다."는 빌드 파이프라인이 아니라 복사-붙여넣기입니다.
그 세 번째 경우는 소리보다 더 일반적입니다. 릴리스 노트를 HTML 만 가져 오는 CMS 필드에 붙여 넣기. README 를 전자 메일 템플릿으로 가져옵니다. 커밋하기 전에 문서가 어떻게 생겼는지 확인합니다. Obsidian 으로 작성된 초안을 디자이너에게 건네 줄 수있는 것으로 변환합니다. 그 중 어느 것도 파서를 프로젝트에 배선하는 것을 정당화하지 못합니다.
CommonMark와 차이점은 무엇입니까 깃허브 맛 마크다운?
Gruber's 원래 사양은 산문 페이지와 Perl 스크립트였으며 모든 구현이 엣지 케이스에 동의하지 않을 정도로 모호함을 남겼습니다. 커먼마크 이에 대한 답입니다: 수백 개의 예제 적합성 제품군을 갖춘 엄격하고 테스트 가능한 사양으로, 두 개의 적합 파서가 동일한 입력에 대해 동일한 출력을 생성합니다. 이는 기준선 - 제목, 단락, 강조, 링크, 이미지, 목록, 블록 인용, 코드 블록, 주제별 중단, 백슬래시 이스케이프, HTML 블록을 정의합니다.
깃허브 맛 마크다운(GFM) 는 사람들이 계속 요구했던 것들을 추가하는 GitHub 에 의해 지정된 CommonMark 의 공식적인 슈퍼세트입니다:
| 특징 | 커먼마크 | GFM | 구문 |
|---|---|---|---|
| 테이블 | 아니요 | 예 | | a | b | a와 함께 | --- | --- | 구분자 행 |
| 작업 목록 | 아니요 | 예 | - [x] done / - [ ] todo |
| 취소선 | 아니요 | 예 | ~~gone~~ |
| 자동 링크된 기본 URL | 아니요 | 예 | https://toolz.dev 부류 없음으로 |
| 각주 | 아니요 | 예 (GitHub 확장) | [^1] |
| 제목, 목록, 코드, 강조 | 예 | 예 | 동일한 |
만약 당신의 마크다운이 GitHub README,GitLab 위키,Notion 내보내기 또는 대부분의 최신 편집기에서 나왔다면,그것은 GFM 입니다. 변환기에서 GFM 을 켜거나 테이블이 리터럴 파이프로 렌더링될 것인데,이것은 1 위 "the converter is broken" support question anyone who ships one of these tools receives 입니다.
왜 내 라인 브레이크가 사라졌습니까?
일반 텍스트 이메일의 관례에 따라 Markdown 은 공백이 아닌 연속된 줄을 하나의 단락으로 취급하기 때문입니다. 이:
Line one
Line two
생산합니다 <p>Line one\nLine two</p>- 한 단락, 그리고 개행은 브라우저가 그것을 렌더링 할 때 공간으로 축소. 그것은 버그가 아니다; 그것은 사양이며, 그것은 당신이 출력으로 누출 그 래핑없이 텍스트 편집기에서 80 열에 산문을 하드 랩 수 있도록 존재합니다.
실제 휴식을 취하는 방법에는 세 가지가 있습니다:
- 빈 줄 새로운 단락을 시작합니다. 이것은 당신이 대부분의 시간을 원하는 것입니다.
- 두 개의 후행 공간 라인의 끝에서 하드 브레이크를 생산 -
<br />. 이것은 표준 트릭이며 편집기에는 보이지 않으므로 사람들은 이를 미친 짓이라고 생각합니다. - 백슬래시 줄 끝에서도 CommonMark에서 동일한 작업을 수행하며 최소한 표시됩니다.
그리고 네 번째 방법이 있는데, 이것이 혼란의 근원입니다: 많은 플랫폼이 "breaks" 모드를 켭니다 모든 개행이 a가 되는 곳 <br />. GitHub 댓글과 이슈가 이를 수행합니다. 대부분의 채팅 앱이 이를 수행합니다. GitHub README 파일 하지 마십시오. 따라서 동일한 텍스트는 GitHub 문제와 동일한 저장소의 README에서 다르게 렌더링됩니다. 이는 현재 우리 모두가 고수하고 있는 정말 나쁜 디자인입니다.
변환기는 이것을 스위치로 노출합니다. 소스가 채팅 스타일 렌더러용으로 작성된 경우 회선 끊김을 켜십시오. 문서인 경우 해제하고 사양이 의도하는 것처럼 빈 줄을 사용하십시오.
원시 HTML은 어떻게 처리되나요?
Markdown 은 인라인 HTML 을 허용합니다 - 원래 사양은 명시적으로 당신이 쓰는 모든 HTML 이 곧바로 통과한다고 말합니다. 그것은 당신이 저자 일 때 기능입니다 (당신은 당신의 <details> 블록, 당신의 <img> 너비 속성이 있는 앵커에는 a가 있습니다 rel), 그렇지 않은 경우에는 책임이 있습니다.
HTML 통과를 활성화하여 신뢰할 수 없는 Markdown을 렌더링하면 XSS 취약점이 발생하기 때문입니다. <script>alert(document.cookie)</script> 는 유효한 마크다운이다.So is valid Markdown <img src=x onerror="...">. 그래서 <a href="javascript:...">. 댓글 상자, 사용자 프로필 약력, 공개 위키 - 낯선 사람이 다른 사람이 읽는 Markdown을 쓰는 곳이라면 어디든 HTML을 벗어나거나 실제 소독제로 출력을 소독해야 합니다(DOMPurify가 일반적인 답변이며, 이는 정확히 다음과 같은 이유로 실제 소독제입니다. regex는 적대적인 입력으로는 충분하지 않습니다.).
이 변환기는 기본값으로 탈출 원시 HTML: <div> 소스에서 문자 그대로의 텍스트로 나타납니다 <div> 출력에서, 정확히 당신이 쓴 것처럼 <div>. 소스가 자신의 것일 때 전달을 켤 수 있습니다. 그리고 그 설정에 관계없이 라이브 미리보기가 스트립됩니다 <script>, <style>, 인라인 on* 이벤트 핸들러 및 javascript: URLs before it renders - a defense in depth measure,so pasting someone else's README into the preview pane cannot execute their code. 즉,범용 소독제가 아닌 미리보기-안전 조치입니다: 사용자 마크다운을 렌더링하는 제품을 빌드하는 경우 전용 소독제 서버 측을 사용하고 regex 를 신뢰하지 마십시오,내 포함.
캐릭터에서 탈출해야 하는 경우 부터 마크다운은 문자 그대로 렌더링합니다. 별표로 유지되어야 하는 별표, 파일 이름의 밑줄 - 백슬래시가 이를 수행합니다: \*not emphasis\*. 그리고 다른 방향으로 엔터티를 놓고 논쟁을 벌이고 있다면 HTML 엔터티 인코더/디코더 은 그 일을 위한 도구이다.
좋은 컨버터는 실제로 어떤 HTML을 방출해야합니까?
의미론적이고 지루하며 클래스 없는 HTML - 한 가지 예외가 있습니다.
- 제목이 됩니다
<h1>-<h6>. 제목 ID가 활성화되면 각각 슬러지화도 발생합니다id두 제목이 제목을 공유하는 경우(, 중복 제거됨)#setup,#setup-1). 그것이 만드는 것입니다#anchor딥 링크가 작동하며 이는 목차 생성기가 중단되는 것입니다. - 정보 문자열이 있는 울타리가 있는 블록 -
```js- 된다<pre><code class="language-js">. *예외입니다.** The `language-` class is the convention Prism,highlight.js and Shiki all look for,and it is why the converter emits a class at all. 변환기는 코드를 색칠하지 않습니다; 페이지의 형광펜은 색칠을 하고,그 후크가 필요합니다. - 목록이 됩니다
<ul>/<ol>그리고 여기에 알 만한 미묘함이 있습니다: a 단단한 목록(항목 사이에 빈 줄 없음)은 텍스트를 바로 안에 넣습니다<li>, 동안 느슨한 목록 (항목 사이 공백 선) 는 각 item's 내용을 안으로 감쌉니다<p>. 그것은 특이한 것이 아니라 CommonMark 동작입니다. 두 글머리 기호 사이에 빈 줄을 추가하면 목록이 갑자기 수직 간격이 늘어나는 이유입니다. CSS는 깨지지 않습니다; HTML이 실제로 변경되었습니다. - 테이블이 진짜가 된다
<table>/<thead>/<tbody>마크업, withstyle="text-align:center"구분자 행이 사용하는 셀에:---:. - 작업 목록이 됩니다
<input type="checkbox" disabled>내부<li>는 GitHub가 방출하는 것과 정확히 같습니다.
콘텐츠 우선, 래퍼 div도 없고 유틸리티 클래스도 없습니다. 외부에서 스타일을 지정합니다 .prose 클래스 또는 자신의 규칙, 그리고 마크업은 휴대용 유지.
컨버터는 어떻게 사용하나요?
1 단계: 마크다운 붙여넣기
README, 변경 로그, 릴리스 노트, 초안을 드롭합니다. 입력할 때 업데이트를 출력합니다. 변환 버튼이 없으며 업로드되는 것이 없습니다.
2 단계: 스위치를 설정합니다
깃허브 맛 소스에 테이블, 작업 목록 또는 취소선이 있는 경우(아마도 그럴 것입니다). 제목 ID 앵커를 원한다면 켜세요. 줄 바꿈 소스가 채팅 스타일 렌더러용으로 작성된 경우에만 켜집니다. 원시 HTML 허용 소스가 귀하의 것인 경우에만 가능합니다. 전체 문서 doctype, 문자 집합, 뷰포트 및 a가 포함된 완전한 HTML5 페이지를 원하는 경우 <title> 당신의 첫 번째에서 가져온 것입니다 <h1>- 브라우저에서 직접 결과를 열거나 정적 호스트에 드롭하려는 경우에 유용합니다.
3 단계: 미리보기 확인
미리보기 탭으로 전환하고 구조를 확인합니다. stats 행은 단어,제목, 링크,이미지, 코드 블록 및 읽기 시간을 알려줍니다. - 게시물을 확인하는 데 편리합니다. 게시하기 전에 생각했던 길이입니다. 더 철저한 카운트를 위해,the 워드 카운터 동일한 텍스트에 대한 가독성과 키워드 밀도가 있습니까.
4 단계: 출력을 가져 가라
HTML을 복사하여 다운로드하세요 .html 생성된 목차를 파일화하거나 복사합니다. 각 제목 앵커에 연결되는 Markdown 중첩 목록이 문서 상단에 다시 붙여넣을 준비가 되어 있습니다.
바이트가 중요한 페이지에 결과를 붙여넣는 경우 해당 페이지를 통해 실행하세요 HTML 미니파이어 그 후에. converter's 산출은 가독성을 위해,철사를 위해 아닙니다 들여쓰기됩니다.
일반적인 사용 사례
README를 웹사이트에 게시합니다
플러그인 및 패키지 작성자는 좋은 README 를 작성한 다음 랜딩 페이지에 동일한 콘텐츠가 필요합니다. README 는 테이블과 배지가있는 GFM 입니다; 랜딩 페이지에는 HTML 이 필요합니다. 기존 CSS 로 변환,붙여 넣기,스타일링. 제목 ID 는 무료로 사이드 바 TOC 를 제공합니다.
HTML만 허용하는 CMS에 게시합니다
CMS 분야의 많음,이메일 플랫폼 및 유산 행정관은 HTML 를 가지고 가고 다른 것은 가지고 가지 않는다. 당신이 Markdown 에서 초안하는 경우에 - 그리고 정기적으로 쓰는 대부분의 사람들은 한다 - 이것은 교량으로 개조한다 전체 문서 꺼짐, 그래서 당신은 전체 페이지가 아닌 조각을 얻을, 필드에 붙여 넣기.
문서 페이지 프로토타입 제작
콘텐츠를 docs 사이트에 커밋하기 전에 로컬로 변환하면 실제 제목 계층 구조와 코드 울타리가 올바른 언어를 전달하는지 여부가 표시됩니다. An h3 그것은 그랬어야 했습니다 h2 TOC에서는 명백하고 소스에서는 보이지 않습니다.
다른 사람이 작성한 감사 내용
기여자 붙여넣기's Markdown,방출된 HTML 을 보면,그들이 실제 제목을 사용했는지 아니면 가짜에 줄을 굵게 표시했는지 즉시 확인할 수 있습니다 - 문서 구조와 접근성을 파괴하는 습관 화면 판독기 제목을 탐색; **Big Text** 는 제목이 아니고 굵은 글씨로 된 단락이며 변환기는 이를 한 줄의 출력으로 보여줍니다.
목차 추출하기
긴 문서는 하나가 필요하며 손으로 유지하면 오래도록 유지됩니다. 제목에서 생성하고 붙여넣고 제목이 바뀔 때마다 재생성하세요.
고급: 이 파서가 수행하는 작업과 수행하지 않는 작업입니다
그것은 의존성이없는 대략 400 줄의 손으로 쓴 파서입니다 - 고의적 인 것입니다, 왜냐하면 전체 요점이 빠른 페이지로 200KB 의존성을 끌어들이는 Markdown 파서는 나쁜 거래이기 때문입니다.
덮여 있음: ATX 제목(# x) 및 setext 제목(밑줄이 그어져 있음) === / ---), 단락, 강조 및 강함(*, _, **, __), 백틱 실행 일치 기능이 있는 인라인 코드, 정보 문자열이 있는 울타리 코드, 들여쓰기된 코드 블록, 게으른 연속 기능이 있는 블록 인용문, 중첩된 목록(순서 및 비순서, 빡빡하고 느슨함), 주제별 나누기, 제목이 있는 링크 및 이미지, 각도 브래킷 자동 링크, 이메일 자동 링크, 백슬래시 이스케이프 및 GFM 세트: 정렬이 있는 테이블, 작업 목록, 취소선, BARE-URL 자동 링크.
다루지 않음: 참조 스타일 링크([text][ref] a와 함께 [ref]: url 다른 곳의 정의), 각주,정의 목록,그리고 단락을 방해하는 HTML 블록 주변의 진정으로 모호한 CommonMark 코너 케이스 몇 가지. 이에 대해 CommonMark 적합성 제품군을 실행하고 있다면 100%의 점수를 얻지 못할 것입니다. README,changelog 또는 블로그 게시물을 변환하는 경우 눈치 채지 못할 것입니다.
그것은 정직한 거래이며,컨버터가 즉시 로드되고 네트워크 오프와 함께 작동하는 이유입니다. 비트-정확한 CommonMark 적합성이 필요한 콘텐츠 파이프라인의 경우 다음을 사용하십시오 markdown-it, remark 또는 cmark 당신의 빌드에서; 그것이 바로 그들이 하는 목적입니다.
자주 묻는 질문
마크다운을 HTML로 어떻게 변환합니까?
편집기에 마크다운을 붙여넣으면 HTML 이 즉시 나타납니다 - 변환 버튼도 없고 업로드할 파일도 없습니다. 소스가 테이블이나 작업 목록을 사용하는 경우 GitHub Flavored Markdown 을 켠 다음 HTML 을 복사하거나.html 파일로 다운로드하십시오. 모든 것이 브라우저에서 실행되므로 게시되지 않은 초안과 내부 문서는 장치를 떠나지 않습니다.
GitHub 맛 마크다운이란 무엇입니까?
GitHub Flavored Markdown (GFM) 은 공식적으로 지정된 CommonMark 의 수퍼세트로 테이블,작업 목록 체크박스,이중 물결표로 취소선,그리고 베어 URL 의 자동 연결을 추가합니다. 이는 GitHub 가 README 파일과 이슈를 렌더링하는 데 사용하는 방언이며,오늘날 대부분의 Markdown 편집기가 내보내는 변환기에서 기본적으로 활성화됩니다.
내 단일 줄 바꿈이 사라진 이유는 무엇입니까?
Standard Markdown 은 연속된 줄을 하나의 단락으로 조인합니다; 줄 바꿈은 두 칸으로 줄을 끝내거나,뒤로 오는 백슬래시를 사용하거나,빈 줄을 남겨둘 경우에만 살아남습니다. 모든 개행이 a 가 되기를 원한다면 <br />줄 바꿈 옵션을 활성화합니다. 이는 GitHub 댓글과 대부분의 채팅 앱이 사용하는 동작이지만 README 파일이 수행하는 동작은 아닙니다.
변환기가 내 코드를 강조 표시합니까?
형광펜이 필요로 하는 마크업을 내보내지만 코드 자체에 색을 입히지는 않습니다. 언어로 태그된 울타리가 있는 코드 블록 js 된다 <pre><code class="language-js">클래스 규칙인 Prism 인 highlight.js 와 Shiki 가 모두 찾습니다. 출력을 붙여넣으면 강조 표시가 자동으로 나타나는 페이지에 해당 라이브러리 중 하나를 추가합니다.
내 마크다운 안에 원시 HTML이 보존되어 있습니까?
기본적으로 이스케이프됩니다 <div> 태그가 아닌 리터럴 텍스트로 나타납니다. 태그를 바로 통과시키기 위해 allow-raw-HTML 옵션을 켜세요. 이것은 Markdown 이 HTML 에서 의도적으로 믹스할 때 원하는 것입니다 - a <details> 블록,또는 속성이 있는 이미지. 신뢰할 수 없는 작성자의 원시 HTML 은 XSS 벡터이기 때문에 신뢰할 수 있는 소스에 대해서만 활성화합니다.
내가 쓰지 않은 마크다운을 붙여넣는 것이 안전합니까?
예. HTML 은 기본적으로 이스케이프되며 라이브 미리보기는 렌더링 전에 스크립트 및 스타일 태그,인라인 이벤트 핸들러 및 javascript: URL 을 추가로 제거합니다. 붙여 넣기 한 것은 아무데도 전송되지 않습니다. 낯선 사람으로부터 Markdown 을 렌더링하는 제품을 만드는 경우 여전히 DOMPurify 서버 측과 같은 전용 소독제를 사용하십시오 - 미리보기 필터는 하나를 대체하지 않습니다.
내 제목에서 목차를 생성할 수 있습니까?
예. 제목 ID 를 사용하도록 설정한 상태에서 모든 제목에 슬러그 처리된 중복 제거된 앵커가 생기고 도구는 각 제목에 연결되는 Markdown 목차를 구축합니다. 문서 상단에 다시 복사하면 생성된 ID 에 대해 링크가 해결됩니다. 손으로 머릿글을 유지하는 대신 제목이 변경될 때마다 다시 생성합니다.
이 변환기는 CommonMark 를 완전히 구현합니까?
사람들이 실제로 쓰는 구성을 구현합니다 - ATX 및 setext 제목,문단, 강조,링크, 이미지,자동 링크,블록 인용,중첩 및 느슨한 목록,울타리 및 들여쓰기 코드,주제별 나누기,백슬래시 이스케이프 - 플러스 GFM 확장 참조 스타일 링크,각주 및 몇 가지 드문 CommonMark HTML-블록 가장자리 케이스는 다루지 않습니다. 빌드 파이프라인에서 비트 정확한 적합성을 위해 markdown-it,remark 또는 cmark 를 사용하십시오.
관련 도구: 마크다운에서 HTML로 · HTML 엔터티 · HTML 미니파이어 · 워드 카운터 · 슬러그 생성기
관련 읽기: 웹 개발자's 툴킷 · 텍스트 도구 가이드
