If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/changkun/modern-cpp-tutorial shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 49+ active contributors
• Distributed ownership (top contributor 32% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live changkun/modern-cpp-tutorial repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/changkun/modern-cpp-tutorial.

What it runs against: a local clone of changkun/modern-cpp-tutorial — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in changkun/modern-cpp-tutorial | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 659 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of changkun/modern-cpp-tutorial. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/changkun/modern-cpp-tutorial.git
#   cd modern-cpp-tutorial
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of changkun/modern-cpp-tutorial and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "changkun/modern-cpp-tutorial(\\.git)?\\b" \\
  && ok "origin remote is changkun/modern-cpp-tutorial" \\
  || miss "origin remote is not changkun/modern-cpp-tutorial (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "book/en-us/toc.md" \\
  && ok "book/en-us/toc.md" \\
  || miss "missing critical file: book/en-us/toc.md"
test -f "code/2/Makefile" \\
  && ok "code/2/Makefile" \\
  || miss "missing critical file: code/2/Makefile"
test -f "book/en-us/01-intro.md" \\
  && ok "book/en-us/01-intro.md" \\
  || miss "missing critical file: book/en-us/01-intro.md"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 659 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~629d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/changkun/modern-cpp-tutorial"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A comprehensive bilingual (English/Chinese) tutorial book teaching modern C++ features (C++11/14/17/20) through code examples and historical context. It's published as Markdown files in book/en-us/ and book/zh-cn/, rendered via Hexo static site generator, with accompanying runnable C++ code samples organized by chapter in the code/ directory. Dual-tree structure: book/en-us/ and book/zh-cn/ contain 11 Markdown chapters (00-preface through 10-cpp20 plus appendices) and a toc.md for navigation. code/ directory holds executable C++ examples organized by chapter. Build orchestrated by Makefile and Hexo config (package.json specifies generators, renderers, and dev server via serve). GitHub Actions in .github/workflows/website.yml auto-deploys the static site.

Experienced C++98/03 developers who want to quickly learn modern C++ features without deep theory; students and professionals migrating legacy C++ codebases to contemporary standards; anyone seeking a fast-track introduction to C++11–C++20 with working code examples.

This is an actively maintained, production-ready educational resource. The second edition is published with PDF/EPUB/web distribution. The Hexo+GitHub Pages setup with CI/CD via .github/workflows/website.yml indicates professional deployment. Regular updates across both language versions suggest active maintenance, though commit recency data isn't visible in this snapshot.

Low operational risk for a static educational resource. Hexo has 6 dependencies (mostly stable renderers like hexo-renderer-marked v4.0.0). Single-maintainer repo (changkun) means content updates depend on one person, but the project is a book, not a live service. Breaking changes in Hexo or Node.js could affect build process, but the site itself is immutable once published.

No specific recent activity visible in the provided file listing, but the repo actively distributes the tutorial across multiple formats (website via CI/CD, PDF, EPUB). The CODE_OF_CONDUCT.md, CONTRIBUTING.md, and GitHub issue/PR templates indicate ongoing community engagement and a framework for accepting contributions.

git clone https://github.com/changkun/modern-cpp-tutorial.git
cd modern-cpp-tutorial
npm install
npm run server  # or check Makefile for alternatives

Daily commands: Development server: npm install && npm run server (starts Hexo dev server on localhost, likely port 4000). Build for production: make or equivalent Hexo build command (generates static site in public/). Check Makefile for exact targets.

• README.md — Primary entry point explaining the tutorial's purpose, scope (C++11/14/17/20), and structure; essential for understanding project goals and intended audience.
• book/en-us/toc.md — Table of contents organizing all learning modules; required to understand how chapters map to code examples and dependencies.
• code/2/Makefile — Build configuration for the largest code module (Chapter 2: Usability); demonstrates compilation patterns used across all C++ examples.
• book/en-us/01-intro.md — Introduction chapter establishing historical context and rationale for modern C++ features; foundational reading for understanding design decisions.
• Makefile — Root build orchestration file; controls how the entire tutorial (book generation + code compilation) is built and deployed.
• .github/workflows/website.yml — CI/CD pipeline configuration for automated documentation generation and deployment; critical for maintaining published tutorial accessibility.
• package.json — Hexo static site generator configuration; specifies all dependencies for rendering markdown chapters as a website.

Add a new C++ code example for a feature

1. Create a new .cpp file in the appropriate chapter directory (e.g., code/2/ for usability features) following naming convention: chapter.section.feature.cpp (code/2/2.21.new-feature.cpp)
2. Add compilation rule to the chapter's Makefile with target name matching the feature (code/2/Makefile)
3. Write corresponding section in the English chapter markdown, explaining the feature's historical motivation and use case (book/en-us/02-usability.md)
4. Translate and add the same section to the Chinese chapter markdown (book/zh-cn/02-usability.md)
5. Verify the example compiles by running make -C code/2 and commit with reference to the book sections updated

Add a new chapter covering a C++ topic

1. Create markdown file in book/en-us/ and book/zh-cn/ following naming pattern: NN-topic.md (e.g., 11-metaprogramming.md) (book/en-us/11-metaprogramming.md)
2. Add entries to both toc.md files to register the chapter in navigation (book/en-us/toc.md)
3. Create code/N/ directory and Makefile for chapter examples (code/11/Makefile)
4. Add chapter-specific compilation rules to root Makefile if needed (Makefile)
5. Submit PR with all book sections, code examples, and CI verification passing

Maintain and publish the website

1. Run npm install to install Hexo and dependencies from package.json (package.json)
2. Edit book content in markdown (book/en-us/ and book/zh-cn/) and test locally with hexo serve (book/en-us/toc.md)
3. Verify all C++ examples compile successfully by running Make in code/ directories (code/2/Makefile)
4. Push to master branch; GitHub Actions automatically runs .github/workflows/website.yml to build and deploy (.github/workflows/website.yml)

• Hexo Static Site Generator — Converts markdown chapters into a fast, SEO-friendly website without backend server complexity; perfect for educational documentation with multi-language support.
• GitHub Actions CI/CD — Automates testing (C++ compilation verification) and deployment on every commit, ensuring examples remain working and site stays up-to-date.
• GNU Make — Standard build system for compiling C++ examples to verify correctness; familiar to systems programmers and requires no additional toolchain.
• Markdown + Multi-language Structure — Human-readable source format; parallel English/Chinese directories enable community translation while avoiding divergence.

• Static HTML site generation via Hexo rather than dynamic backend

  • Why: Educational content changes infrequently; static hosting is cheaper, faster (CDN-friendly), and eliminates server maintenance.
  • Consequence: Cannot offer interactive features like user comments or progress tracking; all content updates require rebuild and redeploy.

• Separate English and Chinese markdown trees (book/en-us/ and book/zh-cn/) rather than single-source translation

  • Why: Allows translators to localize explanations and examples without blocking English updates.
  • Consequence: Content divergence risk if translations lag; requires discipline to keep both synchronized and tested.

• Example code embedded in separate .cpp files compiled independently, not inline in markdown

  • Why: Guarantees examples compile correctly; readers can run them locally; Makefile rules serve as documentation.
  • Consequence: Reader must navigate between markdown explanation and separate code files; increased cognitive load.

• No interactive sandbox or playground (e.g., Compiler Explorer embedded)

  • Why: Simplifies deployment and avoids third-party API dependencies; keeps site lightweight and works offline.
  • Consequence: Readers must set up local compiler to run examples; higher barrier to quick experimentation.

• Does not provide a live coding playground or online compiler; readers must compile examples locally or use external tools.
• Does not track reader progress, bookmarks, or learning analytics; purely static, stateless content.
• Does not offer video tutorials or interactive exercises; text-based learning only.
• Does not provide a real-time forum or Q&A system; issues and discussions occur via GitHub.
• Does not support C++23+ features (covers up to C++20); scope is intentionally capped at early 2020s.
• Not a reference manual or complete language specification; emphasizes historical context and modern idioms over exhaustive feature documentation.

Hexo templating: EJS templates in the build require correct syntax; malformed EJS will fail silently during rendering. Language sync: English and Chinese chapters must be kept in parallel; missing translations in either tree will break the bilingual navigation. C++ compiler version: Code examples assume a modern C++ compiler (GCC 7+, Clang 5+, MSVC 2017+) supporting C++11 through C++20; older toolchains will fail. Node.js version compatibility: Hexo 5.3.0 may have upper-bound version requirements; very recent Node.js versions could break package installation.

• Move semantics and RValue references — Core C++11 feature enabling efficient resource transfer without copies; essential for modern C++ performance and memory safety that this tutorial teaches in chapter 03-runtime.md.
• Template metaprogramming (TMP) and SFINAE — Advanced compile-time computation technique used throughout modern C++ libraries; tutorial covers this to help readers understand generic code patterns in the standard library.
• RAII (Resource Acquisition Is Initialization) — Foundational C++ pattern for automatic resource management that modern C++ (smart pointers, scoped_lock) builds upon; critical for memory safety without garbage collection.
• Variadic templates and fold expressions — C++11/17 feature for writing generic functions accepting any number of arguments; enables type-safe metaprogramming central to modern C++ library design.
• Coroutines (Stackless concurrency) — C++20 feature for lightweight async/await-style concurrency; tutorial's chapter 10-cpp20.md covers this paradigm-shifting capability for high-performance I/O.
• Concepts (Template constraints) — C++20 feature for declaring and enforcing template requirements at compile-time; makes generic code more readable and error messages more helpful than traditional SFINAE.
• Structured bindings and pattern matching — C++17 syntax sugar for decomposing tuples and aggregates into named variables; improves code readability and reduces boilerplate in modern C++ applications.

• isocpp/CppCoreGuidelines — Official C++ Core Guidelines by Bjarne Stroustrup and Herb Sutter; definitive reference for modern C++ best practices that align with this tutorial's philosophy.
• cppreference/cppreference-doc — Comprehensive C++ standard library and language reference; complements this tutorial's feature explanations with detailed API documentation.
• lefticus/cppbestpractices — Runnable examples and guidelines for idiomatic modern C++; parallels this repo's goal of teaching C++11/14/17 conventions through concrete code.
• facebook/folly — Production-grade C++ library showcasing advanced modern C++ patterns and idioms in real-world scale; reference for how tutorial concepts apply in large codebases.
• changkun/go-under-the-hood — Companion tutorial by the same author explaining Go internals; demonstrates the author's pedagogical approach to systems programming education.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add automated code compilation and execution tests in CI workflow

The repo contains 50+ C++ code examples in the code/ directory (code/1/, code/2/, ... code/10/) with Makefiles, but there's no CI workflow that validates these examples compile and run correctly. Currently, .github/workflows/website.yml only builds the Hexo website. Adding a C++ compilation workflow would catch regressions when examples break due to outdated syntax, missing includes, or incorrect output.

• [ ] Create .github/workflows/cpp-examples.yml that compiles all code examples using the existing Makefiles in each code/* directory
• [ ] Add matrix strategy to test across multiple C++ standards (C++11, C++14, C++17, C++20) using GCC and Clang
• [ ] Verify example output matches expected results by capturing stderr/stdout from each compiled program

Create comprehensive example index with metadata and difficulty levels

The code/ directory has ~50 examples (e.g., 2.01.nullptr.cpp, 10.2.concepts.cpp) but no centralized index mapping these to book chapters or difficulty levels. Contributors struggle to find which example corresponds to which section in book/en-us/ and book/zh-cn/. A structured index (JSON or YAML) would improve navigation and help maintain consistency between code examples and documentation.

• [ ] Create code/index.json with entries mapping each .cpp file to its book chapter, section number, C++ standard, and difficulty level (beginner/intermediate/advanced)
• [ ] Add validation script to ensure all .cpp files in code/* are referenced in index.json
• [ ] Update README to link to this index and explain how examples relate to book sections

Add missing appendix3.md translation to English version

The Chinese version (book/zh-cn/) has 13 markdown files including appendix3.md, but the English version (book/en-us/) only has 12 files (missing appendix3.md). This creates an incomplete English tutorial. Translating and integrating appendix3.md into the English book would provide parity between both language versions.

• [ ] Examine book/zh-cn/appendix3.md to understand its content and scope
• [ ] Translate appendix3.md to English, maintaining consistent terminology and style with existing English chapters (e.g., book/en-us/appendix1.md and appendix2.md)
• [ ] Update book/en-us/toc.md to include the new appendix3.md entry and rebuild website to verify rendering

• Add missing code examples for C++20 chapter (book/en-us/10-cpp20.md exists but code/10-cpp20/ may be incomplete); implement working samples for concepts, coroutines, modules.
• Create exercise solutions documentation (exercises/ directory exists but likely lacks annotated solutions); write step-by-step explanations for end-of-chapter problems in both English and Chinese.
• Translate or verify consistency of figures and ASCII diagrams between English and Chinese editions (assets/figures/ has some language-specific variants like pointers1_en.png; ensure all diagrams are localized).

This is a documentation/tutorial repository with moderate security concerns. The primary risks are outdated npm dependencies (Hexo, marked renderer) which could contain known vulnerabilities. The repository itself is low-risk for injection attacks due to its nature as a static site with educational C++ code examples. However, the build pipeline dependencies need immediate attention. Recommendations include upgrading all npm packages to current versions and implementing security headers for the deployed website. The absence of a visible lock file and lack of security configuration in deployment are secondary concerns.

• Medium · Outdated Hexo Dependency — package.json - devDependencies.hexo. The package.json specifies hexo version ^5.3.0, which is outdated. Hexo 5.x reached end-of-life and may contain known security vulnerabilities. Current stable versions are 6.x or 7.x. Fix: Update hexo to the latest stable version (currently 7.x). Run 'npm update hexo' and test the website generation thoroughly.
• Medium · Outdated hexo-renderer-marked Dependency — package.json - dependencies.hexo-renderer-marked. The hexo-renderer-marked package version ^4.0.0 is outdated. The marked library (which this renderer depends on) has had XSS vulnerabilities in past versions. Current versions are 11.x or higher. Fix: Update hexo-renderer-marked to the latest compatible version and verify marked library is at version 11.x or higher to mitigate XSS risks in markdown rendering.
• Low · Outdated hexo-renderer-stylus Dependency — package.json - dependencies.hexo-renderer-stylus. The hexo-renderer-stylus version ^2.0.1 is outdated and may lack security patches. No active maintenance evident for this plugin. Fix: Consider updating or replacing with maintained CSS processing alternatives. Evaluate if stylus is still necessary for the project.
• Low · Missing Security Headers Configuration — .github/workflows/website.yml (presumed) or deployment configuration. No evidence of security header configuration in the website deployment. The GitHub Actions workflow file (.github/workflows/website.yml) is not fully visible, but static sites should include security headers (CSP, X-Frame-Options, etc.). Fix: Configure security headers in the web server or via deployment platform. At minimum, set Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, and Strict-Transport-Security headers.
• Low · No Dependency Lock File Visible — Repository root. No package-lock.json or yarn.lock file is shown in the file structure. This can lead to non-deterministic builds and potential supply chain issues if dependencies update with breaking changes. Fix: Ensure package-lock.json (or yarn.lock) is committed to the repository and used for CI/CD builds to guarantee consistent dependency versions.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.