DeepLearning-500-questions Admin Guide

This guide covers what a maintainer, fork operator, translator, or downstream republisher needs to know about scutan90/DeepLearning-500-questions. The repository is a static Markdown book served via docsify, with Chinese as the primary language and a partial English port. There is no application code, no build, no CI, no service. The "system" is text, images, a single static-site index.html, and a copy of docsify.js. Operations are entirely editorial: triaging issues, merging corrections, coordinating translators, and keeping the static site servable.

If you arrived here looking for runtime architecture, stop and read §1.2 first.

1. Executive Summary

1.1 What this system is

1.2 What this system is not

• Not a web application. There is no backend, no database, no API.
• Not a build pipeline. There is no package.json, no requirements.txt, no Makefile, no Dockerfile.
• Not actively maintained. The last commit landed in October 2021. Pull requests are reviewed irregularly.
• Not the same as the print book. The print edition is editorially distinct and commercially licensed.
• Not a runnable curriculum. Unlike microsoft/Web-Dev-For-Beginners or comparable curriculum repos, there are no exercises, no solutions, no quizzes.

1.3 Operational baseline

A fork of this repository requires almost no operations:

1. Host static files on any HTTP server (GitHub Pages, S3 + CloudFront, Netlify, Vercel, plain Nginx).
2. Keep .nojekyll if hosting on GitHub Pages.
3. Periodically merge PRs from translators and editors.
4. (Optional) Pin docsify and KaTeX to local copies if you do not want to depend on unpkg.com and cdn.jsdelivr.net.

There is no log to tail, no service to restart, no metric to monitor, no backup to schedule (the .git history is the backup).

2. Architecture

