마크다운 포매터가 하는 일
마크다운은 너그럽습니다. 글머리 기호는 -, *, + 중 무엇으로든, 강조는 *나 _로, 제목은 등호 줄이나 #으로 쓸 수 있습니다. 입력할 때는 이 자유로움이 편하지만, 여러 사람이 고친 파일에는 금세 온갖 스타일이 섞입니다. 표의 칸이 어긋나고, 빈 줄이 빠지고, diff가 지저분해집니다. 마크다운 포매터는 이런 파일을 한 번에 정리해 줍니다.
이 포매터는 소스를 하나의 일관된 스타일로 다시 씁니다. 대부분의 JavaScript 프로젝트가 문서 정리에 이미 쓰고 있는 Prettier를 기반으로 하므로, VS Code나 명령줄에서 Prettier를 돌린 결과와 같습니다.
사용 방법
- 왼쪽 상자에 마크다운을 붙여넣거나, 파일 열기를 눌러
.md파일을 불러옵니다. 붙여넣으면 바로 정렬됩니다. - 먼저 예제를 보고 싶다면 예시를 누릅니다.
- 들여쓰기, 줄 너비, 텍스트 줄바꿈 방식을 고릅니다. 줄바꿈 방식은 그대로 유지, 줄 너비에서 줄바꿈, 문단당 한 줄 중 하나입니다.
- 설정을 바꾼 뒤 다시 실행하려면 포맷(또는 Ctrl과 Enter)을 누릅니다.
- 복사나 다운로드로 결과를 가져갑니다. 지우기를 누르면 입력이 비워집니다.
한 번 포맷한 뒤에는 입력하는 대로 결과가 따라 바뀝니다.
정렬 전과 후
여러 스타일이 섞인 짧은 파일입니다.
Project Notes
=============
* Install the tools
* Run the build
+ Deploy
|Name|Role|
|-|-|
|Ada|Admin|
|Linus|Editor|
Some *emphasis* and __bold__ text.포매터는 다음 결과를 돌려줍니다.
Project Notes
=============
- Install the tools
- Run the build
* Deploy
| Name | Role |
| ----- | ------ |
| Ada | Admin |
| Linus | Editor |
Some _emphasis_ and **bold** text.몇 가지가 바뀌었습니다. 제목 다음에 빈 줄이 생겼습니다. 첫 번째 목록은 -를 씁니다. 굵게는 **, 기울임은 _를 씁니다. 표의 열은 일반 텍스트로 봐도 줄이 맞도록 공백으로 채워졌습니다. “Deploy”가 따로 떨어져 있다는 점도 보세요. 다른 글머리 기호를 썼기 때문에 마크다운은 이를 두 번째 목록으로 취급하며, 포매터는 다른 기호를 붙여 그 의미를 지킵니다.
긴 문단 줄바꿈
텍스트 줄바꿈을 줄 너비에서 줄바꿈으로, 줄 너비를 60으로 설정하면 다음 문단은
Markdown files are easier to review when each paragraph follows the same rule for line length, because a diff then shows only the sentence that changed.이렇게 바뀝니다.
Markdown files are easier to review when each paragraph
follows the same rule for line length, because a diff then
shows only the sentence that changed.문단당 한 줄은 반대로 동작해 줄바꿈된 줄을 다시 한 줄로 합칩니다. 팀에서 어떤 방식을 쓰는지 모를 때는 그대로 유지가 안전한 기본값입니다.
건드리지 않는 것
포매터는 배치를 바꿀 뿐 의미는 바꾸지 않습니다. 일부러 손대지 않는 것들은 다음과 같습니다.
- 코드 블록. 펜스 코드 블록 안의 코드는 작성한 그대로 남습니다.
const a={b:1}이 들어 있는js블록도 다시 정렬되지 않습니다. 그런 코드는 자바스크립트 포매터를 쓰세요. - 번호 목록. 모든 항목이
1.로 시작하면 모든 줄에1.을 유지합니다. 1, 2, 3으로 번호를 매겼다면 그대로 둡니다. - 올바른 문법이 아닌 텍스트. 공백 없는
#Title은 CommonMark에서 제목이 아니므로 일반 문단으로 남습니다. 공백을 넣으면 제목이 됩니다. - 인라인 HTML. 마크다운 안의 HTML 태그는 그대로 유지됩니다.
팁
- 커밋하기 전에 포맷하세요. 파일이 일관되면 풀 리퀘스트의 diff에는 실제 수정 사항만 나타납니다.
- 저장소 전체에 줄바꿈 규칙을 하나만 정하세요. 줄바꿈된 파일과 그렇지 않은 파일이 섞여 있으면 누군가 처음 포맷할 때 diff가 크게 생깁니다.
- 표를 손으로 만드는 것은 느립니다. 마크다운 표 만들기 도구는 칸에 바로 입력할 수 있는 그리드를 제공하고 스프레드시트에서 붙여넣기도 받습니다.
- 웹 페이지나 워드 파일을 마크다운으로 옮겨야 한다면 HTML 마크다운 변환기나 워드 마크다운 변환기를 쓴 뒤 여기서 결과를 정리하세요.
마크다운을 정렬하는 다른 방법
- VS Code: Prettier 확장을 설치하고
.md파일을 연 다음 Format Document(문서 서식)를 실행합니다. 결과는 이 페이지와 같습니다. - 명령줄:
npx prettier --write README.md는 파일을 그 자리에서 정렬합니다. 문단을 줄바꿈하려면--prose-wrap always를 덧붙입니다. - 린트: markdownlint는 제목 단계나 줄 길이 같은 스타일 규칙을 검사합니다. 린터는 문제를 알려 주고, 포매터는 배치를 대신 고쳐 줍니다. 둘 다 쓰는 프로젝트가 많습니다.
한계
포매터는 CommonMark에 표, 작업 목록 같은 GitHub 확장을 더한 규칙을 따릅니다. 커스텀 컨테이너나 위키 링크처럼 다른 도구의 확장 문법은 일반 텍스트로 취급되므로, 그 도구가 기대하는 것과 공백이 다르게 정리될 수 있습니다. 파일 맨 위의 프런트 매터(두 --- 줄 사이의 블록)는 유지됩니다. 아주 큰 파일도 처리할 수 있지만 모든 작업이 기기에서 이루어지므로 시간이 더 걸립니다.