MDN to markdown conversion

Yari 이전에는 MDN 문서는 WYSIWYG 편집기에서 편집되었으며, 페이지를 HTML로만 편집할 수 있는 옵션이 있었습니다. Yari 이후로는 MDN 문서를 텍스트 편집기에서 HTML로만 편집할 수 있습니다.

 

현재 이 방식은 느리고 더 어려우며 더 많은 형식 오류가 발생합니다. 또한, 작성자는 표현하려는 개념 대신 항상 형식에 대해 생각해야 해서 문서의 질 또한 좋지 못합니다. HTML에 익숙하지 않은 사람들은 전혀 기여하지 못할 수도 있습니다.

 

마지막으로, 검토하는 데에도 많은 어려움들이 있습니다.

 

이에 대한 해결책으로 MDN 문서를 Markdown으로 마이그레이션하는 제안이 나왔습니다. (링크)

---

먼저, mdn/content에서 MDN 문서를 HTML이 아닌 Markdown을 사용하기 위한 프로젝트를 진행했습니다. 프로젝트의 첫 번째 목표로 JavaScript 문서(/en-US/docs/Web/JavaScript/에 있는 모든 것)를 변환합니다. 이에 대한 주요 프로젝트 Issue는 다음 링크와 같습니다. 아래는 [Markdown] Migrate one section of the MDN docs to Markdown 에 대한 요약 내용입니다. 원활한 이해를 위해, 원문과 일부 차이가 있습니다. 세부 사항은 원문을 참고해주세요.

 

다음 원문 작업에서는 몇 가지 다른 단계의 목표가 있습니다.

1. 어떤 Markdown을 사용할지, 그리고 그것을 필요한 곳으로 확장하는 방법을 알아냅니다.
2. Markdown과 호환되도록 콘텐츠 업데이트합니다.
3. HTML을 Markdown으로 변환하는 도구 구현합니다.
4. 이 Markdown을 HTML로 렌더링 할 수 있도록 Yari를 업데이트하고, 다른 도구들은 계속 작동하게 합니다.

Specifying MDN to Markdown conversion