2.1 System diagram

                                ┌────────────────────────────────┐
                                │     Reader's web browser       │
                                │                                │
                                │  HTML+JS rendered by docsify   │
                                │  KaTeX + MathJax for math      │
                                │  prismjs for code highlighting │
                                └─────────────┬──────────────────┘
                                              │ HTTP GET *.md / *.png
                                              ▼
                          ┌───────────────────────────────────────┐
                          │   Static file server (any HTTP host)  │
                          │                                       │
                          │   Serves:                             │
                          │     index.html         (entry)        │
                          │     docsify.js         (renderer)     │
                          │     _sidebar.md        (nav)          │
                          │     chXX_<topic>/*.md  (chapter text) │
                          │     chXX_<topic>/img/* (figures)      │
                          │     English version/*  (EN port)      │
                          └───────────────────────────────────────┘

                External CDNs the page also pulls from (configurable):
                  unpkg.com         → docsify themes, plugins
                  cdn.jsdelivr.net  → KaTeX (CSS + JS)
                  cdnjs.cloudflare  → MathJax 2.7.5

The reader's browser does all the work. The server is a dumb file host.

2.2 Repository layout

DeepLearning-500-questions/
├── README.md                    # Chinese front matter, JD purchase link, full TOC
├── _sidebar.md                  # Master navigation, 20 chapter entries
├── index.html                   # Docsify configuration (theme, plugins, KaTeX)
├── docsify.js                   # Vendored docsify v4 build (~17K LOC, third-party)
├── 目录预览.md                  # Original Chinese TOC (deprecated alias)
├── 深度学习500问-Tan-00目录.docx   # Print-edition TOC (Word)
├── LICENSE                      # GPL-3.0
├── .nojekyll                    # Disable Jekyll on GitHub Pages
├── .gitignore
├── qun.png                      # WeChat group QR (image referenced from README)
├── Translation Required         # File-named placeholder (no extension)
│
├── ch01_数学基础/
│   ├── readme.md                # Chapter status note
│   ├── modify_log.txt           # Per-chapter contributor log
│   ├── 第一章_数学基础.md        # Chapter 1 main content
│   └── img/ch1/                 # Figures referenced by chapter 1
│
├── ch02_机器学习基础/ ... ch19_软件专利申请及权利保护/
│   (same structure for each: readme.md, modify_log.txt, 第N章_*.md, img/chN/)
│
├── ch07_生成对抗网络(GAN)/
│   └── ch7.md                   # Note: chapter 7 file is named differently
│
├── ch17_模型压缩、加速及移动端部署/
│   ├── 第十七章_*.md             # Main chapter
│   └── 17.8.1 NCNN部署.md       # Supplement on NCNN deployment
│
├── ch18_后端架构选型、离线及实时计算/    # First "chapter 18"
├── ch18_后端架构选型及应用场景/         # Second "chapter 18" (different focus)
│
└── English version/
    ├── README.md                # English front matter, contributor agreement
    ├── ch01_MathematicalBasis/
    ├── ch02_MachineLearningFoundation/
    ├── ch03_DeepLearningFoundation/
    └── ch04_ClassicNetwork/
                                  # Chapters 5–19 not translated

2.3 Per-chapter file conventions

Every chapter folder follows the same shape, with two filename quirks:

Inside each chapter file:

[TOC]



# 第N章 <Topic>

<chapter intro paragraph>

## N.1 <Section title>

### N.1.1 <Subsection title>

**<Bold term>**
<Definition or paragraph>

$$<TeX block formula>$$

> <Optional blockquote>

The [TOC] token is a Typora-only directive — see §4.4.

2.4 Docsify configuration (index.html)

The configuration is small and the entire delivery contract is in this file. Key fields:

External script/style dependencies pulled from CDNs:

Two custom hooks are registered as plugins:

hook.beforeEach(function(content) {
  // Rewrite ../img/foo.png → img/foo.png so that docsify's
  // virtual paths line up with the chapter folder structure
  return content.replace(/..\/img/g, "img");
})

hook.doneEach(function () {
  // After KaTeX runs, queue a MathJax pass for any expressions
  // KaTeX did not render
  window.MathJax.Hub.Queue(["Typeset", MathJax.Hub, document.getElementById('app')]);
})

The beforeEach hook is load-bearing: removing it breaks every chapter image in docsify. Mention it in your fork's CONTRIBUTING if you accept index.html PRs.

2.5 Sidebar (_sidebar.md)

A single Markdown bullet list, 20 entries — one per chapter, plus a "简介" (introduction) entry that points back to the README:

* [简介]()
* [1. 第一章 数学基础](ch01_数学基础/第一章_数学基础.md)
* [2. 第二章 机器学习基础](ch02_机器学习基础/第二章_机器学习基础.md)
* ...
* [20. 第十九章 软件专利申请及权利保护](ch19_软件专利申请及权利保护/第十九章_软件专利申请及权利保护.md)

Notes for editors:

• The numbering in the sidebar (1–20) is display order, not chapter number. Chapter 18 occupies slots 18 and 19 (the two ch18_* folders); chapter 19 is sidebar slot 20.
• The path for chapter 7 is ch07_生成对抗网络(GAN)/ch7.md — not the 第七章_*.md pattern used elsewhere. This is historical.
• Adding a chapter requires editing this file and the README's TOC.

3. System Requirements

3.1 For readers

3.2 For self-hosters

3.3 For editors and translators

Important

Editors on Windows: enable Git's core.quotepath = false to avoid garbled filenames in git status for Chinese-named folders.

git config --global core.quotepath false

3.4 For PDF or print pipelines (out of scope but commonly forked)

Multiple users have requested a downloadable PDF (open issues #393, #481, #376). None ship in the repository today. A working approach for forks:

See §9.4 for a working Pandoc invocation.

4. Configuration

4.1 Docsify config keys you may want to change

When self-hosting (especially for a translation fork), consider editing the window.$docsify = { ... } block in index.html:

4.2 KaTeX version pinning

index.html pins KaTeX 0.10.0-rc.1. This is eight years old and predates many useful TeX macros (\mathbb, \overset, \boldsymbol work; \gdef and modern \colorbox do not). The MathJax fallback covers the gaps for the existing content but a fork that adds modern math should upgrade:

<!-- Replace these two lines: -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.0-rc.1/dist/katex.min.css">
<script src="https://cdn.jsdelivr.net/npm/katex@0.10.0-rc.1/dist/katex.min.js"></script>

<!-- With current stable: -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css">
<script src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js"></script>

Test all 19 chapters after upgrading; KaTeX has tightened its grammar over the 0.10 → 0.16 jump and a handful of older TeX expressions that worked silently before may now warn.

4.3 MathJax 2.x → 3.x migration

The current site uses MathJax 2.7.5. MathJax 3 is faster but has a different config API. If you upgrade, replace the <script type="text/x-mathjax-config"> block and the loader URL in index.html. The existing doneEach plugin call (MathJax.Hub.Queue(["Typeset", ...])) is MathJax 2 API — the MathJax 3 equivalent is MathJax.typesetPromise([...]).

4.4 Typora and the [TOC] directive

Every chapter file begins:

[TOC]



# 第N章 <Topic>

[TOC] is Typora-specific. Standard Markdown renderers ignore it (display as literal text on GitHub) or refuse it (some preview tools show a warning). Docsify ignores it harmlessly.

If you fork into a strict-Markdown ecosystem (Hugo, Jekyll without plugins, mdBook), strip [TOC] from every chapter on ingestion:

find . -name "第*章_*.md" -o -name "ch7.md" -o -name "17.8.1*.md" \
  | xargs sed -i '/^\[TOC\]/d'

Run it once at fork time, then change the editor convention for new chapters.

4.5 GitHub Pages hosting

The repository ships .nojekyll and is GitHub-Pages-ready out of the box. To enable for a fork:

1. Settings → Pages → Source: main branch / root → Save.
2. Wait ~30 seconds for the first build.
3. Visit https://<user>.github.io/<repo>/.

Caution

Never delete .nojekyll. Without it, GitHub Pages runs Jekyll, and Jekyll hides _sidebar.md (any underscore-prefixed file). The site will appear empty.

The repository is well within GitHub Pages' hosting limits for static content.

Note

GitHub Pages enforces a 1 GB site size limit and a 100 GB / month soft bandwidth limit. The book repository is ~80 MB and far below either threshold.

5. Operations

The repository's ongoing operations are entirely editorial. There is no service to restart, no log to monitor, no incident class beyond "broken link" or "wrong formula".

5.1 Editorial cadence (current state)

The maintainers' last commit landed 2021-10-14. There is no public commitment to an update cadence. Expect:

• PRs reviewed in batches, not on a fixed schedule.
• Some PRs may sit indefinitely (typo fixes especially).
• New-chapter PRs almost certainly require coordination with the editorial team via WeChat or email.

If you fork to revive active maintenance, document a target review SLA in your fork's CONTRIBUTING.md.

5.2 Issue tracker triage

Open issues fall into four buckets. The project uses no labels, so triage is manual.

5.3 Suggested labels for a fork

If you fork and revive triage, a useful label set:

• type:typo — single-character or wording fix
• type:math — formula or derivation correction
• type:image — figure missing, broken, or wrong
• type:translation — relating to the English port
• type:new-content — proposing or contributing a new section
• chapter:01 … chapter:19 — for routing to the right co-editor
• priority:print — issues that affect the print edition (block on editorial review)
• noise — spam, recruitment, off-topic — close on sight

5.4 Pull-request review workflow

For typo and math corrections (the dominant PR class):

1. Verify the diff is only the correction — no whitespace churn, no reformatting, no Typora-introduced line endings.
2. Render the chapter in Typora or docsify and confirm the corrected math/text shows correctly.
3. Compare against a textbook for math claims (Goodfellow, Bishop, Hands-On ML).
4. Merge with a Co-authored-by trailer crediting the reporter if the reporter is not the PR author.
5. Add the contributor's name to the chapter's modify_log.txt (if your fork keeps the log convention).

For new-content PRs:

1. Confirm the section number does not collide with an existing one (search the chapter's # and ## headings).
2. Confirm the math renders in both KaTeX and MathJax.
3. Confirm any new images go under chXX/img/chN/ and use relative paths consistent with the existing chapter.
4. Update _sidebar.md if a new top-level chapter — not needed for new sub-sections.
5. Ensure GPL-3.0 acceptance is implicit (the project is GPL — no separate CLA).

5.5 Translation operations

The English port lives under English version/ and is manually maintained, not auto-generated. There is no translation script, no translation-as-CI workflow, no translation-management tool integration. Implications:

• Each translation PR is a manual port of a chapter.
• The English README explicitly notes Google Translate was used for the bulk port; human editing is encouraged but uneven.
• A non-trivial number of mechanical-translation artifacts exist (e.g. "twenty four" instead of "2.14" in the chapter 2 TOC, "Reinforced Learning" calque).
• Math notation is identical between editions; do not re-LaTeX in the English files.

For a serious translation fork:

A modern alternative — automated translation via a GitHub Action mirroring lesson trees (the co-op-translator pattern used by microsoft/Web-Dev-For-Beginners) — is feasible but was not adopted upstream. A fork can add it; coordinate with maintainers first if you want changes upstreamed.

5.6 Backups

The repository's .git history is its backup. There is no separate database, no upload directory, no user-generated content. To restore: git clone. To preserve indefinitely: archive on Software Heritage or the Internet Archive's GitHub mirror — both already index the repo.

6. Security & Compliance

6.1 Threat model

For a reader-facing static site, the threat model is small. Threats and their mitigations:

There is no user input, no authentication, no authorization, no session, no PII, no cookies in the rendered site. CSRF, SQLi, XSS-via-form, and credential-leak threats do not apply.

6.2 GPL-3.0 implications

The repository is licensed under GNU GPL-3.0. Important consequences for forks and republishers:

• Strong copyleft. Any derivative work distributed externally must also be GPL-3.0 (or a compatible later GPL).
• Source must be available. If you serve the rendered HTML as part of a larger product, you must also make the underlying Markdown source available to recipients.
• No additional restrictions. You cannot relicense to MIT, Apache-2.0, or CC-BY without the consent of every contributor (impossible in practice).
• Pure reading is unrestricted. Reading the book on GitHub or a fork's website triggers no GPL obligations on the reader.

Warning

GPL-3.0 is unusual for a book. Most books use Creative Commons (CC-BY-SA, CC-BY-NC). The GPL-3.0 choice here is best understood as a strong-copyleft signal from the editors. Honor it.

6.3 Image rights

A non-trivial fraction of the figures (LeNet5 architecture diagram, AlexNet diagrams, Inception module diagrams, ResNet residual block, YOLO grid figures, U-Net, etc.) appear to be reproduced from the original papers. The repository does not enumerate the source for each image, and academic-paper figures are not licensed under GPL-3.0 — they remain the copyright of the paper authors and publisher.

For a republishing fork:

1. Audit every figure for provenance.
2. Either obtain permission (often granted for educational use), replace with a re-drawn figure (preferred for commercial use), or remove.
3. For figures clearly redrawn by the editorial team, no action is needed — they inherit GPL-3.0.
4. The print edition presumably negotiated rights; the open repository did not.

Important

If you fork commercially (for sale, for paid courses), audit images before publishing. The GPL-3.0 grant from the editors does not include rights to third-party images they reproduced.

6.4 The print-book copyright

The README notes:

Please respect the authors' intellectual property rights, and copyright. Piracy will be investigated

and links to the JD listing for the print edition. The print book has separate copyright held by the publisher 博文视点 (Boven Vision Point) and the authors. Do not redistribute scanned or PDF copies of the print edition; that is unrelated to the GPL-3.0 license on the open repository.

6.5 External dependencies and supply chain

The site loads remote assets at every page-view from three CDNs:

For a high-stakes fork (corporate intranet, classroom-deployed at scale):

1. Pin each dependency to a specific version (already done — KaTeX is pinned to 0.10.0-rc.1).
2. Consider Subresource Integrity (<script integrity="sha384-...">) — the upstream index.html does not use SRI.
3. Best: download and self-host all CDN assets, then point index.html at local paths.

6.6 Vendored docsify.js

The repository ships a vendored copy of docsify (docsify.js at the root, ~17K LOC). This is not the same as the upstream docsify@4.x — it is a pinned snapshot. Implications:

• No CVE patches will reach this site automatically.
• Behavior is predictable (no "the CDN updated and broke something").
• For active deployments, periodically re-vendor from upstream or switch to the CDN-loaded version (<script src="//unpkg.com/docsify"></script> instead of <script src="docsify.js">).

The current index.html loads docsify.js locally (not via CDN), which is the safer and faster default for offline reading.

6.7 Reporting issues

There is no SECURITY.md. For a security finding (e.g. an XSS in a chapter caused by hand-crafted HTML), file a normal GitHub issue and tag the maintainers. Given the static nature of the content, security findings here are vanishingly rare.

7. Configuration Reference

7.1 index.html complete configuration

The full window.$docsify object as shipped:

window.$docsify = {
  themeColor: '#fc7e09',
  loadSidebar: true,
  maxLevel: 2,
  subMaxLevel: 2,
  auto2top: true,
  alias: {
    '/.*/_sidebar.md': '/_sidebar.md',
  },
  markdown: {
    latexRender: katex.renderToString.bind(katex)
  },
  search: {
    placeholder: 'Type to search',
    noData: 'No Results!',
    paths: 'auto',
    depth: 6
  },
  plugins: [ /* see §2.4 */ ],
  externalLinkTarget: '_target',
  name: '深度学习500问',
  repo: 'https://github.com/scutan90/DeepLearning-500-questions'
}

