이 레포가 무엇을 하는 물건인가.
hello-algo(중국어 제목 Hello 算法)는 자료구조·알고리즘을 ① 애니메이션 그림으로 설명하고, ② 그 개념의 코드를 14개 언어로 제공하며, ③ 그 코드를 곧바로 빌드·실행해볼 수 있게 만든 무료 입문서다. 텍스트는 웹사이트(hello-algo.com)로 읽고, PDF/EPUB로 내려받을 수도 있다. 핵심은 "읽기만 하는 책"이 아니라 읽으면서 손으로 돌려보는 책이라는 점.
저장소 자체는 "책 한 권을 만드는 공장"이다. 본문은 docs/ 안의 마크다운 16개 장(章)이고, 예제 코드는 codes/ 안에 언어별로 따로 들어 있다. 빌드 도구(MkDocs)가 이 둘을 합쳐 예쁜 웹사이트로 찍어낸다. 그래서 이 레포에서 배울 거리는 두 겹이다 — ① 콘텐츠로서의 알고리즘 지식, 그리고 ② 그 콘텐츠를 만드는 "문서를 코드처럼 다루는(docs-as-code)" 엔지니어링.
저자는 krahets(Yudong Jin)이며, 같은 내용이 정식 종이책으로도 출간됐다. 칭화대 덩쥔후이(邓俊辉) 교수, 아마존 수석과학자 리무(李沐, Dive into Deep Learning 저자)가 추천사를 썼다는 점이 콘텐츠 신뢰도를 뒷받침한다.
트렌딩 이유 · 기존 학습 자료(교재·문제집·강의) 대비 차별점.
알고리즘 학습 자료는 차고 넘치는데도 hello-algo가 ★ 12만 개를 넘기고 GitHub 트렌딩에 56번이나 다시 올라온 이유는, 입문자가 실제로 겪는 세 가지 고통을 정확히 겨냥했기 때문이다.
| 입문자의 고통 | 흔한 자료의 한계 | hello-algo의 처방 |
|---|---|---|
| "글로는 이해가 안 된다" | 교재는 정적인 그림·수식 위주 | 단계별 애니메이션 GIF로 자료구조의 변화를 눈으로 추적 |
| "코드를 못 돌려본다" | 문제집은 정답만, 환경 설정은 알아서 | codes/가 언어별 실행 프로젝트 — 받아서 바로 빌드·실행 |
| "내 언어가 없다" | 대개 한두 언어(C++/Java)에 고정 | 14개 언어로 같은 예제 제공, 페이지에서 탭 전환 |
여기에 완전 무료·오픈소스(콘텐츠는 CC BY-NC-SA), 다국어(간체·번체 중국어·영어·일본어·러시아어), 현대적인 웹 UX(검색·다크모드·코드 복사·언어 탭 동기화)가 더해진다. GeeksforGeeks의 광고 더미나 두꺼운 CLRS 교재와 비교하면, "깔끔하고, 친절하고, 손으로 해볼 수 있다"는 점이 차별점이다.
좋은 글만으로도, 좋은 빌드 시스템만으로도 이 정도가 안 된다. hello-algo는 덩쥔후이·리무가 인정한 콘텐츠를 docs-as-code로 깔끔하게 빌드·배포해 둘을 곱했다. 그래서 "읽기 좋은 책"인 동시에 "기여하기 좋은 오픈소스"가 됐고, 14개 언어 코드의 상당수가 커뮤니티 번역으로 채워졌다.
이 저장소의 글·그림·영상·코드는 CC BY-NC-SA 4.0으로 배포된다. 즉 저작자 표시(BY) · 비영리(NC) · 동일조건 변경허락(SA) 조건이다. 학습·번역·기여는 환영이지만, 예제 코드를 그대로 상업 제품에 넣거나 책을 영리 목적으로 재배포하는 것은 라이선스 위반이 될 수 있다. MIT·Apache 같은 코드 라이선스와 다르다는 점을 기억하자.
"책"처럼 보이지만 실제로는 정적 사이트 생성기·14개 언어 빌드·Docker가 도는 소프트웨어다.
hello-algo의 흥미로운 점은 핵심 자산이 "글 + 그림 + 14개 언어 코드"이고, 그것을 한 권의 웹사이트로 묶는 부분만 빌드 도구(Python 기반 MkDocs)라는 것이다. 그래서 레포를 세 레이어로 나눠 보면 전체가 한눈에 들어온다.
| 레이어 | 기술 | 역할 |
|---|---|---|
| 콘텐츠 | Markdown 16개 장 (docs/chapter_*/) | 책 본문. 그림·수식·코드 조각을 품은 알고리즘 설명. |
| 실행 코드 | 14개 언어 프로젝트 (codes/{언어}/) | 장 구조를 그대로 복제한, 빌드·실행 가능한 예제 모음. |
| 사이트 빌드 | MkDocs + Material for MkDocs 9.5.5 | 마크다운+코드를 합쳐 정적 HTML 사이트로 생성. |
| 마크다운 확장 | PyMdown Extensions (snippets·superfences·tabbed·details…) | 코드 조각 포함, 언어 탭, 접이식 박스, 경고 박스 등. |
| 수식 | MathJax (arithmatex) | 시간/공간 복잡도의 Big-O 수식을 렌더링. |
| 이미지 뷰어 | mkdocs-glightbox | 애니메이션·도해를 클릭하면 확대(라이트박스). |
| 다국어 | 언어별 mkdocs.yml (zh·zh-hant·en·ja·ru) | 같은 테마로 5개 언어 사이트를 각각 빌드. |
| 재현 빌드 | Dockerfile (python:3.10-alpine) + docker-compose.yml | 로컬에서 한 줄로 사이트를 빌드·서빙(:8000). |
| 배포 | 정적 호스팅 (hello-algo.com) + GitHub Releases | 웹 열람 + PDF/EPUB 다운로드. |
codes/의 진짜 파일을 끌어와 보여준다. 덕분에 책과 실행 코드가 절대 어긋나지 않는다 — 이게 이 프로젝트 설계의 핵심이다(§4).먼저 빌드 파이프라인 한 장, 그다음 "단일 진실원(코드 한 벌)"이라는 핵심 설계를 따라가 본다.
hello-algo의 구조는 "원본은 따로, 합치는 건 빌드 때"로 요약된다. 책 글(docs/)과 실행 코드(codes/)는 평소엔 분리돼 있다가, MkDocs가 빌드하는 순간 스니펫 포함으로 코드를 본문 안에 끌어와 하나의 사이트로 굳힌다. 같은 본문이 5개 언어 설정으로 5번 빌드되어 다국어 사이트가 된다.
대부분의 알고리즘 책은 본문에 코드를 그림처럼 박아둔다. 그러면 코드를 고칠 때 본문과 실제 파일이 따로 놀기 시작한다. hello-algo는 이 문제를 구조로 없앤다 — 본문은 코드를 소유하지 않고 참조한다.
codes/에만 있고 책은 그걸 가리키기만 한다. 그래서 코드를 고치면 책도 자동으로 최신이 된다. 실무에서 설정·문서·스키마를 다룰 때 늘 등장하는 핵심 원칙이다.각 언어 폴더(codes/{언어}/)는 책의 장 구조(chapter_sorting, chapter_tree …)를 똑같이 복제한다. 그래서 "정렬 장의 퀵소트"를 어느 언어에서 찾든 경로가 예측 가능하고, 새 언어로 번역할 때도 빈칸을 채우듯 같은 위치에 파일만 추가하면 된다. 기여자 친화적 구조다.
modules/(또는 공용 파일)로 분리한다. 덕분에 각 예제는 알고리즘 핵심만 짧게 담아 가독성이 좋아진다. 파이썬은 test_all.py로 모든 예제를 한 번에 회귀 테스트하기까지 한다.Material 테마의 content.tabs.link 기능으로, 페이지 어디서든 한 번 "Python" 탭을 누르면 그 페이지의 모든 코드가 Python으로 전환된다. 독자는 자기 언어를 한 번만 고르면 된다. 또 같은 본문이 5개 언어 mkdocs.yml로 각각 빌드되어, 콘텐츠는 한 벌이되 사이트는 다국어로 갈라진다.
이 저장소를 "코드 프로젝트"가 아니라 "출판사의 조판·인쇄 공정"으로 보면 편하다. 원고(docs/)와 예제 소스(codes/)가 들어오면, 조판기(MkDocs)가 삽화·수식·코드 탭을 붙여 한 권으로 묶고, 같은 원고를 5개 언어판으로 찍어낸다. Docker는 그 인쇄소를 누구 컴퓨터에서나 똑같이 재현하는 컨테이너다.
"콘텐츠(docs) · 실행 코드(codes) · 빌드 설정"의 3분할 구조.
최상위는 의외로 단순하다. 책 본문은 docs/, 실행 코드는 codes/, 그 둘을 묶는 설정이 mkdocs.yml·Dockerfile이다. 다국어판(en/·ja/·ru/·zh-hant/)은 각자 자기 docs/와 mkdocs.yml을 갖는다.
| 경로 | 역할 |
|---|---|
docs/chapter_*/ | 책 본문. index.md(장 도입) + 절별 .md + *.assets/(삽화·애니메이션 GIF). |
codes/{언어}/chapter_*/ | 그 장의 예제를 해당 언어로 구현. 본문이 스니펫으로 끌어오는 원본. |
codes/python/modules/ · test_all.py | 공용 자료구조·출력 도우미 + 전 예제 회귀 테스트(pytest). |
codes/rust/Cargo.toml | 각 예제를 실행 타깃(bin)으로 등록 — cargo run 한 줄로 돌아가게. |
mkdocs.yml | 테마(Material)·네비게이션(16장)·마크다운 확장·플러그인을 정의하는 빌드 두뇌. |
Dockerfile / docker-compose.yml | 의존성·빌드 절차를 컨테이너에 박제 — 누구나 동일하게 사이트 재현. |
overrides/ | Material 기본 템플릿 위에 덧씌우는 커스텀 HTML 조각·스타일. |
이 레포에서 진짜 배울 만한 것 — "알고리즘"과 "엔지니어링" 두 갈래.
가장 큰 학습 가치는 당연히 콘텐츠 자체다. 복잡도(2장)→선형 자료구조(4·5·6장)→트리·힙·그래프(7·8·9장)→탐색·정렬(10·11장)→문제풀이 패러다임(12~15장) 순서가 입문 커리큘럼으로 잘 짜여 있다. 그림으로 직관을 잡고, 코드로 검증하는 순환이 이 책의 학습법이다.
퀵소트 하나를 Python·Rust·Go로 나란히 읽으면, 파이썬의 간결함, 러스트의 소유권/borrow, 고의 명시적 슬라이스 같은 언어 철학 차이가 드러난다. 새 언어를 배울 때 "이미 아는 알고리즘"을 매개로 비교하는 건 매우 효율적인 학습법이다.
이 레포는 그 자체가 MkDocs-Material 모범 사례다. mkdocs.yml 한 파일로 검색·다크모드·코드복사·언어탭·수식·라이트박스를 켜는 법, pymdownx.snippets로 코드를 동기화하는 법을 그대로 베껴 내 프로젝트 문서에 쓸 수 있다.
Dockerfile이 Python 버전·mkdocs-material 버전(9.5.5)·빌드 순서를 못 박아, 누구 환경에서나 동일한 사이트가 나오게 한다. 작은 프로젝트로 의존성 고정과 컨테이너 빌드를 체득하기 딱 좋은 예제다.
장 구조를 거울처럼 복제한 레이아웃 덕분에, 기여자는 "빈 칸"을 찾아 채우면 된다. 코드 번역(언어 추가)·오타 수정·번역 검수 같은 다양한 난이도의 기여 경로가 열려 있어, 첫 오픈소스 PR 연습 대상으로 훌륭하다.
본문이 코드를 "복붙"이 아니라 "참조"로 가져오는 개념은 대략 이렇게 생겼다(개념 예시 — 실제 문법과 다를 수 있음):
# docs/chapter_sorting/quick_sort.md 안에서
# 코드를 직접 적지 않고, 실제 파일을 끼워 넣는다
```python
--8<-- "codes/python/chapter_sorting/quick_sort.py"
```
# → 빌드 때 진짜 quick_sort.py 내용이 그 자리에 들어감
# → 코드를 고치면 책도 자동으로 최신화"읽기 · 코드 실행 · 사이트 빌드" 세 단계로 요구사항이 다르다.
| 하고 싶은 일 | 필요한 것 |
|---|---|
| 그냥 읽기 | 웹 브라우저만 있으면 됨 — hello-algo.com 접속, 또는 Releases의 PDF/EPUB 다운로드. |
| 예제 코드 실행 | 고른 언어의 툴체인만. 예: Python 3, JDK(Java), cargo(Rust), go, Node(JS/TS), gcc/CMake(C/C++) 등. |
| 사이트 로컬 빌드 | Python 3.10 + mkdocs-material==9.5.5 + mkdocs-glightbox (pip install). |
| 빌드 환경 통째로 | Docker — docker compose up 한 줄이면 :8000에서 사이트가 뜬다(파이썬 설치 불필요). |
| OS | macOS · Windows · Linux 모두 가능(순수 텍스트·표준 툴체인). |
특별한 하드웨어(GPU·고사양 메모리)는 전혀 필요 없다. 가장 가벼운 길은 그냥 사이트를 읽는 것이고, 가장 확실한 실습 길은 저장소를 클론해 Docker로 사이트를 띄운 뒤, 관심 언어 폴더로 들어가 예제를 하나씩 실행해 보는 것이다.
읽기만 하면 남는 게 없다 — 손으로 돌리고, 비교하고, 기여까지.
저장소를 클론하고 codes/python/chapter_searching/binary_search.py(또는 본인 언어)를 직접 실행해 본다. "책에서 본 코드가 실제로 도는" 첫 경험으로, hello-algo의 일건운행(一键运行 = 한 번에 실행) 컨셉을 체감하는 게 목표.
docker compose up으로 사이트를 빌드해 localhost:8000에서 열어 본다. "마크다운 + 코드 → 완성된 웹사이트"라는 정적 사이트 생성 파이프라인이 내 손에서 도는 걸 확인한다.
퀵소트(chapter_sorting/quick_sort)를 Python·Rust·Go 세 폴더에서 펼쳐 놓고, 스왑·재귀·메모리 처리가 언어마다 어떻게 달라지는지 표로 정리한다. 언어 철학의 차이를 알고리즘이라는 공통 렌즈로 보는 연습.
파이썬 예제 하나에 단계별 print를 넣어 알고리즘의 중간 상태를 눈으로 본 뒤, test_all.py(pytest)를 돌려 회귀 테스트가 여전히 통과하는지 확인한다. "동작을 바꾸지 않는 로깅"과 테스트의 감을 잡는다.
잘 아는 언어에서 아직 비어 있거나 개선 여지가 있는 예제를 골라, 장 구조를 그대로 따라 파일을 추가하고 본문 스니펫이 잘 끌어오는지 확인한 뒤 PR을 연다. 단일 진실원·기여 가이드(부록 16.2)를 실전으로 익히는 과제.
hello-algo를 발판으로 "탄탄한 CS 기초 + 문서 엔지니어링"을 익히는 4주 계획.
| 주차 | 주제 | 학습 자료 (장/파일) |
|---|---|---|
| 1주차 | 복잡도 분석 + 선형 자료구조 | 2장(복잡도) · 4장(배열·연결리스트) · 5장(스택·큐) + 실습 1 |
| 2주차 | 해시·트리·힙·그래프 | 6장(해시) · 7장(트리) · 8장(힙) · 9장(그래프) |
| 3주차 | 탐색·정렬 직접 구현·비교 | 10장(탐색) · 11장(정렬) + 실습 3·4 |
| 4주차 | 문제풀이 패러다임 | 12장(분할정복) · 13장(백트래킹) · 14장(DP) · 15장(탐욕) |
| +α | docs-as-code로 나만의 기술 노트 사이트 만들기 | MkDocs-Material · pymdownx 확장 · Docker 배포 + 실습 2·5 |
알고리즘은 "그릇 → 절차" 순서로 쌓아야 한다. 복잡도(평가 기준)를 먼저 손에 쥐고, 선형 그릇(배열·스택)에서 비선형 그릇(트리·그래프)으로 넓힌 뒤, 그 그릇들로 탐색·정렬을 돌리고, 마지막에 분할정복·DP·탐욕 같은 문제 설계 사고법으로 마무리한다. hello-algo의 장 순서가 이미 이 곡선을 따른다.
본문에 나온 용어 빠른 참조.
| 자료구조 | 데이터를 담는 그릇의 모양(배열·연결리스트·트리·해시·그래프 등). |
| 알고리즘 | 그 그릇으로 문제를 푸는 절차(정렬·탐색·DP 등). |
| 시간/공간 복잡도 | 입력이 커질 때의 속도·메모리 증가율. Big-O로 표기(O(n), O(log n)…). |
| 동적계획법(DP) | 큰 문제를 겹치는 작은 문제로 쪼개고 결과를 저장해 재사용하는 기법(14장). |
| 백트래킹 | 가능성을 시도하다 막히면 되돌아가며 해를 찾는 탐색(13장, N-퀸 등). |
| 분할정복 | 문제를 절반씩 나눠 풀고 합치는 전략(12장, 병합정렬·하노이탑). |
| 탐욕법 | 매 순간 최선을 골라 전체 해에 도달하려는 전략(15장). |
| MkDocs / Material for MkDocs | 마크다운을 기술 문서 사이트로 굽는 정적 사이트 생성기와 그 현대적 테마. |
| 정적 사이트 생성기(SSG) | 원본을 미리 완성 HTML로 구워두는 도구. 빠르고 안전하고 저렴. |
| pymdownx.snippets | 마크다운에 실제 소스 파일을 끼워 넣는 확장 — 책과 코드의 동기화 비결. |
| 단일 진실원(SSoT) | 같은 정보를 한 곳에만 두는 원칙. 코드는 codes/에만, 책은 참조만. |
| 폴리글랏(다언어) | 같은 알고리즘을 14개 언어로 제공 — 비교 학습·언어 입문에 유리. |
| CC BY-NC-SA 4.0 | 저작자표시·비영리·동일조건변경허락. 상업적 재사용엔 제약이 있는 콘텐츠 라이선스. |