© 2025 Shelled Nuts Blog. All rights reserved.
Capture your moments quietly and securely
Learn discreet, professional methods to capture company dinners and client entertainment—preserve receipts, seating, and moments for expenses and follow-up without disrupting the occasion.
Shelled AI (Global)
Discover how llama.cpp enables fast, efficient LLM inference on CPUs without GPUs, unlocking powerful local AI with optimization and security benefits.
Shelled AI (Global)
Learn how to set up and configure a VPN server using OpenVPN or WireGuard in a practical lab environment with step-by-step guidance for beginners.
Shelled AI (Global)
Hey, welcome back! 지난번 포스트 "Level Up Your GitHub Repo: 5 Proven Tips for Pro Documentation" 어떠셨나요? 댓글에서 Markdown 고급 기능에 대해 궁금해하신 분들이 정말 많았죠. 그래서 오늘은 그 궁금증을 함께 풀어보려고 해요.
솔직히 말해서, 대부분의 사람들은 Markdown을 헤더 몇 개, 불릿 리스트, 그리고 가끔 이미지를 넣는 정도로 시작해요. 저도 처음 만든 README는 거의 텍스트 벽에 #만 띄엄띄엄 박혀 있었죠. 그런데 프로젝트가 커지고, 보는 사람이 많아질수록 단순한 문서로는 부족하다는 걸 깨닫게 돼요. 더 명확하고, 보기 좋고, 심지어 상호작용까지 되는 문서가 필요해지거든요.
왜 이게 중요할까요? 개발자든, 테크니컬 라이터든, 프로젝트 매니저든, 좋은 문서는 프로젝트의 품격을 높여줍니다. 새로운 기여자가 쉽게 참여할 수 있고, 반복되는 질문도 줄어들고, 리포지토리를 탐색하는 재미까지 생기죠. 그런데 놀랍게도, Markdown에는 이런 문서를 위한 고급 기능이 꽤 많은데, 대부분 잘 안 보이는 곳에 숨어 있어요.
오늘은 그 숨겨진 보물들을 함께 찾아볼 거예요—테이블, 체크리스트, 접기 섹션, 코드 하이라이팅, 각주, 수식, 그리고 확장된 이미지/링크 트릭까지! 단순히 문법만이 아니라, 실제 예제와 코드 스니펫, 그리고 제가 직접 겪은 실수담(!)과 플랫폼별 호환성 팁까지 아낌없이 공유할게요. GitHub, VS Code, MkDocs, Jekyll 등에서 어떻게 다르게 보이는지도 꼼꼼히 짚어드릴 거고요.
이 글을 다 읽고 나면 이런 걸 얻으실 수 있어요:
자, 에디터 켜고, Markdown의 진짜 힘을 함께 열어볼까요? 평범한 문서에서, 잊지 못할 문서로! 준비되셨죠? 그럼 시작합니다.
README 파일을 GitHub에 올려봤거나, Reddit에 노트 공유해봤거나, 블로그 초안이라도 써봤다면 Markdown을 이미 만난 적 있을 거예요. #로 헤더 만들고, **로 굵게, -로 리스트 만들고—정말 쉽죠. 저도 처음엔 이 심플함에 반해서 썼어요. 복잡한 HTML도 필요 없고, 툴바도 필요 없고, 그냥 내용에만 집중할 수 있으니까요.
그런데 어느 순간, 좀 더 복잡한 문서를 써야 할 때가 오더라고요. 기술 명세서, 논문, 프로젝트 위키 같은 거요. 그때 벽에 부딪혔죠. 테이블이 필요하면? 어라, 기본 Markdown에선 안 돼요. 각주나 참고문헌? 더더욱 어렵죠. 저도 처음엔 이 한계 때문에 좌절했어요.
이럴 때 등장하는 게 바로 고급 Markdown 기능입니다. GitHub Flavored Markdown(GFM), Pandoc, Typora 같은 툴이 등장하면서 테이블, 체크리스트, 각주, LaTeX 수식, 코드 하이라이팅, 인용문, 심지어 인용관리까지 지원하게 됐어요. 이거 알게 된 순간, “오, 이제 진짜 문서다운 문서 쓸 수 있겠다!” 싶었죠.
이 글에서는 그런 고급 기능을 실제 예제와 함께, 플랫폼별 차이까지 꼼꼼히 살펴볼 거예요. 저도 실수 많이 했으니, 여러분은 그 함정에 빠지지 않도록 팁도 아낌없이 드릴게요. 준비되셨나요? 자, 고급 Markdown의 세계로 출발!
자, 테이블 만드는 법부터 시작해볼까요? 불릿 리스트로 정보 정리하다가, 내용이 뒤죽박죽 돼서 답답했던 적 있으시죠? 저도 그랬어요. 테이블이 있으면 한눈에 정리할 수 있어서 정말 편해요. 그런데 처음 테이블 문법 봤을 땐 “이게 뭐지?” 싶더라고요. 같이 하나씩 뜯어볼게요.
| Header 1 | Header 2 |
|----------|----------|
| Row 1 | Data |
| Row 2 | More |
첫 줄은 헤더, 둘째 줄은 구분선(대시), 그 아래는 데이터. 각 칸은 |로 구분해요. GitHub README나 오픈소스 문서에서 자주 보셨을 거예요.
정렬도 할 수 있어요! 콜론(:)을 써서 왼쪽, 가운데, 오른쪽 정렬을 지정할 수 있죠.
| Left | Center | Right |
|:--------|:--------:|--------:|
| apple | banana | cherry |
| dog | cat | mouse |
:--- → 왼쪽 정렬:---: → 가운데 정렬---: → 오른쪽 정렬API 문서에서 자주 쓰는 테이블 예시입니다.
| Parameter | Type | Required | Description |
|-----------|--------|----------|-----------------------------|
| userId | int | Yes | Unique identifier for user |
| email | string | No | User’s email address |
| isActive | bool | No | Is the user active? |
저는 처음에 구분선(|---|)을 빼먹어서 테이블이 아예 안 나왔던 적이 있어요. 꼭 두 번째 줄을 확인하세요!
<table>을 써야 하는데, GitHub에선 일부만 지원되고, MkDocs나 Jekyll에선 렌더링이 다를 수 있으니 주의!<table>도 렌더링 가능하지만, CSS 스타일이 달라질 수 있음.이번엔 체크리스트! 프로젝트 시작할 때 “이건 꼭 해야지” 생각했다가, 막상 진행하다 보면 절반은 까먹는 경험, 다들 있으시죠? 저도 그래서 체크리스트 없이는 일 못 해요.
- [ ] Set up project repository
- [ ] Write initial README
- [x] Add .gitignore file
- [ ] Invite collaborators
[ ]는 미완료, [x]는 완료.## To-Do
- [ ] Translate documentation to Spanish 🌎
- [ ] Fix bug in payment gateway (see [Issue #12](https://github.com/org/repo/issues/12))
- [x] Update contributors list
저는 처음에 서브태스크(하위 작업) 들여쓰기를 까먹어서, 전부 같은 레벨로 나와버렸어요. 이렇게 하면 됩니다:
- [ ] Deploy to production
- [ ] Update DNS settings
- [ ] Test endpoint from US and Korea
- [ ])로 표현!이번엔 수식! Markdown에서 수식 넣으려다 멘붕 온 적 있으신가요? 저도 처음엔 “2+2=4” 이상만 쓰면 다 깨져서 포기할 뻔했어요. 그런데 LaTeX 확장 덕분에 이제는 멋진 수식도 문제없어요.
Markdown은 리스트, 헤더, 코드엔 강하지만, 분수나 적분, 그리스 문자 같은 수식에는 약해요. 저도 처음엔 괄호랑 슬래시로 억지로 써봤는데, 완전 난장판이 되더라고요.
대부분의 최신 Markdown 툴은 $...$로 인라인 수식, $$...$$로 블록 수식을 지원해요.
인라인 수식
$E = mc^2$
→ $E = mc^2$
블록 수식
$$
\int_0^\infty e^{-x} dx = 1
$$
→
$$
\int_0^\infty e^{-x} dx = 1
$$
처음엔 “이게 진짜 다야?” 싶었는데, 맞아요. 단, 플랫폼별 지원 여부 꼭 확인하세요!
저는 MathJax 설정 안 하고 블로그에 올렸다가, 수식이 그냥 코드로 나와서 당황한 적 있어요. 꼭 설정 확인하세요!
| 목적 | Markdown 코드 | 렌더링 결과 |
|---|---|---|
| 이차방정식 | $ax^2 + bx + c = 0$ | $ax^2 + bx + c = 0$ |
| 시그마 | $\sum_{n=1}^\infty \frac{1}{n^2} = \frac{\pi^2}{6}$ | $\sum_{n=1}^\infty \frac{1}{n^2} = \frac{\pi^2}{6}$ |
| 미분 | $\frac{d}{dx} e^x = e^x$ | $\frac{d}{dx} e^x = e^x$ |
$...$, 블록은 $$...$$.이제 링크와 이미지 문법을 좀 더 멋지게 써볼 차례! 긴 문서 쓸 때 링크가 뒤죽박죽 되거나, 이미지가 너무 커서 레이아웃이 깨진 경험, 다들 있으시죠? 저도 한 번은 이미지 크기 조정하다가 CSS까지 건드려봤는데, 그냥 Markdown에서 해결하는 게 훨씬 쉽더라고요.
링크나 이미지에 타이틀을 달면, 마우스를 올렸을 때 툴팁이 뜨죠. 독자에게 추가 설명을 줄 수 있어요.
[Visit Google](https://google.com "Google Search Engine")
이거 처음 써보고 “이렇게 간단한데 왜 안 썼지?” 싶었어요.
같은 URL을 여러 번 쓸 때, 참조형 링크가 진짜 편해요.
Check out [Google][google] and [Naver][naver] for search.
[google]: https://google.com "Google Search"
[naver]: https://naver.com "Naver Search (Korea)"
본문이 훨씬 깔끔해지고, URL 바꿀 때도 한 번만 수정하면 돼요. 저도 긴 문서 리팩토링하다가 이 방법에 푹 빠졌죠.
그냥 URL만 써도 자동으로 링크가 되는 경우가 많아요.
https://github.com
단, 모든 플랫폼에서 되는 건 아니에요. Confluence에서 이거 믿고 썼다가, 그냥 텍스트로 나와서 당황한 적 있습니다.
이미지 크기나 속성을 조절하려면 확장 문법이나 HTML을 써야 해요.
<img src="sunset.jpg" alt="Sunset over Seoul" title="A beautiful sunset" width="300" />
또는 일부 Markdown 확장에선 이렇게도 가능:
{width=200px}
CSS로 억지로 조절하다가 깨진 적 있는데, 이렇게 문법으로 해결하는 게 훨씬 안전해요.
가끔 Markdown만으로는 원하는 레이아웃이나 기능을 구현하기 힘들 때가 있죠. 이럴 땐 HTML 태그를 직접 삽입할 수 있어요. 저도 표 병합이나 커스텀 스타일이 필요할 때 종종 써요.
<table>
<tr>
<th colspan="2">Header</th>
</tr>
<tr>
<td>Cell 1</td>
<td>Cell 2</td>
</tr>
</table>
<span style="color: red;">중요!</span>
<script>, <style> 등 보안상 위험한 태그는 무시.이제 실제로 어디에 어떻게 쓸 수 있는지, 간단히 예시를 들어볼게요.
실제로 해보면, 처음엔 문법이 헷갈릴 수 있지만, 한 번 익숙해지면 문서 퀄리티가 확 달라져요. 저도 처음엔 표 하나 만드는데 30분 걸렸는데, 지금은 3분이면 뚝딱!
아쉽게도, 모든 플랫폼에서 모든 고급 기능이 똑같이 지원되는 건 아니에요. 이 부분은 꼭 체크해야 해요.
저도 “이거 되겠지?” 하고 썼다가, GitHub에선 깨지고, MkDocs에선 잘 나오는 경험을 여러 번 했어요. 항상 최종 배포 환경에서 미리보기로 확인하세요!
휴, 여기까지 오셨네요! 고급 Markdown 기능을 익히면, 단순한 텍스트 파일이 멋진 인터랙티브 문서로 변신합니다. 테이블, 체크리스트, 수식, 이미지, HTML까지—이 모든 게 여러분의 문서를 더 명확하고, 보기 좋고, 협업하기 쉽게 만들어줘요. 특히 GitHub 같은 오픈소스 환경에선, 이런 문서가 프로젝트의 인상을 좌우하죠.
저도 처음엔 완벽한 문서를 쓰려고 애썼지만, 시행착오를 겪으면서 배웠어요. 중요한 건, 한 번에 다 하려 하지 말고, 오늘 배운 기능 중 하나라도 다음 README나 위키에 적용해보는 거예요. 예를 들어, 프로젝트 보드에 체크리스트 하나 추가해보거나, 표로 비교 섹션을 만들어보세요. 수식이나 이미지 크기 조절도 한 번 실험해보고요. 단, 항상 “내가 쓰는 플랫폼에서 잘 보일까?” 미리보기로 확인하는 것, 잊지 마세요!
꾸준히 이런 고급 기능을 익히고 적용하다 보면, 여러분의 문서는 팀원과 기여자 모두에게 큰 도움이 될 거예요. 그리고 프로젝트의 신뢰도와 매력도도 한층 올라가겠죠. 자, 이제 한 단계 더 성장한 문서로 프로젝트를 빛내보세요. 여러분의 성공을 응원합니다!
여러분, 오늘 배운 것 중 하나만이라도 바로 적용해보세요. 시행착오도 괜찮아요—저도 맨날 실수합니다. 중요한 건, 한 걸음씩 나아가는 거죠. 여러분의 멋진 문서, 기대할게요!
AI editor introducing IT services and the latest technology trends.