mkdocs.yml

site_name: AI Agents in Depth
site_description: AI Agents in Depth — Design Principles and Engineering Practice. An open-source book covering AI Agents from theory to production, with 10 chapters and 94 companion experiments.
site_url: https://bojieli.github.io/ai-agent-book
repo_url: https://github.com/bojieli/ai-agent-book
repo_name: bojieli/ai-agent-book
edit_uri: edit/main

# The actual docs are assembled into `_web/` by `scripts/build_site.sh`
# (only the Markdown sources + images are copied; code/PDFs are left out).
docs_dir: _web

# Strip Pandoc/LaTeX attributes the source Markdown uses (e.g. `{.unnumbered}`,
# `{#sec:foo}`, image `{height=55%}`) which Python-Markdown cannot parse.
hooks:
  # `_web/` is an ignored staging tree, so map each staged page back to its
  # tracked source before the revision-date plugin asks Git for timestamps.
  - scripts/git_revision_dates.py
  # `_web/` promotes book/chapterN.md to book/chapterN/index.md, a path that
  # does not exist in the repository. Retarget the "edit this page" / "view
  # source" buttons at the tracked source so they don't 404 (issue #1019).
  - scripts/site_edit_urls.py
  # Validates every configured language and generates the browser-side
  # translation catalog from Material's locales + our book navigation labels.
  - scripts/site_i18n.py
  - scripts/mkdocs_pandoc_strip.py
  - scripts/seo_meta.py
  # Splits the search plugin's single 55 MB search_index.json into one file
  # per book edition. Runs last: MkDocs appends `hooks:` to the plugin list,
  # so this sees the index the search plugin just wrote.
  - scripts/split_search_index.py

theme:
  name: material
  language: zh
  # Custom overrides: injects the language-tab switcher into the header.
  custom_dir: overrides
  logo: assets/logo.svg
  favicon: assets/logo.svg
  # Brand colours — indigo accent matches the book cover and SVG figures.
  font:
    text: Noto Sans SC, -apple-system, BlinkMacSystemFont, Helvetica, Arial, sans-serif
    code: JetBrains Mono, SFMono-Regular, Consolas, monospace
  icon:
    logo: material/robot-outline
    repo: fontawesome/brands/github
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/weather-night
        name: 切换夜间模式
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/weather-sunny
        name: 切换日间模式
  features:
    # ── Navigation ──────────────────────────────────────────────
    # Two-sidebar layout: the left sidebar is the BOOK structure only
    # (a clean chapter tree), the right sidebar is the CURRENT PAGE
    # outline. Do NOT use navigation.tabs — that would cram all 10
    # chapters into a horizontal bar. Do NOT use toc.integrate — it
    # folds each chapter's ~40-heading outline into the left sidebar,
    # burying chapters 3-10 below the fold.
    - navigation.instant         # SPA-like page swaps, no full reload
    - navigation.instant.progress # show a loading bar on slow swaps
    - navigation.tracking        # URL changes with scroll
    - navigation.sections        # group nav entries into titled sections
    # navigation.expand OFF — with it on, all chapter subtrees are force-
    # expanded and can't be collapsed (clicking the title does nothing).
    - navigation.indexes         # chapter title = link to the chapter prose.
    # Requires each chapter section's first child to be an index page;
    # scripts/build_site.sh promotes book/chapterN.md to
    # book/chapterN/index.md (the URL /book/chapterN/ is unchanged).
    # The collapse chevron next to the title still toggles the subtree.
    - navigation.top             # "back to top" button
    - navigation.footer          # prev/next pager in footer
    # ── Table of contents (right sidebar) ──────────────────────
    - toc.follow                 # TOC tracks scroll position
    # ── Content ─────────────────────────────────────────────────
    - content.code.copy          # copy button on code blocks
    - content.code.annotate      # rendered annotations in code
    - content.action.edit        # "edit this page" pencil
    - content.action.view        # "view source" link
    - content.tooltips           # rich hover tooltips
    - content.tabs.link          # sync same-named tabs across page
    # ── Search ─────────────────────────────────────────────────
    - search.suggest             # autocomplete-style suggestions
    - search.highlight           # highlight matches in results
    - search.share               # shareable search URLs

plugins:
  # Default Material plugins, made explicit so we can tune them.
  - search:
      lang:
        - ja          # CJK-aware tokenizer; far better for Chinese than `en`
        - ko          # Korean tokenizer for the Korean edition
        - en
        - ar
  # Stamp each page with its git commit date — readers see "最后更新" trust signal.
  - git-revision-date-localized:
      enable_creation_date: true
      enable_git_follow: false   # avoids noisy "First revision older than last" warnings
      type: date
      fallback_to_build_date: true
  # Auto-generate Open Graph / Twitter card images so links look rich when
  # shared to WeChat / Twitter / Slack.
  - social:

