fq-book: a docsify book on proxies, tunnels and network censorship

A docsify site in a repository that GitHub calls Shell

The repository tree is the fastest way to understand what this project is. It lists `.github/`, `.vscode/`, `README.md`, `deploy.sh`, `docs/` and `push.sh`, and nothing else. GitHub reports Shell as the primary language, which is an artefact of the two deployment scripts rather than a claim that the project is a tool. There is no library to import, no binary to fetch, no package to install and no daemon to supervise. What you get is a `docs/` directory that docsify turns into a book.

That shape matters for how you evaluate the project. A book cannot be compared to a proxy client on features, because it is not one. What it offers instead is explanation: the repository topics list proxy, tunnel, vpn, shadowsocks, ssr, ssh, tcp, ip-blocking, digital-certificate, https, rst, ipfs, deep-web and gfw, which is a decent map of the territory the chapters cover. The author states the scope directly, focusing on how to get online and how to get information, with short hands-on configuration for common software alongside the underlying principles.

The book also carries its own caveats. Its disclaimer says it is aimed at Chinese readers living overseas, that the material is for research and study, and that readers inside China should delete any related files within 24 hours, with the author accepting no responsibility for what follows. Use of derivative and shared copies is allowed while commercial use is not, and no formal licence file appears in the tree. Documentation and training material is a category where that distinction is worth reading carefully rather than assuming.

Publishing the book on GitHub Pages in four steps

The README's deployment section is a numbered list, which is unusual for a documentation site and refreshing. Step one forks the repository to your own account. Step two is the only edit you actually have to make: open `docs/index.html`, find the docsify configuration object written as `window.$docsify = {}` and change its `repo` value to your own repository. Step three, in repository settings, selects GitHub Pages and points it at the `master` branch with the `docs` folder as the publishing source.

git clone https://github.com/你的github用户名/fq-book.git
cd fq-book

Step four is simply visiting the resulting URL, which takes the form of your GitHub username followed by the repository name. In practice the whole deployment is a fork plus a one-word configuration change, and everything else is GitHub's own Pages pipeline. There is no build step, no bundler and no dependency file: docsify does its work in the browser, so the folder you publish is the finished site.

The README records that image hosting moved to postimg.cc, which is why an old fork can render text correctly while every picture is missing. The same change let the author cut the repository from about 30MB down to 144KB, which is what makes a fork-and-publish workflow practical at all. If you are upgrading a fork you set up years ago, that is the symptom to look for.

Reading it locally with docsify and taking it offline

The local path needs two things on Windows: git and node, both installed with the default options. Open git bash from the right-click menu rather than Command Prompt, because the instructions are written for a bash shell. Download the archive with `clone or download`, unpack it, change into the `fq-book-master/docs` directory, then install the docsify command line tool and serve:

npm i docsify-cli -g
docsify init .
docsify serve

Once the server starts, the book appears in a browser at `localhost:3000`. The same commands work from a terminal on macOS or Linux, where you skip the right-click step entirely. The README points at the official docsify documentation for anything beyond this, which is where you go when you want to add search, a different theme or sidebar behaviour.

Offline reading gets its own paragraph, and the answer is a third-party tool rather than something the project implements. The README suggests Offline Explorer to pull down the whole site for local viewing. It also notes that you can convert the docsify layout into gitbook format and use gitbook's own commands to produce a PDF, which is the path to take if you want the book on a device that should not be running a web server.

Rebasing a fork onto upstream without losing local edits

Because the recommended workflow is to fork, the update path gets real attention. The README assumes your fork has drifted, either because you changed the `repo` setting or because the author has moved on since you cloned. You add the original repository as a remote named `upstream`, fetch it, and then point your `master` at what upstream has:

git remote add upstream https://github.com/hoochanlon/fq-book.git
git fetch upstream
git reset --hard upstream/master

The hard reset is the honest part of this. It discards anything you committed locally, which is exactly why the README also suggests `git pull upstream master --allow-unrelated-histories` for readers who want to review the incoming changes as a code diff rather than take them on trust. The choice is between a fast, blind update and a slower one where you can see what changed.

Once the tree is where you want it, publishing your fork is three commands, a commit message of your choosing and a credential prompt. The README flags that special situations may require configuring a proxy, a mirror or a shallow clone, which is a realistic warning for anyone working through a slow connection or a repository that grew large over the years.

The proxy configuration blocks that make the book practical

A book about proxying is not much use if the tools themselves will not route their traffic, and this is where the README is unusually concrete. The git section sets and clears a SOCKS5 proxy at the global level, and the clearing half matters because a stale proxy setting breaks fetches in ways that look like network outages:

git config --global http.proxy 'socks5://127.0.0.1:1080' && \
git config --global https.proxy 'socks5://127.0.0.1:1080'

 git config --global --unset https.proxy

The macOS section is the one people search for. A client running in global mode does not cover a terminal, so the shell needs its own variable, and the README gives both the set and the unset form. It names `curl cip.cc` as the way to check whether the terminal is actually going through the tunnel, which is the sort of detail that only shows up in a guide written by someone who has been stuck by it.

export ALL_PROXY=socks5://127.0.0.1:1080

The SSH section is the least obvious and the most useful. Rather than configuring a local port forward, it puts a `ProxyCommand` in the SSH config so that git over SSH inherits the proxy, offering a `socat` variant for an HTTP proxy on port 8848 and an `nc` variant for SOCKS5 on 1080. This is the part of the book that generalises beyond any single client, because SSH proxying is a problem every developer hits eventually.

Where the book ends and other people's repositories begin

Reading the README as a document rather than as a tool surfaces an honest limitation. A substantial share of it is a list of other projects: free node lists, subscription collections, a low-cost airport, a Clash desktop client and a repository of configuration files. The author is candid that these were useful to them personally. If you are looking for a maintained proxy client, this repository will not get you one, and the entries age faster than the chapters do.

The recent update notes are the better signal about what kind of maintenance this is. They list a new chapter, a fix for the `crx_header_invalid` extension error, a section on the case where a VPN connects to a server but no page loads, and a note that the built-in probot bot gained a new mode. Each entry corresponds to a question a reader actually asked, which suggests the book is shaped by its issue tracker rather than a release schedule.

The repository records no GitHub releases at all, so there is no version history to diff and no changelog beyond those README notes. There is no test suite, because there is nothing to execute. What you can evaluate is narrow and concrete: whether the explanations match the tools you actually use, whether the deployment steps still work on a current Node release, and whether a fork of a 144KB docsify site is a workflow you would rather maintain yourself.

Editorial conclusion

fq-book is worth an afternoon if you want the reasoning behind censorship tooling rather than another subscription link, and it is the wrong thing to install if you need a working client today. It ships no software beyond two shell scripts, so nothing here will change how your machine reaches the internet. Start with the intro and sidebar in `docs/`, since the README only points at them. The last push was on 2026-09-19 and the site lives at https://hoochanlon.github.io/fq-book. Before you fork it, note that the repository records no licence file and the disclaimer forbids commercial reuse.

Frequently asked questions

Official sources

1. hoochanlon/fq-book on GitHub
2. Issues
3. Project website
4. README