krahets/hello-algo
github.com/krahets/hello-algo ↗ · 4000 files · 11.9 MB · scan capped
动画图解、一键运行的数据结构与算法教程 简体中文 ｜ 繁體中文 ｜ English ｜ 日本語 ｜ Русский 关于本书 本项目旨在打造一本开源免费、新手友好的数据结构与算法入门教程。 - 全书采用动画图解，内容清晰易懂、学习曲线平滑，引导初学者探索数据结构与算法的知识地图。 - 源代码可一键运行，帮助读者在练习中提升编程技能，了解算法工作原理和数据结构底层实现。 - 提倡读者互助学习，欢迎大家在评论区提出问题与分享见解，在交流讨论中共同进步。 若本书对您有所帮助，请在页面右上角点个 Star :star: 支
Overview
hello-algo ("Hello 算法") is a large open-source data-structures-and-algorithms tutorial by krahets, published at hello-algo.com and licensed CC BY-NC-SA 4.0. It is not an application: the repo is a MkDocs Material static site (5 language locales: zh, zh-hant, en, ja, ru) plus a parallel corpus of ~1,500 runnable algorithm samples across 16 programming languages under codes/. Its distinctive traits are per-language tabbed code blocks, step-through frame animations embedded in the markdown, and PythonTutor links for visual execution — with CI that validates every sample by compiling or executing it.
System map
The system has two coupled halves: (1) a MkDocs Material documentation site whose source lives in docs/ with theme overrides in overrides/ and build config in mkdocs.yml, and (2) a multi-language code corpus in codes/ organized as chapter_* directories mirroring the book chapters. Four locale trees (en/, ja/, ru/, zh-hant/) replicate the whole structure, each with its own mkdocs.yml that uses INHERIT to extend the root config. The Dockerfile is the deployment entrypoint: it builds all five locale sites into a single site/ tree and serves it with python -m http.server on port 8000 via docker-compose. There is no runtime backend, database, or service layer — the only external integrations are CDN-loaded assets (MathJax, giscus) and GitHub Discussions for comments.
- Root mkdocs.yml defines the MkDocs Material site 'Hello 算法' v1.3.0 with docs_dir=build/docs, site_dir=site, theme 'material' with custom_dir=build/overrides — the staged build/ layout is produced by copying docs/ and overrides/ before building.
- Dockerfile is the deployment entrypoint: FROM python:3.10.0-alpine, installs mkdocs-material==9.5.5 and mkdocs-glightbox, runs 'mkdocs build' once for the root site and once per locale (zh-hant, en, ja, ru), then serves /hello-algo/site via 'python -m http.server 8000'.
- docker-compose.yml exposes the single 'hello-algo' service on host port 8000; there is no other service, volume, or network configuration.
- docs/ contains the Simplified Chinese source of the book: ~120 markdown files in chapter_* directories, plus per-page image directories named <page>.assets/, a minimal index.md stub, and a hand-written index.html landing page.
- codes/ holds 16 language subdirectories (c, cpp, csharp, dart, go, java, javascript, kotlin, python, pythontutor, ruby, rust, swift, typescript, zig, plus docker assets); each language dir mirrors the book with chapter_* folders of self-contained runnable samples.
- Each locale tree (en/, ja/, ru/, zh-hant/) is a near-complete copy of docs/ + codes/ with a locale mkdocs.yml that uses 'INHERIT: ../mkdocs.yml' config inheritance and overrides site_name, site_url, docs_dir (../build/<locale>/docs) and site_dir (../site/<locale>).
- Per-language manifests anchor each code subproject: codes/go/go.mod (module github.com/krahets/hello-algo, go 1.19), codes/rust/Cargo.toml (package hello-algo-rust with a [[bin]] entry per sample), codes/typescript/package.json (script 'check': tsc) + tsconfig.json (noEmit), codes/csharp/hello-algo.csproj, codes/c/CMakeLists.txt + codes/cpp/CMakeLists.txt, codes/zig/build.zig.
- CI is 13 per-language GitHub Actions workflows in .github/workflows/ (c, cpp, dart, dotnet, go, java, javascript, kotlin, python, ruby, rust, swift, typescript), each path-filtered to codes/<lang>/ and en/codes/<lang>/ and matrixed across ubuntu/macos/windows.
- The theme is customized through overrides/: main.html extends base.html to render a per-language announcement banner, and partials/{actions,comments,content}.html override Material's edit/view buttons, giscus comment injection, and prev/next footer.
- Comments are provided by giscus (GitHub Discussions backend): overrides/partials/comments.html injects the giscus.app client script with data-repo='krahets/hello-algo' and giscus.json whitelists the hello-algo.com origins.
- overrides/zensical/ is a parallel, second theme/toolchain configuration (zensical.toml with its own extra_css/extra_javascript) for the Zensical static site generator, including an animation_player.js not present in the MkDocs theme — indicating an in-progress migration target. (inferred)
- Shared helper code lives in per-language utility packages: codes/python/modules/ (ListNode, TreeNode, Vertex, print_util), codes/javascript/modules/, codes/typescript/modules/, codes/go/pkg/, codes/rust/src/include/ (via src/lib.rs 'pub mod include'), codes/c/utils/.
Feature catalog
User-facing features are reading/learning features rather than app features: a 16-chapter illustrated book, per-language tabbed code samples, step-through frame animations, collapsible PythonTutor visual-execution links, runnable driver-code files, a giscus comment section per page, light/dark themes, full-text search, MathJax math rendering, a custom hero landing page, and five site locales. Contribution-facing features include per-page edit buttons wired to GitHub, a PR template with separate checklists for translation vs. code contributions, and Docker-based one-command local deployment.
- The book is organized as 16 numbered chapters plus preface/appendix/reference/paperbook sections; the full nav tree (Preface → Introduction → Complexity → Data Structures → Arrays/Linked Lists → ... → Greedy → Appendix) is hard-coded in mkdocs.yml.
- Every algorithm sample is presented as a pymdownx.tabbed block with one tab per language (=== 'Python', 'C++', 'Java', 'C#', 'Go', 'Swift', 'JS', 'TS', 'Dart', 'Rust', 'C', 'Kotlin', 'Ruby') containing a fenced code block titled with the source filename, e.g. ```python title='array.py'.
- Step-through animations are encoded as tabbed blocks whose labels are frame numbers (=== '<1>' ... === '<9>'), each wrapping one PNG from <page>.assets/ — e.g. quick_sort.md's pivot_division_step1..9.png sequence for the partition walk-through.
- overrides/zensical/javascripts/animation_player.js upgrades any tabbed set whose labels all match /^<\d+>$/ into a slideshow player with SVG play/pause/prev/next controls, auto-advancing every 1500ms after a 1000ms delay (labels '播放幻灯片'/'暂停幻灯片').
- PythonTutor visual execution is offered via collapsible '??? pythontutor "可视化运行"' admonitions embedding URL-encoded pythontutor.com/render.html#code=... links; codes/pythontutor/ holds the same links in per-function .md files annotated '[file]{array}-[class]{}-[func]{random_access}'.
- Every code sample file is a self-contained runnable program: Python files define functions then a '"""Driver Code""" if __name__ == "__main__":' block that exercises them with printed output (e.g. array.py initializes [1,3,2,5,4] and demos random_access/extend/insert/remove/traverse/find).
- Shared pretty-printing utilities let samples print linked lists, binary trees, heaps, matrices and dicts: codes/python/modules/print_util.py provides print_tree (borrowed from techiedelight), print_linked_list, print_heap, print_dict, print_matrix, re-exported through modules/__init__.py.
- Page comments render only when front matter sets 'comments: true' — comments.html checks page.meta.comments, picks a per-locale prompt string, includes an optional 'partials/checkin.html' (ignore missing), and injects the giscus script with data-mapping='pathname'.
- Giscus theme is synchronized with the Material palette: comments.html reads __md_get('__palette'), maps 'slate' to 'noborder_dark', and posts setConfig messages to the .giscus-frame iframe on palette change.
- Each page gets edit/view action buttons from overrides/partials/actions.html honoring theme features content.action.edit/view, and mkdocs.yml sets edit_uri=tree/main/docs so 'edit' links jump to GitHub's editor (per-locale mkdocs.yml overrides to tree/main/<locale>/docs).
- The landing page docs/index.html is a hand-crafted HTML hero with a .starfield canvas container, absolutely-positioned chapter link cards (astronaut/links/ground artwork), a reviewer grid, and a contrib.rocks contributor image — shipped as a static file inside docs_dir alongside index.md.
- Math rendering uses MathJax 3: mkdocs.yml loads overrides/javascripts/mathjax.js plus the cdnjs tex-mml-chtml bundle and enables pymdownx.arithmatex; mathjax.js configures inline/display delimiters and re-typesets on each navigation via document$.subscribe.
Data flow
Data flow is a static publishing pipeline rather than a runtime system. Author inputs are markdown pages, PNG frame assets, and code files; these flow through a staged build/ directory into per-locale mkdocs builds, producing one static site/ tree served over HTTP. Code samples move by manual transcription: authors write codes/<lang>/chapter_* files, then copy excerpts into the docs' tabbed blocks and into URL-encoded PythonTutor links. At view time the browser pulls third-party resources (MathJax CDN, giscus.app, pythontutor.com, contrib.rocks) — the repo itself serves only static files.
- Build pipeline: Dockerfile copies overrides→build/overrides and docs→build/docs, runs 'mkdocs build -f mkdocs.yml' producing site/, then repeats the copy+build for each locale where locale mkdocs.yml sets docs_dir=../build/<locale>/docs and site_dir=../site/<locale> — all locales land in one /hello-algo/site tree.
- Locale configs are derived, not duplicated: en/mkdocs.yml (and zh-hant/ja/ru equivalents) start with 'INHERIT: ../mkdocs.yml' and only override identity fields (site_name, site_url, docs_dir, site_dir, theme.language, nav), so structural changes to the root config propagate to all locales.
- Code-to-docs flow is manual transcription: docs pages contain fenced copies of the sample code inside === 'Lang' tabs (e.g. array.md's Python block mirrors array.py's logic), so the docs and codes/ trees are independent artifacts that must be kept in sync by contributors.
- PythonTutor flow: each function's source is URL-encoded into a pythontutor.com/render.html#code=... URL with parameters like curInstr, mode=display, py=311; the URLs are stored both inline in '??? pythontutor' admonitions and as standalone records in codes/pythontutor/chapter_*/*.md.
- Animation flow: authors produce ordered PNG frames in <page>.assets/ and reference them as === '<N>' tabs; at view time animation_player.js detects all-numeric-label tabbed sets via isAnimationSet(), wraps them in controllers with prev/next/play buttons, and auto-advances the checked radio input on a 1500ms interval.
- Comment data flow: page.meta.comments flag → comments.html emits a localized prompt + giscus.app script tag with repo/category IDs → giscus maps the page pathname to a GitHub Discussion → theme changes are pushed back via postMessage to the giscus iframe.
- CI data flow: push/PR events filtered on paths 'codes/<lang>/**' and 'en/codes/<lang>/**' trigger the matching workflow; the job checks out the repo, sets up the toolchain, then builds or executes every sample in that directory, failing the run on any compile/runtime error.
- Python execution harness: test_all.py globs 'chapter_*/*.py', subprocess.Popens 'python <file>' for each with PYTHONIOENCODING=utf-8, collects stderr per file, and raises RuntimeError aggregating all stderr if any exit code is non-zero — 'Tested N files / Found exception in M files' is the only output.
- JavaScript execution harness: codes/javascript/test_all.js uses Deno APIs (expandGlob 'chapter_*/*.js', Deno.Command 'node') to spawn every sample under node, awaiting all statuses — the CI workflow invokes it via 'deno run -A test_all.js'.
- Helper-module data flow: chapter samples import shared structures (e.g. 'use hello_algo_rust::include::print_util' in array.rs, 'from modules import *' style in Python) so TreeNode/ListNode/Vertex construction and printing flow through one module per language, keeping sample files focused on the algorithm.
- Rendered pages pull external assets at view time: MathJax from cdnjs.cloudflare.com, giscus client from giscus.app, contributor image from contrib.rocks, PythonTutor frames from pythontutor.com — declared in mkdocs.yml extra_javascript, comments.html, docs/index.html, and ??? pythontutor blocks respectively.
Behavior traces
Key flows traced end-to-end: (1) the Docker build that produces and serves the five-locale site; (2) the Python CI lane that lints then executes every sample via a glob-and-subprocess harness; (3) a reader's page view, where markdown tabs, animation frames, MathJax and giscus all hydrate client-side; (4) adding a Rust sample, which requires a manual [[bin]] registry entry before cargo run works; and (5) the Go lane where driver code lives in _test.go files executed by 'go test'.
- Docker site-build trace: FROM python:3.10.0-alpine → ENV PIP_INDEX_URL → pip install mkdocs-material==9.5.5 mkdocs-glightbox → COPY overrides ./build/overrides and docs ./build/docs → mkdocs build → for each locale COPY <loc>/docs ./build/<loc>/docs + <loc>/mkdocs.yml → mkdocs build → WORKDIR site → EXPOSE 8000 → CMD python -m http.server 8000.
- Python CI trace (python.yml): paths filter on codes/python/** and en/codes/python/** → matrix os×python-version×code-dir → actions/checkout@v4 → setup-python 3.10 → pip install black → 'black <code-dir>' lint → 'cd <code-dir> && python test_all.py' which globs and subprocess-runs every chapter_*/*.py.
- Reader page-view trace: mkdocs renders the .md page → pymdownx.tabbed emits per-language code tabs and <N> frame tabs → glightbox plugin enables image zoom → mathjax.js re-typesets formulas on navigation → '??? pythontutor' renders a collapsible link → if page.meta.comments, comments.html injects giscus and syncs its theme to the palette.
- Add-a-Rust-sample trace: create codes/rust/chapter_x/foo.rs with a fn main() driver → register a [[bin]] block ('name' + 'path') in codes/rust/Cargo.toml → run 'cargo run --bin foo' locally → CI rust.yml runs 'cargo build' and 'cargo build --release' on ubuntu/macos/windows with the nightly toolchain.
- Go sample trace: sample logic lives in chapter_*/*.go as package chapter_* functions (e.g. randomAccess/extend/insert/remove in array.go); the 'Driver Code' is a TestXxx(t *testing.T) func in a sibling _test.go file that fmt.Printlns each step → 'go build ./...' + 'go test -v ./...' in go.yml exercises it.
- C build trace: root codes/c/CMakeLists.txt sets C11, includes ./utils (or include dir), and add_subdirectory's each chapter; each chapter CMakeLists declares add_executable(<name> <name>.c) per sample → CI c.yml runs cmake -B build with gcc/clang/cl matrix → cmake --build → ctest.
- TypeScript check trace: chapter .ts files are plain scripts with a '// Driver Code' tail; tsconfig.json includes only 'chapter_*/*.ts' with noEmit → 'npm run check' invokes bare tsc → typescript.yml runs npm install + npm run check per OS per code-dir (codes/typescript and en/codes/typescript).
- Docs contribution trace: reader clicks the edit icon rendered by partials/actions.html → edit_uri jumps to github.com/.../tree/main/docs → fork → edit markdown → PR opened → pull_request_template.md forces a checklist choice (translation vs code) and demands console output parity with the Python/Java reference for code PRs.
- Translation pipeline trace: per en/CONTRIBUTING.md, Chinese source docs → AI/LLM first-pass translation → human optimization → PR with two-reviewer approval → merged en/docs tree consumed by the en mkdocs build stage in the Dockerfile.
- Locale-code divergence trace: en/codes mirrors codes/ file-for-file (same 89 .py files for python) but with English comments/docstrings — e.g. en array.py translates '随机访问元素' to 'Random access to element' while keeping identical logic — so every code edit must be applied twice.
Testing signals
Testing is 'does it compile and run' rather than assertion-based verification. Each language has either a run-all harness (Python test_all.py, JS test_all.js), native test drivers used as print harnesses (Go _test.go, ctest), or compile-only checks (Rust cargo build, TypeScript tsc --noEmit, Java javac, C/C++ cmake builds). There are no unit-test assertions on algorithm outputs, no docs/link checking, no site-build CI, and no coverage tooling. Coverage gaps: zig and pythontutor have no workflow at all, and zh-hant/ja/ru code trees are outside every workflow's path filter.
- codes/python/test_all.py is the Python 'test suite': it subprocess-executes every chapter_*/*.py and fails only on non-zero exit codes — no assertion of output content, so crashes are caught but wrong results are not.
- The Python workflow additionally enforces formatting: 'pip install black' then 'black <code-dir>' runs black over the whole directory (applying rewrites, which CI then leaves uncommitted but fails on parse errors).
- codes/javascript/test_all.js is the JS harness: Deno expandGlob over chapter_*/*.js spawning 'node' per file via Deno.Command — also exit-code-only validation.
- Go 'tests' are print-only drivers: e.g. pkg/list_node_test.go's TestListNode builds a linked list and calls PrintLinkedList with no assertions; chapter _test.go files like array_test.go are labeled 'Driver Code' and only fmt.Println results.
- Rust CI is compile-only: rust.yml runs 'cargo build' and 'cargo build --release' — no 'cargo test' and no bin execution — while using the nightly toolchain via brndnmtthws/rust-action-rustup.
- TypeScript CI is type-check-only: npm run check → tsc with noEmit over chapter_*/*.ts; nothing is executed.
- Java CI compiles everything with 'javac -d <dir>/build <dir>/**/*.java' on JDK 11 and 17 — no execution — and is pinned to the retired ubuntu-20.04 runner with actions/setup-java@v3.
- C and C++ CI builds with CMake across gcc/clang/cl on ubuntu+windows and runs 'ctest' — but the CMakeLists only register executables (add_executable), so ctest success effectively means 'built and ran without crashing'.
- Path filters limit each workflow to codes/<lang>/ and en/codes/<lang>/ — changes to zh-hant/codes, ja/codes or ru/codes trigger no CI at all, and docs-only changes never exercise the code.
- zig (codes/zig, ~59 files with build.zig) and pythontutor have no workflow — no .github/workflows/zig.yml exists — so the zig corpus is completely unverified in CI.
- There is no CI job that runs 'mkdocs build' — the docs site, nav integrity, overrides templates and locale INHERIT configs are only exercised by the Docker image build, which itself is not run by any workflow.
- Non-determinism is inherent: samples use randomness (random_access picks random.randint indices, Rust uses rand::thread_rng, Go rand.Intn), which is one reason the harnesses check exit codes rather than golden output. (inferred)
Risk map
The dominant risks are duplication and drift: the same sample logic exists in up to five copies (codes/ + four locale trees) and again inline in the markdown tabs, with only human discipline and PR checklists keeping them consistent. CI has real holes (no zig workflow, no coverage of zh-hant/ja/ru code paths, compile-only checks for several languages). Secondary risks: a subprocess-based runner that executes contributor code, several apparently dead assets (starfield.js, pythontutor-iframe CSS, missing checkin.html), vendored third-party headers, stale GitHub Actions versions/runners, and heavy reliance on external services (giscus, pythontutor.com, CDNs).
- Code/text drift hazard: docs pages embed hand-copied code inside === 'Lang' tabs that duplicate codes/ files (array.md vs array.py); nothing mechanically verifies the inline snippets match the runnable files.
- Five-way duplication across locales: en/codes, zh-hant/codes, ja/codes, ru/codes are full copies of codes/ with translated comments; every fix to a sample must be replicated, and only codes/ + en/codes/ are CI-covered so zh-hant/ja/ru copies can silently break.
- test_all.py executes every contributed .py file via subprocess with the CI runner's full environment — adequate on ephemeral GitHub runners, but any agent running it locally executes all contributor code unsandboxed; it also assumes 'python' resolves on PATH.
- overrides/javascripts/starfield.js (~460 lines, UMD Starfield module) is not referenced by mkdocs.yml extra_javascript and docs/index.html contains no script tag for it — the .starfield div in the landing page renders an empty canvas, making this likely dead/unwired code. (inferred)
- extra.css defines .pythontutor-iframe scaling styles and comments.html includes 'partials/checkin.html' with 'ignore missing' (no such file exists in overrides/partials/) — residual hooks for features that are absent or external. (inferred)
- codes/c/utils/uthash.h is a vendored third-party single-header library shipped in-repo — an unversioned external dependency embedded in the source tree.
- Stale CI infrastructure: java.yml pins runs-on ubuntu-20.04 (a retired GitHub runner image) and uses actions/setup-java@v3; go.yml uses actions/setup-go@v3; rust.yml builds on nightly — all fragile against upstream changes.
- Single Docker build compiles all five locales serially at image-build time (five mkdocs build RUN steps); any locale's docs error fails the entire image and there is no incremental/caching strategy — and no workflow builds this Dockerfile, so site breakages are only caught on manual/deploy builds.
- Runtime third-party dependencies: giscus.app client script, cdnjs MathJax bundle, pythontutor.com render URLs, contrib.rocks images — a service outage or URL-format change degrades comments, math, visualizations, and the landing page with no fallback.
- python -m http.server is the production server inside the Docker image — a development-grade server (no TLS, caching, or compression), acceptable for static files but a scaling/security ceiling for hello-algo.com if used as-is. (inferred)
- Manual registries are easy to forget: a new Rust sample fails cargo build unless a [[bin]] is added to Cargo.toml, and a new C/C++ file needs add_executable in the chapter CMakeLists — CI will catch it, but only after push.
- License is CC BY-NC-SA 4.0 for all content including code — non-commercial share-alike; downstream reuse of the sample code is more restrictive than typical OSS licenses and worth flagging before repurposing.
Extension points
The repo is built to be extended in five dimensions: new programming languages (add a codes/<lang> mirror + workflow + docs tabs), new chapters/sections (docs/chapter_x + nav entry + per-language code dirs), new locales (copy tree + INHERIT config + Dockerfile stage + alternate entry), new page features (custom admonition types, animation frame sets, pythontutor embeds), and theme behavior (override partials + CSS/JS). Some extension is registry-driven (Cargo.toml [[bin]], CMakeLists add_executable, mkdocs.yml nav) while the run-all harnesses auto-discover files via chapter_* globs.
- Add a new programming language: create codes/<lang>/chapter_* mirrors of the sample set, a modules/pkg/utils helper dir, a manifest (go.mod/package.json/Cargo.toml/.csproj/CMakeLists/build.zig pattern), a .github/workflows/<lang>.yml path-filtered to codes/<lang> and en/codes/<lang>, plus a === '<Lang>' tab in every docs code block and a README badge.
- Add a new chapter or page: create docs/chapter_x/*.md (+ <page>.assets/ for images), register it in the nav tree in mkdocs.yml, and mirror it across locale docs trees and codes/<lang>/chapter_x directories.
- New Rust samples plug in via the Cargo.toml [[bin]] registry — each entry maps a bin name to a chapter_*/*.rs path with a '# Run Command: cargo run --bin <name>' comment; shared helpers go in codes/rust/src/include/ exposed through src/lib.rs.
- New C/C++ samples plug in via per-chapter CMakeLists add_executable lines; a whole new chapter requires an add_subdirectory line in the root codes/c/CMakeLists.txt.
- New locale: copy a locale tree, write a mkdocs.yml starting with 'INHERIT: ../mkdocs.yml' overriding site_name/site_url/docs_dir/site_dir/theme.language, add the language to extra.alternate, and add a COPY+mkdocs-build stage in the Dockerfile.
- Run-all harnesses auto-discover new files: test_all.py (glob 'chapter_*/*.py') and test_all.js (expandGlob 'chapter_*/*.js') pick up added samples with no registry edit — unlike Rust/C/C++ which need manifest entries.
- New callout types are added via CSS: extra.css defines --md-admonition-icon--pythontutor and .admonition.pythontutor/details.pythontutor styles; the same pattern extends to new '??? <type>' admonitions.
- New animations need no code: any tabbed set whose labels are all '<N>' is auto-detected by animation_player.js's isAnimationSet() and upgraded to a slideshow — authors just add sequential frame PNGs as === '<k>' tabs.
- Theme surface is extensible through Material's override blocks: main.html extends base.html (announce block), partials/{actions,comments,content}.html slot into content rendering — new per-page chrome plugs in here rather than by forking the theme.
- Page-level feature flags via front matter: comments.html keys off page.meta.comments and content.html checks page.meta.hide for action buttons — new pages opt into features declaratively.
- pymdownx.snippets is enabled in mkdocs.yml but no docs page uses the --8<-- include syntax — an available-but-unused extension point that could replace manual code transcription. (inferred)
- overrides/zensical/ is the forward extension path: zensical.toml + its own javascripts/stylesheets dirs define an alternate site build (Zensical SSG) where animation_player.js and animation_player.css already live — new interactive features land there first.
Contributor handoff
This is a content monorepo, not an app — treat it as five parallel trees (root zh + en, zh-hant, ja, ru) over two artifact types (docs markdown, runnable code). Read mkdocs.yml, Dockerfile, and the contribution docs first. The prime directive is consistency: any code change belongs in codes/ AND all locale codes/ copies AND the inline tabs in the docs pages; any structural change (new chapter/language) touches nav, manifests, workflows, and Docker stages together. Validate with the language's own harness before submitting; correctness means 'runs and prints the same results as the Python/Java reference' per the PR template.
- Read these first: mkdocs.yml (nav + build layout), Dockerfile (how all five sites build), docs/chapter_appendix/contribution.md (contribution flow), en/CONTRIBUTING.md (translation standards), .github/pull_request_template.md (required checklists), and the workflow file for whichever language you touch.
- Code file conventions: every sample has a header comment ('File: <name> / Created Time: <date> / Author: <name> (<email>)') and ends with a driver section — '"""Driver Code""" + if __name__ == "__main__":' in Python, '/* Driver Code */ func TestXxx(t *testing.T)' in Go, fn main() in Rust.
- Language of comments matters: codes/ and zh-hant/codes/ use Chinese comments; en/codes/ uses English translations of the same comments — match the locale's language when editing, don't mix.
- When editing a sample, update in lockstep: the codes/<lang>/ file, the matching en/zh-hant/ja/ru copies, the === 'Lang' tab block in the corresponding docs/<chapter>/<page>.md, and any codes/pythontutor/ URL that embeds that function's source.
- Local validation per language: python → 'black codes/python && cd codes/python && python test_all.py'; go → 'go build ./... && go test ./...'; rust → add [[bin]] then 'cargo build'; typescript → 'npm run check'; javascript → 'deno run -A test_all.js'; c/cpp → cmake -B build && cmake --build && ctest.
- Local site builds need the staged layout: mkdocs.yml points docs_dir at build/docs and custom_dir at build/overrides, so 'mkdocs serve' alone fails — replicate the Dockerfile's COPY steps (mkdir -p build && cp -r docs build/docs && cp -r overrides build/overrides) or just 'docker-compose up -d'.
- Trap — registries must stay in sync when adding/removing files: Cargo.toml [[bin]] entries, chapter CMakeLists add_executable lines, and the mkdocs.yml nav tree all reference files by name; a renamed or deleted sample breaks builds three ways.
- Trap — docs/index.html and docs/index.md coexist at docs root: the .html is the real hand-crafted landing page (hero + starfield + reviewer grid) while index.md is a 3-line stub; edit the HTML file for homepage changes.
- Safe-edit boundary: single-page markdown text fixes are low-risk (path filters skip CI anyway); code edits are medium-risk (5-tree sync); structural changes (new chapter/language/locale) are high-touch — nav, manifests, workflows, Dockerfile stages, and all locale trees change together. (inferred)
- Samples must stay self-contained and side-effect-free: files import only stdlib plus the language's own modules/pkg/include utils, print their results to stdout, and must exit 0 — the harnesses treat any crash as failure and there is no mocking/stubbing infrastructure.
- Output parity is the review standard: the PR template requires code transpilation PRs to attach console output proving it matches the Python or Java reference implementation — reproduce that locally before proposing changes.
Languages
| Language | Files | Share of source |
|---|---|---|
| Markdown | 871 | docs/config |
| Go | 695 | 13% |
| Swift | 455 | 8% |
| C++ | 450 | 8% |
| Rust | 450 | 8% |
| Python | 445 | 8% |
| C# | 440 | 8% |
| Java | 435 | 8% |
Start reading here
Probable source entrypoint: codes/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
codes/ (768 files) ru/ (768 files) ja/ (768 files)
Source layout — codes/
| Path | Files |
|---|---|
codes/c/ | 100 |
codes/cpp/ | 106 |
codes/csharp/ | 87 |
codes/go/ | 36 |
codes/Dockerfile | 1 |
Repository structure
| Top-level path | Files |
|---|---|
codes/ | 768 |
ru/ | 768 |
ja/ | 768 |
en/ | 768 |
zh-hant/ | 767 |
docs/ | 123 |
overrides/ | 16 |
.github/ | 14 |
Docs found: README.mddocs/chapter_appendix/contribution.mddocs/chapter_appendix/index.mddocs/chapter_appendix/installation.mddocs/chapter_appendix/terminology.mddocs/chapter_array_and_linkedlist/array.mddocs/chapter_array_and_linkedlist/exercises.mddocs/chapter_array_and_linkedlist/index.mddocs/chapter_array_and_linkedlist/linked_list.mddocs/chapter_array_and_linkedlist/list.md
Package
codes/go/go.mod — github.com/krahets/hello-algo, 0 declared dependencies.
CI & config entrypoints
README.md— Repository readme.github/workflows/c.yml— GitHub Actions workflow.github/workflows/cpp.yml— GitHub Actions workflow.github/workflows/dart.yml— GitHub Actions workflow.github/workflows/dotnet.yml— GitHub Actions workflow.github/workflows/go.yml— GitHub Actions workflow.github/workflows/java.yml— GitHub Actions workflow.github/workflows/javascript.yml— GitHub Actions workflow.github/workflows/kotlin.yml— GitHub Actions workflow.github/workflows/python.yml— GitHub Actions workflow
Structural health signals
Average score 7.1/10 across 96 analyzed source files; 7 hotspots surfaced.
codes/rust/chapter_tree/avl_tree.rs— 297 lines, score 6.2 (Deep nesting, Long function/block)en/codes/rust/chapter_tree/avl_tree.rs— 297 lines, score 6.2 (Deep nesting, Long function/block)ja/codes/rust/chapter_tree/avl_tree.rs— 297 lines, score 6.2 (Deep nesting, Long function/block)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
28c1e74c1d352026-08-18 — Add multilingual exercise code (#1959)bf86c39b6c802026-08-18 — Fix multilingual content typos (#1958)69932aed18912026-07-24 — Remove Warp sponsorship and refine endorsement cards (#1953)69acdc5bf3772026-07-22 — Refine Zensical callout backgrounds (#1951)a3166c2018532026-07-19 — Simplify generated exercise page sources (#1943)