markdown_extensions:
  - admonition
  - attr_list
  # Render the book's `[^label]` citations as superscript links with a
  # collected reference list at the bottom of each page (issue #328).
  - footnotes
  - md_in_html
  - toc:
      permalink: true
      # Default slugify drops CJK, so Chinese headings collapse to useless ids
      # (`蒸馏：提升样本效率` -> `_1`). pymdownx's slugify keeps them and matches
      # GitHub's anchors, so in-page section links work in both places.
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences:
      # Render ```mermaid blocks as <div class="mermaid">…</div> so the
      # mermaid.js runtime (loaded below in extra_javascript) picks them up.
      # fence_div_format wraps raw content in a <div class="...">, which is
      # exactly what mermaid.js expects. Any other fenced language still
      # uses the default highlighted <pre><code>.
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_div_format
  - pymdownx.inlinehilite
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.details

extra_javascript:
  # Generated into _web/ by scripts/site_i18n.py during each MkDocs build.
  - extras/site-i18n.generated.js
  - extras/lang-switcher.js
  # Must load after lang-switcher.js: it appends to the menu the switcher
  # builds, and relies on `window.langSwitcher` to map the current page to
  # the English edition.
  - extras/auto-translate.js
  - extras/nav-collapse.js
  - https://unpkg.com/mermaid@11/dist/mermaid.min.js
  - extras/mermaid-init.js
  # mathjax.js must load first: it sets the `window.MathJax` config that
  # the MathJax bundle reads at startup (see the file header).
  - extras/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

extra_css:
  - extras/lang-switcher.css
  - extras/auto-translate.css
  - extras/book-theme.css