7.2 _sidebar.md complete contents

* [简介]()
* [1. 第一章 数学基础](ch01_数学基础/第一章_数学基础.md)
* [2. 第二章 机器学习基础](ch02_机器学习基础/第二章_机器学习基础.md)
* [3. 第三章 深度学习基础](ch03_深度学习基础/第三章_深度学习基础.md)
* [4. 第四章 经典网络](ch04_经典网络/第四章_经典网络.md)
* [5. 第五章 卷积神经网络(CNN)](ch05_卷积神经网络(CNN)/第五章_卷积神经网络(CNN).md)
* [6. 第六章 循环神经网络(RNN)](ch06_循环神经网络(RNN)/第六章_循环神经网络(RNN).md)
* [7. 第七章 生成对抗网络(GAN)](ch07_生成对抗网络(GAN)/ch7.md)
* [8. 第八章 目标检测](ch08_目标检测/第八章_目标检测.md)
* [9. 第九章 图像分割](ch09_图像分割/第九章_图像分割.md)
* [10. 第十章 强化学习](ch10_强化学习/第十章_强化学习.md)
* [11. 第十一章 迁移学习](ch11_迁移学习/第十一章_迁移学习.md)
* [12. 第十二章 网络搭建及训练](ch12_网络搭建及训练/第十二章_网络搭建及训练.md)
* [13. 第十三章 优化算法](ch13_优化算法/第十三章_优化算法.md)
* [14. 第十四章 超参数调整](ch14_超参数调整/第十四章_超参数调整.md)
* [15. 第十五章 异构运算、GPU及框架选型](ch15_GPU和框架选型/第十五章_异构运算、GPU及框架选型.md)
* [16. 第十六章 自然语言处理](ch16_自然语言处理(NLP)/第十六章_NLP.md)
* [17. 第十七章 模型压缩、加速及移动端部署](ch17_模型压缩、加速及移动端部署/第十七章_模型压缩、加速及移动端部署.md)
* [18. 第十八章 后端架构选型、离线及实时计算](ch18_后端架构选型、离线及实时计算/第十八章_后端架构选型、离线及实时计算.md)
* [19. 第十八章 后端架构选型及应用场景](ch18_后端架构选型及应用场景/第十八章_后端架构选型及应用场景.md)
* [20. 第十九章 软件专利申请及权利保护](ch19_软件专利申请及权利保护/第十九章_软件专利申请及权利保护.md)

