마크다운 문법으로 MD 파일을 작성하고, 실시간으로 렌더링 결과를 확인하는 모습을 표현한 대표 이미지입니다.
MD 파일 작성하는 법, 마크다운 문법 완전 정리
한눈에 보는 요약
이 글은 마크다운(Markdown) 문법으로 MD 파일을 작성하는 방법을 초보자부터 실무자까지 단계별로 정리한 가이드입니다. 제목, 목록, 링크, 이미지와 같은 기본 문법부터 코드, 표, 확장 문법까지 실제 업무에서 자주 쓰는 요소를 모두 다룹니다.
GitHub, GitLab, Azure DevOps 등 대부분의 개발 플랫폼은 공통적인 마크다운 규칙을 따르며, 약간의 확장 문법만 다를 뿐입니다. 따라서 핵심 규칙만 이해하면 어떤 플랫폼에서도 큰 수정 없이 활용할 수 있습니다.
실무에서는 “보기 좋은 문서”를 만드는 것뿐 아니라, 버전 관리와 협업, 리뷰에 적합한 구조를 설계하는 것이 중요합니다. 이 글에서는 문법 설명과 함께 폴더 구조, 파일 네이밍, 코드 블록 스타일 등 실무 팁도 함께 제시합니다.
마지막에는 실전에서 바로 쓸 수 있는 MD 템플릿, 체크리스트, 그리고 블로그 SEO에 도움이 되는 태그와 이미지 프롬프트 예시까지 포함해, 한 번 저장해 두고 계속 참고할 수 있는 레퍼런스를 목표로 합니다.
목차
- 1. 핵심 포인트
- 2. MD 파일과 마크다운 기본 개념
- 3. 기본 문법: 제목·본문·목록·강조
- 4. 링크, 이미지, 인용문 작성법
- 5. 코드와 표 작성 실전 예시
- 6. 실무에서 많이 쓰는 확장 문법
- 7. 실무형 MD 작성 워크플로우
- 8. 따라하기: 첫 MD 파일 작성 단계
- 9. 추가로 생각해볼 점
- 10. 블로그 최적화 정보
핵심 포인트
- MD 파일은 단순한 텍스트 파일이며, 마크다운 문법으로 작성하면 HTML로 쉽게 변환되고 대부분의 개발 플랫폼에서 바로 렌더링됩니다.
- 기본 문법은 제목(#), 강조(*, **), 목록(-, 1.), 링크([텍스트](URL)), 이미지(![]()) 정도만 익혀도 실무 문서의 80%를 작성할 수 있습니다.
- 코드 블록, 표, 체크박스(Task list)와 같은 확장 문법을 활용하면 기술 문서, 설계서, 이슈 템플릿 등 구조화된 문서를 수월하게 만들 수 있습니다.
- 팀 단위로 사용할 때는 제목 체계, 파일 이름, 목차 구조를 통일해 두어야 문서 탐색이 쉬워지고 리뷰 품질도 높아집니다.
- 프리뷰 기능이 있는 에디터(VS Code, Typora, Obsidian 등)를 활용하면 문법을 바로 확인하면서 작성할 수 있어, 초보자도 실수 없이 MD 파일을 만들 수 있습니다.
상세 설명
1. MD 파일과 마크다운 기본 개념
MD 파일은 확장자가 .md인 텍스트 파일로, 내용 자체는 일반 텍스트이지만 마크다운 문법을 사용해 구조와 서식을 표현합니다. 예를 들어 # 제목은 HTML의 <h1>, - 목록은 <ul> 태그로 변환되는 식입니다.
장점은 다음과 같습니다. 첫째, 사람 눈으로 읽기 쉬운 문서를 만들 수 있습니다. 문법 자체가 “보이는 그대로”를 의도했기 때문에, 렌더링하지 않아도 대략적인 구조를 이해할 수 있습니다. 둘째, 순수 텍스트이므로 Git과 같은 버전 관리 도구로 diff를 확인하기에 적합합니다. 셋째, 다양한 도구에서 HTML, PDF 등으로 변환할 수 있어 재사용성이 높습니다.
각 플랫폼은 공통적인 “CommonMark” 또는 그 변형을 사용하고, GitHub Flavored Markdown(GFM), GitLab Flavored Markdown(GLFM)처럼 자체 확장을 추가하기도 합니다. 기본 문법은 거의 동일하니, 먼저 공통 문법을 익히고 필요할 때 플랫폼 확장 문법을 추가로 학습하는 방식을 추천드립니다.
2. 기본 문법: 제목·본문·목록·강조
가장 먼저 익혀야 할 기본 문법은 다음 네 가지입니다.
2-1. 제목(Heading)
제목은 # 기호로 레벨을 표시합니다. # 한 개는 최상위 제목(h1), 여섯 개까지 사용할 수 있습니다.
# 문서 제목(H1)
## 섹션 제목(H2)
### 하위 섹션 제목(H3)
실무에서는 보통 문서 안에서 #는 한 번만 사용해 전체 문서의 제목을 표시하고, 내용 구분에는 ##, ### 정도까지만 사용하는 것을 권장합니다. 이렇게 해야 목차 구조가 명확해지고, 화면 판독기 등 접근성 측면에서도 유리합니다.
2-2. 본문과 줄바꿈
일반 텍스트는 그대로 입력하면 단락(문단)이 됩니다. 문단 사이에 한 줄을 비워 두면 새로운 단락으로 인식됩니다. 한 문단 안에서 줄바꿈만 하고 싶다면 줄 끝에 공백 두 칸을 넣거나, HTML의 <br> 태그를 사용할 수 있습니다.
2-3. 목록(List)
순서 없는 목록은 -, *, + 중 아무 기호나 사용할 수 있고, 순서 있는 목록은 숫자와 점(1.)을 사용합니다.
- 항목 1
- 항목 2
- 하위 항목 A
- 하위 항목 B
1. 첫 번째 단계
2. 두 번째 단계
3. 세 번째 단계
하위 목록을 만들 때는 두 칸 또는 네 칸 정도 들여쓰기(스페이스)를 추가하면 됩니다. 팀 규칙에 따라 들여쓰기 폭을 통일해 두면 렌더링 결과와 diff 모두 보기 편해집니다.
2-4. 텍스트 강조(Emphasis)
기본 강조는 * 또는 _ 기호로 감싸서 표현합니다.
*기울임*또는_기울임_→ 이탤릭(italic)**굵게**또는__굵게__→ 굵게(bold)***굵게 기울임***→ 굵게+기울임
한글 문장에서는 기호 앞뒤로 공백을 둘지 말지 팀 기준을 정해 두는 것도 좋습니다. 예: “**중요:** 다음과 같은 규칙을 지킵니다.”와 같이 접두사 형식으로 사용하면 가독성이 높아집니다.
3. 링크, 이미지, 인용문 작성법
3-1. 링크(Link)
링크는 대괄호와 괄호 조합으로 작성합니다: [텍스트](URL). 선택적으로 제목을 덧붙일 수 있습니다.
[GitHub](https://github.com "소스 코드 호스팅 플랫폼")
[Markdown Guide](https://www.markdownguide.org)
내부 문서의 특정 섹션으로 이동하는 앵커 링크는 [섹션 제목](#section-id) 형식으로 사용합니다. 이 글의 목차처럼, 제목에 id를 부여하고 내부 링크를 걸면 긴 문서를 탐색하기가 훨씬 수월해집니다.
3-2. 이미지(Image)
이미지는 링크 문법 앞에 !를 붙이면 됩니다: . 대체 텍스트(alt)는 시각장애인 보조기기와 검색엔진에 중요한 정보이므로, 이미지 의미를 간단히 설명하는 문장을 넣어주는 습관을 들이시는 것이 좋습니다.
3-3. 인용문(Blockquote)
인용문은 줄 앞에 > 기호를 붙여 작성합니다.
> 이 문장은 인용문입니다.
>
> 여러 줄 인용문도 가능합니다.
> > 안쪽에 또 다른 인용을 중첩할 수도 있습니다.
주요 개념 정리, 주의사항, 참고 링크 등을 강조할 때 인용문을 활용하면 문서의 리듬을 살릴 수 있습니다.
4. 코드와 표 작성 실전 예시
4-1. 인라인 코드와 코드 블록
코드나 명령어를 보여줄 때는 백틱(`)을 사용합니다. 한 줄 안에 짧게 들어가는 코드는 `인라인 코드`로, 여러 줄 코드는 백틱 세 개 또는 물결 세 개로 감싸 “코드 블록”을 만들 수 있습니다.
`npm install` 명령으로 패키지를 설치합니다.
```bash
# 패키지 설치
npm install
# 개발 서버 실행
npm run dev
```
첫 번째 백틱 세 개 옆에 언어 이름을 적어주면(GitHub, GitLab 등) 해당 언어에 맞는 하이라이팅이 적용됩니다. 예: ```bash, ```python, ```json 등.
4-2. 표(Table) 작성
기본 마크다운 표는 파이프(|)와 하이픈(-)으로 구성합니다. 렌더링 결과는 아래 HTML 표와 비슷한 구조가 됩니다.
| 문법 요소 | 예시 | 설명 |
| -------- | ---- | ---- |
| 제목 | # 제목 | H1~H6 제목 작성 |
| 목록 | - 항목 | 순서 없는 리스트 |
| 링크 | [텍스트](URL) | 하이퍼링크 |
| 코드 블록 | ```bash ... ``` | 다중 라인 코드 |
실제 HTML로 변환되면 대략 다음과 같은 구조가 됩니다.
마크다운 문법 요약 표
아래 표는 기본 마크다운 문법 요소와 대표 예시를 정리한 것입니다.
| 분류 | 문법 | 예시 | 주요 용도 |
|---|---|---|---|
| 제목 | # 기호 1~6개 |
## 기능 소개 |
문서 구조를 나누는 섹션 헤더 |
| 목록 | -, *, 숫자+점 |
1. 단계, - 항목 |
절차, 항목, 체크리스트 표현 |
| 강조 | *텍스트*, **텍스트** |
**중요** 안내 |
주의 메시지, 키워드 강조 |
| 링크 | [텍스트](URL) |
[문법 가이드](https://www.markdownguide.org) |
외부/내부 문서 연결 |
| 코드 | `인라인`, ```언어``` |
```bash npm run build``` |
명령어, 코드 스니펫 공유 |
5. 실무에서 많이 쓰는 확장 문법
GitHub, GitLab, Azure DevOps 등은 공통 마크다운 위에 몇 가지 확장 문법을 제공합니다. 모든 플랫폼에서 동일하게 동작하지는 않으므로, 프로젝트에서 사용하는 도구 기준으로 동작 여부를 확인하시기 바랍니다.
- Task List:
- [ ] 할 일,- [x] 완료된 일 - 코드 하이라이팅:
```언어명뒤에 언어 지정 - 테이블 확장: 정렬(
:---,:---:,---:) 지원 - 각주(Footnote):
문장[^1]/[^1]: 각주 내용형식 - 수식:
$...$또는$$...$$(플랫폼에 따라 지원 여부 상이)
문서를 장기간 유지보수해야 하는 팀이라면, “공식적으로 사용하는 확장 문법 목록”을 정해 두고 예시와 함께 팀 위키에 올려두면 혼선을 줄일 수 있습니다.
6. 실무형 MD 작성 워크플로우
실무에서는 마크다운 문법 자체보다 “어떻게 구성하고 관리하느냐”가 더 중요합니다. 다음과 같은 관점에서 워크플로우를 설계해 보시기 바랍니다.
- 에디터 선택: VS Code(확장: Markdown All in One), Typora, Obsidian 등 프리뷰 기능이 있는 에디터를 기본 도구로 사용합니다.
- 폴더 구조:
docs/아래에 주제별 디렉터리를 만들고,README.md를 각 디렉터리의 인덱스 문서로 사용하는 패턴이 일반적입니다. - 파일 네이밍: 공백 대신
-또는_를 사용하고, 영어와 날짜를 조합해 규칙적으로 관리하면 URL, 링크 관리가 용이합니다. 예:api-design-guidelines.md,2025-01-release-notes.md. - PR 기반 리뷰: MD 파일도 코드와 동일하게 Pull Request로 리뷰를 요청하고, 오타·구조·내용을 함께 검토합니다.
- 린트 & 포맷터: 대규모 프로젝트에서는 Markdownlint 같은 도구로 제목 레벨, 리스트 포맷 등을 자동으로 점검하는 것도 좋은 방법입니다.
실행 단계
- 목적 정의하기 – 먼저 작성하려는 MD 파일의 목적을 한 줄로 정의합니다. 예: “신규 API 설계서 초안”, “팀 온보딩 가이드” 등. 목적을 정의해 두면 어떤 섹션이 필요한지, 어느 정도 깊이로 쓸지 결정하기가 쉬워집니다.
- 기본 골격 만들기 – 에디터를 열고 문서 제목과 상위 섹션을 먼저 작성합니다.
# 문서 제목,## 배경,## 요구사항,## 설계,## 참고 자료처럼 큰 틀부터 잡은 후 내용을 채워 넣습니다. - 목차와 링크 설계하기 – 장이 길어질 것 같다면 상단에 목차 섹션을 만들고, 나중에 HTML로 변환할 경우를 고려해 각 제목에 고유한 id 또는 영어 제목을 사용할지 미리 정해 둡니다.
- 본문과 예시 채우기 – 개념 설명에는 문단과 목록을, 실제 사용 방법에는 코드 블록과 표를 적극 활용해 읽기 흐름을 만듭니다. 예시 코드를 포함하면 리뷰어나 후속 독자가 이해하기 훨씬 편합니다.
- 프리뷰로 문법 검증하기 – 에디터 또는 플랫폼의 프리뷰 기능을 활용해 제목 레벨, 목록 들여쓰기, 링크·이미지가 모두 정상적으로 동작하는지 확인합니다. 깨지는 부분이 있다면 공백, 들여쓰기, 백틱 개수 등을 우선적으로 점검합니다.
- 버전 관리 및 공유 – 최종본은 Git 저장소나 위키에 커밋하고, Pull Request 또는 링크를 통해 팀에 공유합니다. 주요 변경 이력은 커밋 메시지나 ChangeLog 섹션으로 남겨 두면 좋습니다.
추가로 생각해볼 점
- 팀 차원에서 “마크다운 스타일 가이드”를 만들면, 누구나 같은 규칙으로 문서를 작성할 수 있어 유지보수 비용이 크게 줄어듭니다.
- 도메인 지식이 많은 사람일수록 문법보다는 “정보 구조화”에 신경 쓰기 어렵습니다. 정기적으로 문서 구조만 리뷰하는 시간을 따로 두는 것도 좋은 방법입니다.
- 장기 보관이 필요한 문서는 최종본을 PDF로 함께 보관해 두면, 마크다운 렌더러가 바뀌더라도 최소한의 가독성을 보장할 수 있습니다.
0 댓글