# Language definitions for the switcher tab bar.
# Each entry maps its prefix + suffix rules to rewrite URLs across editions.
extra:
  languages:
    # `prefix` and `suffix` apply to chapter prose (book*/chapterN[.suffix]/).
    # `readmeSuffix` is the URL slug used for the per-language experiment
    # index page (chapterN/README.<readmeSuffix>/), which mkdocs renders
    # from the source file README.<suffix>.md.
    zh:   { label: 中文,      prefix: book/,      default: true }
    zhtw: { label: 繁體中文（台灣）, prefix: book-zhtw/, suffix: .zhtw,  readmeSuffix: zh-TW }
    en:   { label: English,   prefix: book-en/,                   readmeSuffix: en }
    es:   { label: Español,   prefix: book-es/,   suffix: .es,   readmeSuffix: es }
    id:   { label: Bahasa Indonesia, prefix: book-id/,            readmeSuffix: id }
    ru:   { label: Русский,    prefix: book-ru/,                   readmeSuffix: ru }
    ta:   { label: தமிழ்,      prefix: book-ta/,   suffix: .ta,   readmeSuffix: ta }
    vi:   { label: Tiếng Việt, prefix: book-vi/,   suffix: .vi,   readmeSuffix: vi }
    ja:   { label: 日本語,     prefix: book-ja/,   suffix: .ja,   readmeSuffix: ja }
    ko:   { label: 한국어,     prefix: book-ko/,   suffix: .ko,   readmeSuffix: ko }
    ar:   { label: العربية,    prefix: book-ar/,   suffix: .ar,   readmeSuffix: ar }
    tr:   { label: Türkçe,      prefix: book-tr/,   suffix: .tr,   readmeSuffix: tr }
    hu:   { label: Magyar,      prefix: book-hu/,                   readmeSuffix: hu }
    he:   { label: עברית,       prefix: book-he/,   suffix: .he }

  # Tier 3 — languages the book has no edition for. Selecting one loads
  # translate.js (MIT, https://github.com/xnx3/translate) on demand and
  # machine-translates the English edition in the browser. See
  # extras/auto-translate.js for why it is opt-in, lazy, and always labelled.
  #
  # This is explicitly a lesser tier than the 14 built editions: figures stay
  # in English (they are <img> SVGs, unreachable from page scripts) and the
  # text is unreviewed. Anything worth shipping properly should get a real
  # edition instead.
  auto_translate:
    label: 机器翻译 / Machine translation
    # The edition to translate *from*: MT out of English beats MT out of
    # Chinese for most targets, and that edition is reviewed. `source` is the
    # site language code; `sourceLanguage` is translate.js' name for it.
    source: en
    sourceLanguage: english
    # Free, keyless channel. NOT `client.edge`: that channel authenticates
    # against https://edge.microsoft.com/translate/auth, an undocumented Edge
    # browser endpoint that now returns 404, so it fails for every visitor.
    # `giteeAI` posts to giteeai.zvo.cn/translate.json (verified working,
    # keyless) and fails over to two backup hosts on its own.
    # Alternatives: `siliconflow`, or `translate.service` against a self-host.
    service: giteeAI
    # translate.js' MutationObserver (translate.listener.start) throws
    # "Cannot read properties of null (reading 'nodeValue')" against Material's
    # navigation.instant DOM swaps, and queues a redundant translation pass per
    # mutation. We re-translate on Material's own `document$` instead, so it
    # stays off unless you explicitly want it.
    listener: false
    # How long a translation pass may go without any sign of life before the
    # notice tells the reader the service is not answering. It is a stall
    # window, not a deadline: every batch that comes back restarts it, and a
    # pass that lands after it expired still clears the warning. The states in
    # between ("translating", "translated") come from translate.lifecycle.
    failureTimeoutMs: 12000
    # Pinned version + SRI hash: this is third-party code from a public CDN,
    # so the exact bytes are fixed. Both must be updated together.
    cdn: https://cdn.staticfile.net/translate.js/3.18.66/translate.js
    integrity: sha384-J3fM1QvC/Px5E8QNZj9KjrYuADHneSN4vCpv//WZPKUVzJocwGpZO/byDiEjaPCL
    # `name` is translate.js' v2 language name (note German is `deutsch`);
    # `locale` becomes the <html lang> attribute.
    languages:
      - { name: french,     label: Français,        locale: fr }
      - { name: deutsch,    label: Deutsch,         locale: de }
      - { name: portuguese, label: Português,       locale: pt }
      - { name: italian,    label: Italiano,        locale: it }
      - { name: polish,     label: Polski,          locale: pl }
      - { name: dutch,      label: Nederlands,      locale: nl }
      - { name: ukrainian,  label: Українська,      locale: uk }
      - { name: czech,      label: Čeština,         locale: cs }
      - { name: romanian,   label: Română,          locale: ro }
      - { name: greek,      label: Ελληνικά,        locale: el }
      - { name: swedish,    label: Svenska,         locale: sv }
      - { name: danish,     label: Dansk,           locale: da }
      - { name: finnish,    label: Suomi,           locale: fi }
      - { name: norwegian,  label: Norsk,           locale: "no" }
      - { name: thai,       label: ไทย,              locale: th }
      - { name: hindi,      label: हिन्दी,             locale: hi }
      - { name: bengali,    label: বাংলা,             locale: bn }
      - { name: malay,      label: Bahasa Melayu,   locale: ms }
      - { name: filipino,   label: Filipino,        locale: fil }
      - { name: swahili,    label: Kiswahili,       locale: sw }
      - { name: urdu,       label: اردو,             locale: ur, dir: rtl }
      - { name: persian,    label: فارسی,            locale: fa, dir: rtl }

nav:
  # The left sidebar is a clean chapter tree. With navigation.indexes,
  # each chapter's index page (book/chapterN/index.md, promoted from
  # book/chapterN.md by scripts/build_site.sh) is attached to its section:
  # clicking the chapter title opens the prose directly, and the chevron
  # expands the subtree to reveal "配套实验" (the experiment index).
  - 首页: index.md
  - 引言: book/introduction.md
  - 第1章 Agent基础知识:
      - book/chapter1/index.md
      - 配套实验: chapter1/README.md
  - 第2章 上下文工程:
      - book/chapter2/index.md
      - 配套实验: chapter2/README.md
  - 第3章 用户记忆和知识库:
      - book/chapter3/index.md
      - 配套实验: chapter3/README.md
  - 第4章 工具:
      - book/chapter4/index.md
      - 配套实验: chapter4/README.md
  - 第5章 CodingAgent与通用Agent:
      - book/chapter5/index.md
      - 配套实验: chapter5/README.md
  - 第6章 交互：观察与动作空间的扩展:
      - book/chapter6/index.md
      - 配套实验: chapter6/README.md
  - 第7章 Agent的评估:
      - book/chapter7/index.md
      - 配套实验: chapter7/README.md
  - 第8章 模型后训练:
      - book/chapter8/index.md
      - 配套实验: chapter8/README.md
  - 第9章 Agent的持续进化:
      - book/chapter9/index.md
      - 配套实验: chapter9/README.md
  - 第10章 多Agent协作:
      - book/chapter10/index.md
      - 配套实验: chapter10/README.md
  - 后记: book/afterword.md
  - 思考题参考答案: book/reference-answers.md