7.3 Files that count against GitHub's "Languages" badge

GitHub's linguist tool counts the vendored docsify.js (~17K LOC) and tags the repository "JavaScript / 99%". This is misleading — the authored code is essentially zero JavaScript. To correct the badge in a fork, add a .gitattributes entry:

docsify.js linguist-vendored=true

After commit, the language detection will weight Markdown more heavily.

7.4 No build configuration exists

The repository ships none of:

• package.json
• Cargo.toml
• requirements.txt
• pyproject.toml
• Gemfile
• Makefile
• Dockerfile
• .github/workflows/*.yml
• .gitlab-ci.yml
• tsconfig.json

That is by design — no build step is needed. If you add a build (e.g. docsify-to-pdf for PDF generation, an MkDocs migration, or a translation-mirror CI job), be conservative: the project's appeal is its simplicity.

8. Security Analysis (deeper)

This section consolidates security topics for fork operators who need a defensible posture for an institutional deployment (university classroom, corporate training, public-library kiosk).

8.1 Attack surface inventory

The single elevated risk is PR review: any maintainer who merges a PR containing inline <script> or <iframe> tags inside chapter Markdown introduces persistent JS that runs in every reader's browser. Docsify renders raw HTML by default.

Defensive checklist for PR review:

• [ ] No <script> tags in the diff.
• [ ] No <iframe> tags.
• [ ] No <object> or <embed>.
• [ ] No javascript: URLs in <a href="..."> or [text](...).
• [ ] No data: URLs that decode to anything other than images.
• [ ] No new external <link rel="stylesheet">.

8.2 External link rot

Many chapters cite external blog posts (CSDN, 知乎, 简书 historically; arxiv.org for papers; the major frameworks' docs). Two common failure modes:

1. Chinese tech-blog deletion. CSDN, 简书, and 知乎 routinely retire posts. An estimated 10–20% of outbound links are now dead.
2. Geo-blocking. Some Chinese-hosted resources 451 from non-CN IP addresses. The link is alive; the reader cannot reach it.

Operationally, run a link-rot crawler quarterly:

# lychee is a fast async link checker
brew install lychee  # or: cargo install lychee
lychee --offline ./ch*/*.md

Replace dead links with Wayback Machine archives when content was preserved, or with arXiv equivalents for paper citations.

8.3 Code of Conduct and moderation

