# 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](https://docsify.js.org/), 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](#12-what-this-system-is-not) first. --- ## 1. Executive Summary ### 1.1 What this system is | Property | Value | |----------|-------| | Type | Static Markdown book + docsify single-page site | | Primary content | 19 chapters of deep-learning Q&A in Simplified Chinese | | Secondary content | English port of chapters 1–4 | | Asset count | 1230 files (mostly figure images PNG/JPG/GIF) | | Source-code lines | ~17K (entirely in `docsify.js`, a vendored third-party library) | | Project-authored code | Zero — everything authored is Markdown text | | License | GPL-3.0 | | Last commit | `6087a06`, 2021-10-14 | | Print companion | *深度学习500问——AI工程师面试宝典*, publisher 博文视点, [JD listing](https://item.jd.com/12785031.html) | | Authors | 谈继勇 (chief editor); 郭子钊, 李剑, 佃松宜 (co-editors); 王晋东 (special editorial); contributors listed in `README.md` and per-chapter `modify_log.txt` | ### 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 ```text ┌────────────────────────────────┐ │ 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_/*.md (chapter text) │ │ chXX_/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 ```text 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: | File | Purpose | |------|---------| | `第N章_.md` | The chapter's main content, except chapter 7 (`ch7.md`) | | `readme.md` | Short status note (often just "writing in progress" or contributor names) | | `modify_log.txt` | Manually maintained edit log; predates rigorous use of git | | `img/chN/` | All figures for the chapter; subfolders by section number for some chapters | Inside each chapter file: ```markdown [TOC] # 第N章 ## N.1
### N.1.1 **** $$$$ > ``` The `[TOC]` token is a Typora-only directive — see [§4.4](#44-typora-and-the-toc-directive). ### 2.4 Docsify configuration (`index.html`) The configuration is small and the entire delivery contract is in this file. Key fields: | Config key | Value | Effect | |------------|-------|--------| | `themeColor` | `#fc7e09` (orange) | Primary accent color | | `loadSidebar` | `true` | Load `_sidebar.md` as nav | | `maxLevel` | `2` | Top-of-page TOC depth | | `subMaxLevel` | `2` | Sidebar TOC depth | | `auto2top` | `true` | Auto-scroll to top on navigation | | `name` | `深度学习500问` | Site title shown in sidebar | | `repo` | `https://github.com/scutan90/DeepLearning-500-questions` | "View on GitHub" badge | | `externalLinkTarget` | `_target` | Note: this is a typo; should be `_blank`. Browsers fall back gracefully but it is technically wrong. | | `markdown.latexRender` | `katex.renderToString.bind(katex)` | KaTeX is the primary math renderer | | `search.placeholder` | `Type to search` | Sidebar search box placeholder | | `search.depth` | `6` | Search index covers up to H6 headings | External script/style dependencies pulled from CDNs: | URL pattern | Purpose | |-------------|---------| | `unpkg.com/docsify/lib/themes/vue.css` | Vue theme stylesheet | | `cdn.jsdelivr.net/npm/katex@0.10.0-rc.1/...` | KaTeX 0.10.0-rc.1 (CSS + JS) | | `unpkg.com/docsify/lib/plugins/zoom-image.js` | Click-to-zoom on images | | `unpkg.com/docsify-copy-code` | Copy-button on code blocks | | `unpkg.com/prismjs/components/prism-bash.js` | Bash highlighting | | `unpkg.com/prismjs/components/prism-python.js` | Python highlighting | | `unpkg.com/docsify/lib/plugins/search.js` | Sidebar search | | `cdnjs.cloudflare.com/.../mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_HTMLorMML` | MathJax fallback for symbols KaTeX cannot render | Two custom hooks are registered as plugins: ```javascript 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: ```markdown * [简介]() * [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 | Requirement | Detail | |-------------|--------| | Web browser | Any modern browser. Tested on Chrome 80+, Firefox 70+, Safari 13+. Mobile Safari and Android Chrome work. | | JavaScript enabled | Required — docsify is JS-only | | Network access (for hosted version) | Outbound HTTPS to `cdn.jsdelivr.net`, `unpkg.com`, `cdnjs.cloudflare.com` (or pin local copies) | ### 3.2 For self-hosters | Component | Minimum | Notes | |-----------|---------|-------| | Static file server | Anything | Apache, Nginx, GitHub Pages, S3 + CloudFront, Netlify, Vercel, `python -m http.server`, `caddy file-server`, `npx serve` | | TLS | Optional | Required for serving over HTTPS; trivial via Let's Encrypt | | Disk space | ~80 MB | The full repo with `.git` is ~80 MB; bare `main` ~50 MB | | Bandwidth | Trivial | Static site; one user reads <5 MB/session | | Domain | Optional | Works on any subdomain or path | ### 3.3 For editors and translators | Tool | Why | |------|-----| | [Typora](https://typora.io/) (recommended) | Native rendering of `[TOC]`, KaTeX, MathJax; the maintainers' editor | | Any IDE with Markdown preview | VS Code with "Markdown All in One" works | | `git` 2.20+ | For commits and PRs | | A CJK-capable terminal | If running git from the command line on Chinese-named files | > [!IMPORTANT] > Editors on Windows: enable Git's `core.quotepath = false` to avoid garbled filenames in `git status` for Chinese-named folders. > > ```bash > 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](https://github.com/scutan90/DeepLearning-500-questions/issues/393), [#481](https://github.com/scutan90/DeepLearning-500-questions/issues/481), [#376](https://github.com/scutan90/DeepLearning-500-questions/issues/376)). None ship in the repository today. A working approach for forks: | Component | Recommended | |-----------|-------------| | Conversion engine | Pandoc 3.x with `xelatex` | | CJK font | Noto Sans CJK SC, or 思源黑体 | | Math font | Latin Modern Math | | Build orchestration | `make` or a small shell script per chapter | See [§9.4](#94-building-pdfs-pandoc-recipe) 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`: | Key | Default | When to change | |-----|---------|----------------| | `name` | `深度学习500问` | Translate to your language for a translation fork | | `repo` | scutan90's URL | Point at *your* GitHub fork | | `themeColor` | `#fc7e09` | Match your brand if forking commercially | | `externalLinkTarget` | `_target` | **Fix to `_blank`** — current value is a typo; browsers tolerate it but it is wrong | | `loadNavbar` | unset | Set to `true` to add a top navbar (`_navbar.md`) — useful for multi-language switchers | | `coverpage` | unset | Set to `true` and add `_coverpage.md` for a landing-page splash | ### 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: ```html ``` 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 `` instead of ``: site configuration. - Tail `