이 문서는 MDN의 HTML 콘텐츠를 Markdown으로 변환하는 방법을 설명합니다. 변환하는 것이 우리의 즉각적인 목표이기 때문에 JavaScript 문서( https://developer.mozilla.org/en-US/docs/Web/JavaScript )에 중점을 두고 있습니다. 그러나 향후 더 많은 문서 세트를 변환하는 데 유용해야 합니다.

 

다음을 나열하여 변환에 대한 체계적인 접근을 시도합니다.

• 모든 HTML 요소
• 모든 HTML 속성
• class 속성의 모든 값

변환 프로세스가 해당 항목을 볼 때 수행해야 하는 작업을 결정합니다.

 

전체 세부 정보는 다음 Google 시트에 있습니다.

https://docs.google.com/spreadsheets/d/1Nb-WUHveeUfi5YV0-pzVyHI1vR1IC8xF40IdkiceyQQ/edit#gid=0

 

Google 시트에는 elements, attributes, class, TRIAGE에 대한 페이지가 있습니다. 또한, 각 페이지에는 4개의 열이 있습니다.

 

• Name: 해당 element/attribute/class의 이름
• Conversion: 해당 element/attribute/class를 만났을 때,  변환 프로세스가 수행해야 하는 작업
• In JS docs?: 해당 element/attribute/class가 JS 문서에서 발생하는지 여부
• Issue: 해당 항목에 대해 수행할 작업을 논의하는 GitHub Issue에 대한 링크

 

Generic conversion categories

아래는 Google 시트의 Conversion 열에 대한 세부 사항들입니다.

• GFM: GitHub-Flavored Markdown (GFM)을 대표하는 카테고리입니다. 다음과 같은 태그들을 지원합니다. <p>, <li>, <img src=...>, <pre class="js"> 등. avocado 색으로 하이라이트 표시되어 있습니다.
• Error: 이 항목이 표시되면 콘텐츠가 아직 변환할 준비가 되지 않았음을 의미합니다. 이 항목이 더 이상 소스에 표시되지 않도록 사람들이 콘텐츠를 수정해야 합니다. 따라서, 변환 프로세스는 오류를 기록해야 하며 이를 해결해야 합니다.
  • Markdown 소스에서 이 항목을 지원하고 싶지 않을 때 이 범주를 선택해야 하지만 콘텐츠가 손상될 수 있으므로 자동으로 제거할 수 없습니다. style 속성은 좋은 예입니다.
• Strip tags/strip attribute: 이것은 태그/속성을 버리고 태그의 내용을 유지한다는 의미입니다.
  • 예를 들어 <span>속성이 없는 요소는 변환된 마크업에서 캡처하려는 항목을 추가하지 않습니다. 때때로 이러한 선택은 마크업에서 의미 체계를 제거합니다. 예를 들어, 시트에서 <abbr> 태그를 버릴 것을 권장합니다. 따라서, 이 선택을 한다는 것은 손실을 받아들인다는 의미입니다.
  • 종종 이 선택과 "오류" 사이에서 선택하기가 어렵습니다. 태그를 자동으로 제거하는 것보다 태그에 대해 수행할 작업을 결정하기 위해 수동으로 변경해야 하는지 여부는 판단의 문제입니다.
• Keep original:  즉, 소스를 변환하지 않고 태그와 해당 내용을 있는 그대로 전송합니다.
  • 원래 기능을 유지하고 싶지만 Markdown에서 이를 표현할 합리적인 방법이 없을 때 이것을 선택해야 합니다. MathML과 SVG가 좋은 예입니다.
• GFM XYZ: 다음을 의미합니다: 이것을 GFM 표현이 있는 다른 관련 요소 XYZ로 처리하고, 관련 요소의 GFM 표현을 내보냅니다.
  • "GFM"과 비교하면 일반적으로 일부 의미 체계를 버리기 때문에 이것은 약간 엉뚱합니다. 그러나 어쨌든 이러한 의미론을 대상 형식으로 나타낼 방법이 없으므로 더 나은 옵션이 없습니다.
  • <dfn> 같은 것들이 이에 대한 예입니다: 우리는 <em>의 GFM 구문을 사용하도록 선택할 수 있는데, 브라우저가 일반적으로 <dfn>을 렌더링 하는 방식과 일치하기 때문입니다. 그러나 우리는 단어의 의미를 잃습니다.
  • 특히 속성의 경우, 요소가 무엇인지에 따라 해상도가 다르기 때문에 때때로 이들을 결합합니다. 예를 들어, src는 <img>에 첨부될 때 GFM으로 변환될 수 있지만 그렇지 않으면 오류입니다.

Custom conversion categories

Note/warning/callout

 

요소에 class="note"가 있는 경우:

• <div> 요소가 존재한다.
• 첫 번째 자식 요소가 <p>이다.
• <p> 요소의 첫 번째 자식 요소가 <strong>이다.
• <strong>의 textContent가 "Note:"이다.
• 위 조건을 모두 만족하면 https://developer.mozilla.org/en-US/docs/MDN/Contribute/Markdown_in_MDN#notes_warnings_and_callouts 에 지정된 대로 Markdown의 note로 변환한다.
• 이외의 경우 error를 출력한다.

요소에 class="warning"가 있는 경우:

• <div> 요소가 존재한다.
• 첫 번째 자식 요소가 <p>이다.
• <p> 요소의 첫 번째 자식 요소가 <strong>이다.
• <strong>의 textContent가 "Warning:"이다.
• 위 조건을 모두 만족하면 https://developer.mozilla.org/en-US/docs/MDN/Contribute/Markdown_in_MDN#notes_warnings_and_callouts 에 지정된 대로 Markdown의 note로 변환한다.
• 이외의 경우 error를 출력한다.

요소에 class="callout"가 있는 경우:

• <div> 요소가 존재한다.
• 위 조건을 모두 만족하면 https://developer.mozilla.org/en-US/docs/MDN/Contribute/Markdown_in_MDN#notes_warnings_and_callouts 에 지정된 대로 Markdown의 note로 변환한다.
• 이외의 경우 error를 출력한다.

한국 지역의 경우에는 아래 형식을 따릅니다. (참고 링크)

 

• note: => 참고:
• warning: => 경고:
• callout: => 알림:

 

Tables

테이블에 대한 간략한 이야기는 다음과 같습니다. GFM 테이블 구문을 사용하여 표현할 수 있으면 사용하고, 그렇지 못하면 HTML을 사용합니다( https://developer.mozilla.org/en-US/docs/MDN/Contribute/Markdown_in_MDN#tables ).

 

변환기의 경우, 테이블에 GFM으로 표시되는 것을 방해하는 요소가 포함되어 있으면 변환하지 않고, 다른 경우는 GFM으로 변환합니다.

 

GFM에 표시되지 않는 기능은 다음과 같습니다.

• header가 없는 tables
• 열의 header가 있는 tables
• 블록 요소를 포함하는 table cells
• <table>, <tr>, and <th>, and <td> 외의 요소를 사용하는 tables
• colspan, rowspan 또는 scope과 같은 table 속성을 이용하는 tables

한 가지 예외는 <caption>입니다. 테이블에 caption 이 있다는 점만 제외하고, GFM으로 변환할 수 있는 경우, caption 요소를 제거할 수 있습니다.

 

Hidden class

 

요소에 class="hidden"가 있는 경우:

• ID가 있는 div이고 코드 블록을 포함하는 경우
  • 코드 블록만 포함하는 경우, "hidden" class를 코드 블록으로 전송하고, 외부 div 요소를 버립니다(그러나 코드 블록은 유지).
  • 그렇지 않으면 오류가 발생합니다. 이것은 변환할 수 없는 구조이며, 사람이 수동으로 정렬해야 합니다.
• 그렇지 않으면 요소와 그 내용을 버립니다.

이에 대한 근거는 class="hidden"이 두 가지 컨텍스트에서 사용되기를 기대하기 때문입니다:

• 숨겨진 산문으로, 오래된 Wiki에서 편집자에게 지침을 나타냄
• 라이브 샘플의 일부를 숨기지만 여전히 라이브 샘플 시스템에 액세스 할 수 있도록 하는 방법

첫 번째 경우에는 숨겨진 산문을 제거하기만 하면 됩니다.

두 번째 경우 hidden에는 블록의 정보 문자열에 있는 속성을 통해 라이브 샘플 시스템에서 코드 블록을 숨길 수 있습니다. 그러나 사람들이 제목과 같이 라이브 샘플에 참여할 수 있는 다른 요소를 숨기고 있다면 콘텐츠를 안정적으로 변환할 수 있도록 업데이트해야 할 수 있습니다.

 

summary/seoSummary

 

summary와 seoSummary 클래스일 경우:

• summary 또는 seoSummary집합이 있는 요소의 텍스트 내용이 문서의 첫 번째 산문 단락의 텍스트 내용과 일치하면 클래스를 제거합니다.
• 그렇지 않으면 오류 발생

한 가지 복잡한 것은 "첫 번째 산문 단락"입니다. 많은 문서는 다음과 같이 매크로 호출만 포함하는 요소로 시작합니다.

<div>{{CSSRef}}</div>

일반적으로 이것은 <div>이지만 때때로 사람들이 <p>를 사용했습니다. 따라서 변환기는 "{{ 로 시작하지 않는 첫 번째 단락 요소"와 같은 경험적인 방법을 사용해야 합니다.

 

Description lists

우리는 우리의 고유한 문법인 <ul> 기반의 문법인 <dl>을 만들었습니다. https://developer.mozilla.org/en-US/docs/MDN/Contribute/Markdown_in_MDN#definition_lists, 다음 이슈도 같이 보세요 #4367.

 

이것은 HTML <dl> 보다 <dt>와 <dd>의 쌍만 포함하길 기대한다는 점에서 더 제한적입니다. 그래서:

• <dl>에 연속적으로 <dt>또는 <dd> 요소가 포함되어 있으면 오류가 발생합니다.
• 그렇지 않으면 https://developer.mozilla.org/en-US/docs/MDN/Contribute/Markdown_in_MDN 에 정의된 사용자 정의 구문으로 변환하세요.

Unresolved elements/attributes/class values

모든 카테고리들이 선택되어 있지는 않습니다. 이것은 우리가 그들에 대해 무엇을 해야 할지 아직 확신하지 못한다는 것을 의미합니다. 이러한 모든 항목에는 항목으로 수행할 작업을 해결할 수 있는 GitHub 문제에 대한 링크가 있어야 합니다.

 

문제가 합의에 도달하면 해당 항목에 범주를 할당하고 문제를 종료할 수 있습니다. 물론 해결책은 새로운 카테고리를 만드는 것일 수 있습니다. 예를 들어 <dl>.

 

현재 다음 항목 그룹이 해결되지 않았습니다.

 

• classes
  • fullwidth-table, standard-table: 아직 이슈 트래킹이 안됨

여기에서 모든 항목이 해결되면 소스를 Markdown으로 변환하기 위한 완전한 계획이 있습니다.

실용적인 문제로 이제 JS 문서에 나타나는 항목에 대한 해결 방법만 있으면 됩니다.

---

우리는 다음 명령어를 통해서 변환을 진행할 수 있습니다. (관련 이슈)

yarn md h2m web/javascript --locale en-US --mode replace

 

yarn run md h2m my/path/directory --locale mylocale --mode dry

한국 locale의 경우 변환이 제대로 이뤄지지 않는 경우가 많다. 따라서 html 파일과 비교하기 위해 keep option을 쓰는 명령어를 추천한다. 

yarn md h2m web/javascript/path --locale ko --mode keep

---

Markdown을 작성하는 방법을 설명하는 주요 문서는 https://developer.mozilla.org/en-US/docs/MDN/Contribute/Markdown_in_MDN 입니다. 이것은 GitHub Flavored Markdown 의 기준들과 GFM에서 지원되지 않는 몇 가지 필요한 확장(예: <dl>)을 설명합니다.