마크다운을 배워야 하는 이유
README 파일 하나 제대로 작성하지 못해 프로젝트 포트폴리오가 엉망이거나, 블로그 글 하나 쓰는데 HTML 태그를 일일이 입력하고 있다면 시간 낭비입니다. 마크다운(Markdown)은 개발자가 문서 작성 시 가장 먼저 익혀야 할 경량 마크업 언어로, 일반 텍스트 기반으로 작성하면 자동으로 HTML 등으로 변환됩니다. GitHub README, Velog, Tistory, 기술 문서, 협업 툴 등 대부분의 개발 환경에서 표준으로 사용되며, 문법이 직관적이어서 5분이면 핵심을 파악할 수 있습니다.
 |
| 마크다운초보탈출자주실수하는문법과해결책 |
마크다운 핵심 문법 정리
마크다운 문법은 크게 헤더, 문단/줄바꿈, 강조, 코드, 목록, 인용, 링크/이미지, 표로 구성됩니다. 각 문법의 실무 적용 예시와 주의사항을 정리했습니다.
헤더(Header)
- ATX 방식: # H1부터 ###### H6까지 샵(#) 개수로 제목 레벨 지정. 예:
# 제목 - Setext 방식: 제목 다음 줄에 = (H1) 또는 - (H2)로 밑줄 표시
- 주의: ATX 방식이 직관적이고 6단계까지 지원하므로 실무에서는 ATX를 권장합니다.
문단 구분과 줄바꿈
- 문단 구분: 빈 줄(엔터 2번) 입력
- 줄바꿈: 문장 끝에 공백 두 칸 + Enter 또는
<br>태그 사용 - 주의: 엔터 한 번만 입력하면 줄바꿈이 적용되지 않습니다. 초보자가 가장 많이 실수하는 부분이므로 반드시 공백 두 칸을 습관화하십시오.
강조(Emphasis)
- 기울임(italic):
*텍스트*또는_텍스트_ - 굵게(bold):
**텍스트**또는__텍스트__ - 취소선:
~~텍스트~~ - 주의: 여는 문자와 닫는 문자가 반드시 동일해야 합니다.
*텍스트**같은 형식은 렌더링되지 않습니다.
코드 표현
- 인라인 코드: 백틱(`)으로 감싸기. 예:
`console.log()` - 코드 블록: 백틱 3개(```) 또는 물결표 3개(~~~)로 감싸기
- 문법 강조: 코드 블록 시작 시 언어명 명시. 예:
```python - 팁: 언어명을 명시하면 GitHub, Velog 등에서 자동으로 Syntax Highlighting이 적용되어 가독성이 비약적으로 향상됩니다.
목록(Lists)
- 순서 없는 목록:
-,*,+중 하나 사용 (들여쓰기로 하위 항목 생성) - 순서 있는 목록:
1.,2.형식 (번호는 자동으로 정렬되므로 모두1.로 입력해도 무방) - 팁: 프로젝트 README에서 설치 단계나 실행 순서를 표현할 때는 순서 있는 목록을 사용하십시오.
인용문(Blockquote)
>기호로 시작. 중첩 가능 (예:> > 중첩 인용)- 활용: 공식 문서 인용, 경고 메시지, 주의사항 표시 시 가독성을 높일 수 있습니다.
링크 및 이미지
- 링크:
[텍스트](URL) - 자동 링크:
<https://...> - 이미지:
 - 이미지에 링크 연결:
[](URL) - 팁: 이미지 정렬이 필요하면 HTML 태그 사용. 예:
<p align="center"><img src="..."></p>
표(Table)
|로 열 구분,---이상으로 구분선 표시- 정렬:
:--(왼쪽),:--:(중앙),--:(오른쪽) - 주의: 구분선은 최소 3개의 하이픈이 필요하며, 플랫폼에 따라 렌더링 방식이 다를 수 있습니다.
특수문자 이스케이프
- 마크다운 문법 문자를 그대로 출력하려면 앞에 백슬래시(
\) 추가 - 예:
\*,\#,\[
실무에서 자주 쓰는 마크다운 활용법
GitHub README 작성
프로젝트 README는 포트폴리오의 첫인상을 결정합니다. 다음 항목을 포함하십시오:
- 프로젝트명 및 로고: 헤더와 이미지 태그로 상단에 배치
- 소개 및 배포 주소: 프로젝트 목적과 데모 링크 명시
- 개발 기간 및 팀원 소개: HTML 테이블로 프로필 사진, 이름, GitHub 링크 정리
- 기술 스택: Shields.io 배지로 시각화 (예:
) - 설치 및 실행 방법: 코드 블록으로 명령어 제시 (언어명 명시)
- 주요 기능: 스크린샷과 함께 설명
팁: 다른 개발자의 README를 포크(Fork)해서 구조를 참고하면 빠르게 작성할 수 있습니다. GitHub에서 README.md 파일을 열고 연필 아이콘 클릭 후 'Fork this repository and edit this file'을 선택하십시오.
프로필 README 생성
GitHub 프로필 README는 자신의 GitHub ID와 동일한 이름의 Public 레포지토리를 생성하면 프로필 메인에 자동 노출됩니다. 다음 요소를 활용하십시오:
- Header/Footer 생성기: type, color, height, section, text(띄어쓰기는 %20) 등 파라미터로 커스터마이징
- GitHub Stats 위젯:
https://github-readme-stats.vercel.app/api?username=자신의깃허브ID - Top Langs 위젯: 가장 많이 사용하는 언어 통계 표시
- 배지 생성: Shields.io에서 텍스트, 색상코드, 로고명(Simple Icons 참조) 입력
- 배지 정렬:
<p>태그로 감싸면 한 줄에 나란히 배치 가능
블로그 및 기술 문서 작성
- Velog, Tistory: 마크다운 에디터 기본 제공. 작성 후 미리보기로 렌더링 확인
- 노션: 마크다운 단축키 지원 (예:
#+ space로 헤더,-+ space로 불릿 리스트,[]+ space로 체크박스) - 협업 도구: Slack, Discord 등에서도 인라인 코드와 코드 블록 문법 사용 가능
초보자가 자주 실수하는 부분과 해결책
- 줄바꿈이 안 됨: 엔터만 입력하면 적용되지 않습니다. 문장 끝에 공백 두 칸 + Enter 또는
<br>사용 - 강조 문법이 깨짐: 여는 문자와 닫는 문자가 동일해야 합니다.
*텍스트**는 렌더링 실패 - 코드 블록에 문법 강조가 안 됨: 백틱 3개 뒤에 언어명 명시 (예:
```java) - 리스트 들여쓰기 오류: Tab 또는 스페이스 4칸으로 하위 항목 생성. 플랫폼마다 렌더링 방식이 다를 수 있으므로 미리보기로 확인
- 표 구분선 오류: 최소 3개의 하이픈(
---) 필요. 정렬 기호(:)는 하이픈 앞뒤에 배치 - 특수문자 출력 실패: 마크다운 문법 문자는 백슬래시(
\)로 이스케이프
요약 및 Action Item
마크다운은 헤더, 강조, 코드, 목록, 링크/이미지, 표 등 직관적인 문법으로 구성되어 있으며, HTML로 자동 변환되어 README, 블로그, 협업 문서 작성에 필수적입니다. 줄바꿈은 공백 두 칸 + Enter, 코드 블록에는 언어명 명시, 특수문자는 백슬래시로 이스케이프하는 규칙을 반드시 숙지하십시오. 지금 당장 자신의 GitHub 프로필 README 레포지토리를 생성하고, 위에서 정리한 배지와 위젯을 활용해 포트폴리오를 업그레이드하십시오.
#함께 읽으면 좋은 글
VSCode 파이썬 인터프리터 인식 오류 해결 완벽 가이드 : 바로보기
댓글
댓글 쓰기