The repository ships no CODE_OF_CONDUCT.md. For a public fork, add one — Contributor Covenant 2.1 is standard. The issue tracker has visible spam (e.g. issue #547) and unmoderated; a CoC plus visible enforcement is the conventional response.

8.4 Patent chapter (chapter 19)

Chapter 19 covers Chinese software-patent application procedure, written from the perspective of Chinese practitioners. The content is informational, not legal advice, and the procedures are PRC-specific. If you fork for non-Chinese audiences, consider:

• Replacing chapter 19 with content for your jurisdiction (USPTO, EPO, JPO, etc.).
• Or removing the chapter entirely with a note in the README explaining the omission.

The chapter does not present a security risk; it is flagged here because it is the chapter most likely to be irrelevant outside China.

9. Repository Maintenance & Operations

9.1 Release model

There are no releases. There are no tags. There is no version number. The book is delivered as the head of main. A reader's "version" is whichever commit they cloned.

For a fork that wants release discipline:

1. Use semantic versioning at the chapter level — v1.0 is "all 19 chapters present", v1.1 is "chapter 16 expanded", etc.
2. Tag every print-edition update.
3. Publish changelogs in CHANGELOG.md.

9.2 Branch strategy

The upstream uses single-branch direct-to-main development. Two contributor branches (dev does not exist as of 6087a06) — every contribution merges directly to main.

For a fork with multiple translators:

main                 ← stable, deployed
├── translation/es   ← Spanish translation work
├── translation/ko   ← Korean translation work
└── content/ch16     ← Active expansion of chapter 16

Merge translation branches into main only when a chapter is review-complete.

9.3 Image management

Every chapter has a chXX_<topic>/img/ folder. Conventions:

• File names use the section number — 2-1.png, 2.16.4.1.png, 2.40.10.1.png.
• Some sections use a sub-folder when many figures share a section: 2.1/1.jpg, 2.1/2.jpg, ..., 2.1/12.jpg.
• Image formats vary: PNG, JPG, GIF (e.g. 2-20.gif is animated). All render in browsers and Typora.
• A handful of files use Chinese characters in the filename (e.g. ch18_后端架构选型及应用场景/img/新建文件夹/).

Maintenance gotchas:

• Do not move images without updating the chapter's relative paths. Every chapter file uses ./img/chN/... or ../img/chN/... (the latter requires the docsify rewrite hook).
• GIFs are large. A 5 MB animated GIF will load slowly on mobile readers. Convert to WebM or static stills if the animation is not load-bearing.
• Total figure size dominates repository size. Compressing legacy PNGs with oxipng or pngquant could reduce the repo by 10–30%.

9.4 Building PDFs (Pandoc recipe)

For maintainers who want to generate per-chapter PDFs (the most-requested feature):

# Install Pandoc 3.x and a TeX distribution with xelatex
# (TeX Live, MacTeX, MiKTeX)

# Install Noto Sans CJK SC if not already
# Linux: apt install fonts-noto-cjk
# macOS: brew install --cask font-noto-sans-cjk-sc

# Build chapter 1
pandoc "ch01_数学基础/第一章_数学基础.md" \
  -o "ch01_数学基础.pdf" \
  --pdf-engine=xelatex \
  --variable=mainfont:"Noto Sans CJK SC" \
  --variable=mathfont:"Latin Modern Math" \
  --variable=geometry:margin=1in \
  --variable=fontsize=11pt \
  --resource-path=".:ch01_数学基础"

# Wrap in a loop for all chapters:
for ch in ch*; do
  src=$(ls "$ch"/第*章_*.md 2>/dev/null || ls "$ch"/ch*.md 2>/dev/null)
  [ -z "$src" ] && continue
  pandoc "$src" -o "$ch.pdf" \
    --pdf-engine=xelatex \
    --variable=mainfont:"Noto Sans CJK SC" \
    --variable=mathfont:"Latin Modern Math" \
    --resource-path=".:$ch"
done

Output is decent — formulas render correctly, Chinese typography is readable, figures embed. Page breaks are imperfect; tune with --variable=geometry:... and chapter-by-chapter inspection.

9.5 Translation pipeline (manual workflow)

The current translation workflow is purely manual:

1. Translator forks the repo.
2. Copies a chapter file into English version/chXX_<EnglishTopic>/.
3. Translates section-by-section in Typora.
4. Opens a PR.

For a serious translation effort, document this workflow plus:

• A glossary of technical terms (CNN → 卷积神经网络; ReLU → ReLU; Dropout → Dropout / 丢弃法 — pick a consistent rendering).
• A style guide (American or British English; voice; whether to translate code variable names).
• A review process (one linguistic reviewer + one technical reviewer per chapter).

10. Repository Structure (full file tree)

DeepLearning-500-questions/
├── .gitignore
├── .nojekyll
├── LICENSE                  (GNU GPL-3.0)
├── README.md                (Chinese front matter, 528 lines)
├── _sidebar.md              (20-entry navigation list)
├── docsify.js               (vendored docsify ~17K LOC)
├── index.html               ($docsify config + script tags)
├── qun.png                  (WeChat group QR image)
├── 目录预览.md              (deprecated TOC preview)
├── 深度学习500问-Tan-00目录.docx (print-edition TOC, Word format)
├── Translation Required     (file-named placeholder, no extension)
│
├── ch01_数学基础/
│   ├── 第一章_数学基础.md           (563 lines)
│   ├── readme.md                  (status note)
│   ├── modify_log.txt             (edit log)
│   └── img/ch1/*.png              (~7 figures)
│
├── ch02_机器学习基础/
│   ├── 第二章_机器学习基础.md       (2456 lines — largest chapter)
│   ├── readme.md
│   ├── modify_log.txt
│   └── img/ch2/                   (60+ figures across many sub-folders)
│       ├── 2-1.png, 2-2.png, ..., 2-22.gif  (basic numbered figures)
│       ├── 2.16.17-1.png, 2.16.4.1.jpg, ...  (sub-section figures)
│       └── 2.1/, 2.16/, 2.18/, 2.25/, ... 2.40.15/  (per-sub-section folders)
│
├── ch03_深度学习基础/
│   ├── 第三章_深度学习基础.md       (1278 lines)
│   ├── readme.md
│   └── img/ch3/                   (figures)
│
├── ch04_经典网络/
│   ├── 第四章_经典网络.md           (328 lines)
│   ├── readme.md
│   └── img/ch4/
│
├── ch05_卷积神经网络(CNN)/
│   ├── 第五章_卷积神经网络(CNN).md   (456 lines)
│   ├── readme.md
│   └── img/ch5/
│
├── ch06_循环神经网络(RNN)/
│   ├── 第六章_循环神经网络(RNN).md   (544 lines)
│   ├── readme.md
│   └── img/ch6/
│
├── ch07_生成对抗网络(GAN)/
│   ├── ch7.md                     (491 lines — note: not 第七章_*.md!)
│   ├── readme.md
│   └── img/ch7/
│
├── ch08_目标检测/
│   ├── 第八章_目标检测.md           (1506 lines)
│   ├── readme.md
│   └── img/ch8/
│
├── ch09_图像分割/
│   ├── 第九章_图像分割.md           (922 lines)
│   ├── readme.md
│   └── img/ch9/
│
├── ch10_强化学习/
│   ├── 第十章_强化学习.md           (129 lines)
│   ├── readme.md
│   └── img/ch10/
│
├── ch11_迁移学习/
│   ├── 第十一章_迁移学习.md          (661 lines)
│   ├── readme.md
│   ├── img/ch11/
│   └── media/
│
├── ch12_网络搭建及训练/
│   ├── 第十二章_网络搭建及训练.md     (624 lines)
│   ├── readme.md
│   └── img/ch12/
│
├── ch13_优化算法/
│   ├── 第十三章_优化算法.md          (451 lines)
│   ├── readme.md
│   └── img/ch13/
│
├── ch14_超参数调整/
│   ├── 第十四章_超参数调整.md         (404 lines)
│   ├── readme.md
│   └── img/ch14/
│
├── ch15_GPU和框架选型/
│   ├── 第十五章_异构运算、GPU及框架选型.md  (425 lines)
│   ├── readme.md
│   └── img/ch15/
│
├── ch16_自然语言处理(NLP)/
│   ├── 第十六章_NLP.md              (101 lines — shortest, stub-like)
│   └── readme.md                  (no img/ folder yet)
│
├── ch17_模型压缩、加速及移动端部署/
│   ├── 第十七章_模型压缩、加速及移动端部署.md  (1801 lines)
│   ├── 17.8.1 NCNN部署.md           (985 lines — NCNN supplement)
│   ├── readme.md
│   ├── modify_log.txt
│   └── img/ch17/
│
├── ch18_后端架构选型、离线及实时计算/
│   ├── 第十八章_后端架构选型、离线及实时计算.md  (628 lines)
│   ├── readme.md
│   └── img/
│
├── ch18_后端架构选型及应用场景/
│   ├── 第十八章_后端架构选型及应用场景.md  (1956 lines — second-largest chapter)
│   ├── readme.md
│   └── img/                       (includes 新建文件夹/ — Chinese-named folder)
│
├── ch19_软件专利申请及权利保护/
│   ├── 第十九章_软件专利申请及权利保护.md  (252 lines)
│   ├── readme.md
│   └── img/
│
└── English version/
    ├── README.md                  (English front matter, contributor agreement)
    ├── ch01_MathematicalBasis/
    ├── ch02_MachineLearningFoundation/
    ├── ch03_DeepLearningFoundation/
    └── ch04_ClassicNetwork/
                                   (chapters 5–19 untranslated)

Total: 1230 files, 19 chapter folders + 1 English-version folder + repo-root assets. The 1230 count is dominated by figure images (~1100); authored Markdown is ~50 files.

11. Module Reference (key files)

This is a content repository, not a software project, but several files are load-bearing and worth a brief reference.

11.1 index.html (delivery contract)

The single entry point for the docsify-rendered site. Contains:

• <head>: theme stylesheet, KaTeX CSS+JS, math-jax inline config (<script type="text/x-mathjax-config">).
• <body>: <div id="app"></div> placeholder.
• <script>window.$docsify = { ... }</script>: site configuration.
• Tail <script> tags: docsify, plugins, MathJax (async).

If you change index.html, always test locally before pushing — a syntax error here breaks every reader at once.

11.2 _sidebar.md (navigation)

20 entries. Adding/removing/reordering chapters requires editing this file.

11.3 docsify.js (renderer, vendored)

A pinned snapshot of docsify v4. Source is human-readable but the project does not edit this file — it is treated as a third-party library. To upgrade:

curl -o docsify.js https://unpkg.com/docsify@4/lib/docsify.js
git add docsify.js && git commit -m "Update vendored docsify"

Test all chapters after upgrade — minor docsify versions occasionally change plugin API.

11.4 README.md (front matter and TOC)

The project's "homepage". Renders as the docsify root page (because _sidebar.md has * [简介]() pointing at the root). Contains:

• Print-book purchase link (JD).
• Author bios for 谈继勇, 郭子钊, 李剑, 佃松宜, 王晋东, 王超锋, 郭晓锋, 黄伟, 陈方杰 (Amusi), 李元伟, 陈琳, and others.
• Chinese-language full table of contents (528 lines).

When updating, mirror changes into English version/README.md if appropriate.

11.5 chXX_<topic>/第N章_*.md (chapter content)

The 19 chapter files are the bulk of the repository. They follow the conventions in §2.3. Edits to these files are the dominant PR class.

12. Code Patterns & Conventions

For a content-only repository, "code patterns" = "editorial patterns".

12.1 Heading numbering

Sub-sections use a chapter-prefixed dotted scheme:

# 第二章 机器学习基础       ← H1 (chapter title)
## 2.1 基本概念            ← H2 (top-level section)
### 2.1.1 大话理解机器学习  ← H3 (sub-section)

Numbers are manually maintained — no auto-numbering plugin. This is fragile: removing a sub-section requires renumbering every following section. In practice, the project does not renumber after deletions, leading to the gaps and duplicates flagged in issues like #531 and #536.

12.2 Bold-term-on-first-use

Definition-style sections use a leading bold-term pattern:

**标量（scalar）**
一个标量表示一个单独的数 ...

**向量（vector）**
一个向量表示一组有序排列的数 ...

This is the dominant explanatory style in chapter 1 and parts of chapters 2 and 3.

12.3 Math notation

The \tag{...} pattern is used inconsistently across chapters. Standardize it for a fork.

12.4 Figure captions

There is no consistent caption format. Some figures use the Markdown image alt-text:

![图2-1](./img/ch2/2-1.png)

Others have a separate paragraph below the image. This inconsistency is a known editorial weak spot; a fork that wants Chicago-style "Figure 2.1: ..." captions would need to add them to ~1100 images.

12.5 Citations

Inline citations are unstructured — usually a parenthetical reference to the paper title and author, occasionally with a URL. There is no references.md per chapter and no cross-chapter bibliography.

12.6 Code blocks

Code blocks (rare — most content is text and math) use fenced syntax with a language tag:

```python
import torch
```

No project-specific style; conventional Python/Bash/JS as appropriate.

13. Testing Strategy

There is no automated test suite. There is no CI. There is no pre-commit hook.

For a fork that wants editorial QA, a minimal pipeline:

A reasonable initial GitHub Actions workflow:

name: editorial-qa
on: [push, pull_request]
jobs:
  qa:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lycheeverse/lychee-action@v1
        with:
          args: --offline ./ch*/*.md
      - uses: DavidAnson/markdownlint-cli2-action@v16
        with:
          globs: "ch*/*.md"

Upstream has no such workflow today.

14. Potential Improvements

In rough order of value-to-effort:

1. Ship a PDF build. Multiple users have asked since 2018 (#393, #481, #376). Pandoc per chapter (§9.4) is the cheapest path; commit one PDF per chapter to a pdf/ folder, regenerate on releases.

2. Add .gitattributes to fix the GitHub language badge. The repository displays as "JavaScript / 99%" because of the vendored docsify.js. Mark it linguist-vendored=true.

3. Fix the externalLinkTarget: '_target' typo in index.html. Should be _blank. One-character change.

4. Add a CODE_OF_CONDUCT.md and CONTRIBUTING.md. The English README has a contributing section; promote it to a top-level file with a link from README.

5. Add a SECURITY.md policy even if minimal — GitHub now flags repositories without one.

6. Translate chapters 5–19 to English. The biggest open editorial gap. Open issue #548 tracks this. Coordinate via a translators' issue label.

7. Resolve duplicate section numbering in chapter 2 (issue #531).

8. Fix the tanh derivative table at §3.4.3 (issue #544).

9. Audit and fix link rot. Run lychee quarterly; replace dead links with Wayback URLs or remove.

10. Add Subresource Integrity hashes to the CDN-loaded <script> and <link> tags in index.html, or self-host all CDN assets.

11. Upgrade KaTeX from 0.10.0-rc.1 to a current stable (e.g. 0.16.x). RC versions should not be in production.

12. Compress legacy PNGs with oxipng -o4. Likely 10–30% repo-size savings.

13. Add a glossary of standard term translations to discipline the English port.

14. Consider a docsify alternative (MkDocs Material, Astro Starlight) that ships PDF generation, search index pre-building, and easier theme customization. Migration is non-trivial; only worth it for serious republishing forks.

15. Add a _navbar.md with a language switcher (中文 / English) for the docsify site — current site has no language toggle.

16. Replace third-party paper figures with redrawn versions to clarify image rights for republishing.

17. Adopt the co-op-translator pattern if the project moves toward many-language support; see microsoft/Web-Dev-For-Beginners for prior art.

15. Contributing Guide

15.1 Quick checklist for typo / math PRs

• [ ] Edited only the intended file(s).
• [ ] No whitespace churn (no end-of-line normalization, no trailing-space removal across the whole file).
• [ ] Math previewed in Typora or docsify, renders correctly.
• [ ] Section number unchanged (or renumbered consistently if the change affects ordering).
• [ ] Updated modify_log.txt with name, date, and short description (project convention).
• [ ] PR title in the form chXX: brief description (e.g. ch03: fix tanh derivative table at 3.4.3).

15.2 Quick checklist for new-section PRs

• [ ] Discussed in an issue before writing (the maintainers prefer this).
• [ ] Section number does not collide with an existing one.
• [ ] H2/H3 follow the N.x / N.x.y numbering convention.
• [ ] Math expressions tested in both KaTeX and MathJax.
• [ ] Figures placed under chXX_<topic>/img/chN/, with relative path ./img/chN/<file> from the chapter file.
• [ ] If figures are reproduced from a paper, source attribution included in the figure caption or alt text.

15.3 Quick checklist for translation PRs

• [ ] Translation goes into English version/chXX_<EnglishTopic>/.
• [ ] Original Chinese file is not modified.
• [ ] Math expressions are byte-identical (LaTeX is universal).
• [ ] Section numbering matches the Chinese original.
• [ ] Translator name and affiliation in the format <Name>-<Affiliation> (e.g. Daxie-West Lake University) added to the chapter file or English version/README.md.
• [ ] Glossary terms used consistently within the chapter.

15.4 What not to PR

• Wholesale reformatting (line wrapping, indentation rewrites). Editorial drift is high and reformatting causes review-impossible diffs.
• New chapters without prior issue discussion.
• License changes.
• Removing the JD purchase link from README — the link is part of the relationship with the print publisher.

16. Forking Guidance

If you intend to fork — for translation, derivative work, classroom deployment, or republishing — follow this checklist.

16.1 Before forking

1. Read the LICENSE (GPL-3.0). Confirm your downstream use is GPL-compatible.
2. Decide whether you will mirror image rights audit (see §6.3) or replace figures.
3. Decide on language strategy (one language only? multi-language? co-op-translator workflow?).

16.2 Initial fork setup

gh repo fork scutan90/DeepLearning-500-questions --clone=true --remote=true
cd DeepLearning-500-questions

# Pin yourself as the upstream
git remote add upstream https://github.com/scutan90/DeepLearning-500-questions

# Configure git for Chinese filenames
git config core.quotepath false

# Optional: adjust language detection
echo "docsify.js linguist-vendored=true" > .gitattributes
git add .gitattributes && git commit -m "Mark vendored docsify"

16.3 Fork-specific changes to consider

• Edit index.html: rename name, change repo URL, adjust themeColor, fix externalLinkTarget typo.
• Edit README.md: add a section linking back to upstream, document your fork's purpose.
• Add a CODE_OF_CONDUCT.md.
• Add a CONTRIBUTING.md (your fork's, not the upstream's).
• Add a SECURITY.md policy.
• Optional: add the editorial-qa GitHub Actions workflow (§13).

16.4 Periodic upstream sync

git fetch upstream
git merge upstream/main  # or rebase, your choice

# Resolve conflicts in chapter files (rare; the upstream is mostly stable)
# Test the docsify site (python -m http.server) before pushing

The upstream's low commit cadence means syncs will usually be fast-forwards or no-ops.

17. Troubleshooting (operations)

Error: GitHub Pages serves the README but the docsify site is empty

See User Guide §11. Cause: missing .nojekyll. Add it.

Error: KaTeX fails to render \boldsymbol{\mu} or \mathbb{R}

Both should work in MathJax even when KaTeX rejects them. If both fail, MathJax is not loading — verify the cdnjs.cloudflare.com URL is reachable, or self-host MathJax 2.7.5.

Error: Pull request is closed without comment

Cause: the project is on a slow review cadence. Re-open the PR after 30 days with a polite ping. For urgent fixes (security, broken-image-on-front-page), email [email removed].

Error: Forked translation diverges from upstream

Resolve by syncing git fetch upstream && git merge upstream/main. Conflicts are usually in chapter files; resolve manually because automated tools cannot reconcile translated text against new Chinese content.

Error: _sidebar.md shows duplicate "Chapter 18" entries

That is correct. Two ch18_* folders exist by design; both appear in the sidebar.

Error: [TOC] shows up as literal text

Strip it on ingestion (see §4.4) or use Typora to view source files. Docsify ignores [TOC] harmlessly.

Error: Image at chXX_<topic>/img/<sub>/<file>.png does not load on github.com but loads locally

Cause: GitHub URL-encodes Chinese characters in paths. The link works in raw view but fails in some embedded renderers (e.g. Slack link previews, some mobile apps). No fix on the project side; rename to ASCII filenames if downstream consumers complain.

Error: New <script> tag merged through PR review

Cause: a malicious or careless PR introduced HTML JS. Revert immediately. Audit the chapter file for other unwanted HTML. Add the §8.1 review checklist to your fork's CONTRIBUTING.

18. Quick Reference

18.1 Key paths

18.2 Common commands

# Run docsify locally
python -m http.server 3000

# Find every section that mentions a topic
rg -n "<topic>" -g "ch*/*.md"

# Build a single-chapter PDF with Pandoc + xelatex + Noto CJK
pandoc "ch01_数学基础/第一章_数学基础.md" -o ch01.pdf \
  --pdf-engine=xelatex --variable=mainfont:"Noto Sans CJK SC"

# Re-vendor docsify
curl -o docsify.js https://unpkg.com/docsify@4/lib/docsify.js

# Quarterly link-rot scan
lychee --offline ./ch*/*.md

# Convert all chapter PNGs in place to optimized PNGs
find ch*/img -name "*.png" -exec oxipng -o4 {} +

18.3 Open-issue summary (as of 2026-04 snapshot)

18.4 External references

• Repository: https://github.com/scutan90/DeepLearning-500-questions
• Print edition (JD listing): https://item.jd.com/12785031.html
• Publisher (博文视点): https://www.broadview.com.cn/
• Docsify documentation: https://docsify.js.org/
• KaTeX documentation: https://katex.org/
• MathJax 2 documentation: https://docs.mathjax.org/en/v2.7-latest/
• License (GPL-3.0): https://www.gnu.org/licenses/gpl-3.0.html