# Tech Weekly (科技爱好者周刊) User Guide

**Repository:** `ruanyf/weekly` · **Commit:** `c5d3c9b` (2026-04-24) · **Issue range:** #1 (2018-04-23) through #393 (2026-04-17)

`ruanyf/weekly` is **科技爱好者周刊** ("Technology Enthusiasts Weekly"), a Chinese-language tech newsletter written and curated by **Ruan Yifeng** (阮一峰). It has been published every Friday since 23 April 2018. As of the source commit covered by this guide, the archive holds **393 sequentially numbered weekly issues**, **8 topic pages** under `docs/subjects/`, and **3 free-resource pages** (`free-music.md`, `free-photos.md`, `free-software.md`). Every file is plain Markdown — there is no application, no build system, no database. The product is the writing.

This is a **reading guide**. It tells you how to find your way around the archive, how to extract value from a specific issue, how to subscribe, how to contribute corrections, and how to mirror the content for offline use. If you want to fork, translate, self-host, or maintain a derivative newsletter, read the [Administrator & Developer Guide](ruanyf__weekly__AdminGuide.md) instead.

> [!NOTE]
> The newsletter is published in Simplified Chinese (简体中文). Issue titles, section headings, and the bulk of the prose are Chinese. This guide cites the original Chinese terms inside backticks so machine translators and human readers can follow along without re-encoding the corpus into English. Where helpful, an English gloss follows in parentheses.

---

## 1. Quick Start

The lowest-friction way to read `ruanyf/weekly` is also the canonical way: open the repository on GitHub and click the latest issue.

1. Visit **[github.com/ruanyf/weekly](https://github.com/ruanyf/weekly)** in any browser.
2. Scroll the rendered `README.md`. The top of the index lists the current calendar year (e.g. `## 2026`), then the current month (e.g. `**四月**`), then a bullet for each issue published that month, newest first.
3. Click the most recent bullet — at the source commit, that is **第 393 期：脑腐状态** (Issue 393: "State of Brain Rot") at `docs/issue-393.md`.
4. Read it directly in GitHub's Markdown viewer. Outbound links are clickable; the cover image renders inline; section headings collapse cleanly.

```bash
# Or, from a terminal — open the latest issue without leaving your shell
git clone --depth 1 https://github.com/ruanyf/weekly.git
cd weekly
ls docs/issue-*.md | sort -V | tail -n 1
```

```text
docs/issue-393.md
```

> [!TIP]
> The author also cross-posts every weekly issue to his personal blog at **[ruanyifeng.com/blog](https://www.ruanyifeng.com/blog/)** with the URL pattern `/blog/{YYYY}/{MM}/weekly-issue-{N}.html`. The blog version carries a comment thread per issue, an RSS feed at `https://www.ruanyifeng.com/blog/atom.xml`, and stable permalinks suitable for citation. Pick GitHub for browsing the archive; pick the blog for subscribing or citing a single issue.

After you have read one issue, browse five more. The newsletter rewards immersion — section conventions become obvious after the third issue, and the author's voice carries across years.

---

## 2. Installation

There is **nothing to install** to read the newsletter. A web browser pointed at GitHub is sufficient. This section covers the optional setups that improve the reading experience for power users.

### 2.1 Reading paths compared

| Method | Setup | When to use |
|---|---|---|
| GitHub web UI | None — open `github.com/ruanyf/weekly` | Default; full-text search across the repo; permalinks |
| Author's blog | None — open `ruanyifeng.com/blog` | Comment threads; RSS subscription; cross-citing |
| Local clone | `git clone https://github.com/ruanyf/weekly.git` | Offline reading; `grep`-based search; private notes |
| RSS reader | Subscribe to `https://www.ruanyifeng.com/blog/atom.xml` | Push-style delivery; integration with read-it-later apps |
| Static-site mirror | Build with MkDocs / Hugo / Docusaurus from a local clone | Internal corporate mirror; LAN-only access |

### 2.2 Local clone (recommended for archive readers)

```bash
git clone https://github.com/ruanyf/weekly.git
cd weekly
```

```text
Cloning into 'weekly'...
remote: Enumerating objects: done.
Receiving objects: 100% (...), done.
Resolving deltas: 100% (...), done.
```

The clone is small — a few hundred megabytes — because the repository contains only Markdown text. **No images are committed**; cover photos and inline graphics are referenced by absolute HTTPS URLs to `cdn.beekka.com/blogimg/` (or, for older issues, `www.ruanyifeng.com/blogimg/`). When you open a Markdown file in a viewer with internet access, images load over HTTPS from those CDNs.

```bash
# Verify the clone — should print "393" or higher
ls docs/issue-*.md | wc -l
```

```text
393
```

> [!IMPORTANT]
> The repository ships **no LICENSE file**. Treat the prose as copyrighted by Ruan Yifeng. Reading, cloning, quoting, and linking are fine under fair-use norms. Wholesale republication of an essay or commercial reuse requires written permission — contact `[email removed]`. The free-resource pages (`docs/free-*.md`) are reading lists; their entries link to third parties whose own licenses apply to those entries' content, not to this repository.

### 2.3 Shallow clone (for casual readers)

If you only want to read the current state and never need history:

```bash
git clone --depth 1 https://github.com/ruanyf/weekly.git
```

```text
Cloning into 'weekly'...
remote: Total 410 (delta 0), reused 200 (delta 0), pack-reused 210
Receiving objects: 100% (410/410), 4.10 MiB | 8.20 MiB/s, done.
```

A depth-1 clone drops the eight-year commit history (one commit per weekly issue plus typo-fix commits) and downloads only the current snapshot. Throughput is dramatically faster on slow networks; the trade-off is you lose the ability to inspect how an issue evolved after publish.

### 2.4 Subscribing via RSS

The newsletter does **not** offer a direct email-subscription form. The RSS feed is the closest equivalent and is fed by the author's blog, which carries every weekly issue:

```text
https://www.ruanyifeng.com/blog/atom.xml
```

Add that URL to any RSS reader (Feedly, Inoreader, NetNewsWire, NewsBlur, Reeder, Tiny Tiny RSS, Miniflux). New entries appear within minutes of the Friday push. The feed includes the author's other posts as well as the weekly — filter on title prefix `科技爱好者周刊` if you want only the weekly.

> [!TIP]
> Many email-newsletter services (Kill the Newsletter, Feed-to-Email, Blogtrottr) will turn an RSS feed into per-post emails for free. If you really want the newsletter in your inbox, point one of those at the blog feed and you have an unofficial email subscription.

### 2.5 Mirror it for offline reading

For long flights, restricted networks, or simply lower-latency reading, mirror the entire archive into a single static site. A minimal MkDocs setup at the repo root:

```yaml
# mkdocs.yml — place at the repo root
site_name: 科技爱好者周刊
docs_dir: docs
theme:
  name: material
  language: zh
markdown_extensions:
  - admonition
  - pymdownx.details
```

```bash
pip install mkdocs mkdocs-material
mkdocs serve
```

```text
INFO    -  Building documentation...
INFO    -  Documentation built in 1.42 seconds
INFO    -  [12:34:56] Serving on http://127.0.0.1:8000/
```

Open `http://127.0.0.1:8000/` for a fully searchable, themed, offline-capable copy of every issue.

> [!WARNING]
> If you mirror behind a private network that blocks `cdn.beekka.com`, images will 404. Either run an image proxy that fetches and re-serves the CDN paths, or pre-fetch the images and rewrite the Markdown links to local paths. The author's CDN is first-party, hot-linkable, and reasonably reliable, but corporate firewalls sometimes treat the `.beekka.com` domain as untrusted.

---

## 3. Configuration

There is no configuration file in this repository — it is plain Markdown. The "configuration" relevant to a reader is **how you choose to consume the newsletter**: which channel, which renderer, which font setup.

### 3.1 Choosing a channel

| Goal | Recommended channel | Why |
|---|---|---|
| Read the latest issue once | GitHub web UI | Zero setup, GitHub renders Markdown well |
| Subscribe to weekly delivery | RSS at `ruanyifeng.com/blog/atom.xml` | Push-based, integrates with reader apps |
| Cite an issue in writing | Blog URL `weekly-issue-{N}.html` | Stable permalink, comment context |
| Browse the archive deeply | Local clone + your editor | Faster navigation, full-text search |
| Read on a Kindle / e-reader | Local clone + `pandoc` to `epub` | Convert per-issue or omnibus |
| Share with non-technical readers | Blog cross-post | Comment threads, no Git knowledge required |

### 3.2 Renderer notes

GitHub renders the Markdown faithfully. Three rendering quirks are worth knowing:

- **Full-width numerics.** The author uses `1、` (full-width digit + ideographic comma U+3001) instead of ASCII `1.` for numbered lists. Most renderers preserve the typography; some auto-convert to ASCII. If the items look "wrong" they are probably being auto-converted; switch to a CJK-aware renderer.
- **Full-width parentheses.** Issue titles use `（` and `）` (full-width brackets) inside `# 科技爱好者周刊（第 N 期）`. Match this exactly when grepping for issue titles — `\(` (ASCII) will not match.
- **CJK font fallback.** PDF exports without a CJK font installed (e.g. `fonts-noto-cjk` on Debian) will render Chinese characters as boxes. Install a CJK font before exporting to PDF, or use a renderer that bundles its own CJK fallback (Typora, Marked, modern Chrome print-to-PDF).

### 3.3 Search-engine queries that work

If you need to find content by topic, the newsletter has no tag system — you search by keyword across the corpus. These queries reliably surface results:

```text
# In a search engine
site:github.com/ruanyf/weekly {keyword}
site:ruanyifeng.com/blog weekly-issue {keyword}

# In a local clone
grep -rli "{keyword}" docs/
grep -rln "{Chinese keyword}" docs/issue-*.md | head -n 20
```

The first form catches matches in the GitHub-rendered Markdown; the second catches matches in the blog cross-posts; the third does case-insensitive filename listing of every match in a clone. For Chinese-language searches, the blog's own search box and the GitHub repository search both handle CJK input correctly.

> [!TIP]
> The repository's own README links the most recent issues only — older issues are reachable but not linked from a top-level index page beyond the year sections. Direct URLs are predictable: `https://github.com/ruanyf/weekly/blob/master/docs/issue-{N}.md`. If you remember the number, you can jump straight to the file without browsing.

---

## 4. Core Usage

### 4.1 Publication cadence and numbering

`ruanyf/weekly` ships **one issue per week, every Friday**. The discipline has held for over eight years with rare gaps (holidays, travel, occasionally noted in the previous issue). Issue numbers are **monotonic and sequential** — issue #1 published 2018-04-23, issue #393 published 2026-04-17, no skips, no re-uses. To translate a publication date into an issue number, the rule of thumb is "issues per year ≈ 50, with the year boundary cleanly dividing." More precisely, the year-by-year breakdown visible from filenames in the index:

| Year | Approx. issue range | Notable issues |
|---|---|---|
| 2018 | #1 – #36 | Newsletter launches as `每周分享` (Weekly Sharing) |
| 2019 | #37 – #88 | Renamed to `科技爱好者周刊` |
| 2020 | #89 – #138 | Issue #100 — "零利率时代" |
| 2021 | #139 – #190 | |
| 2022 | #191 – #240 | Issue #200 — "低期望，多尝试" |
| 2023 | #241 – #289 | |
| 2024 | #290 – #340 | Issue #300 — "三十年，解决人生三大问题"; AI section enters schema |
| 2025 | #341 – #391 | |
| 2026 | #392 – #393 (current) | Issue #393 — "脑腐状态" (2026-04-17) |

(Boundaries are approximate — some years run 49 issues, some 52. Check the `README.md` index for the exact split.)

### 4.2 Standard issue structure

Every recent issue follows the same loose schema. Reading them in order makes navigation across the archive nearly automatic. Using issue #393 as the structural reference:

```markdown
# 科技爱好者周刊（第 393 期）：脑腐状态

这里记录每周值得分享的科技内容，周五发布。
本杂志开源，欢迎投稿。另有《谁在招人》服务，发布程序员招聘信息。

## 封面图
![cover image]
{caption describing the photo}

## {Essay title}
{long-form opinion essay by the author — the issue's "cover" piece}

## 科技动态
1、[item title](url)
{short commentary}

## AI 相关
1、[agent / tool / model](url)
{short commentary}

## 工具
1、[tool name](url)
{short commentary}

## 资源
1、[resource name](url)
{short commentary}

## 图片
1、[caption](url)
{descriptive paragraph for the photo}

## 文摘
1、[excerpt title](url)
{excerpted paragraphs from another piece of writing}

## 言论
1、{quote}
-- {attribution}

## 往年回顾
{links to same-numbered issues from prior years}

（完）
```

The Chinese section names map cleanly to English meanings:

| Section heading | Pinyin | Meaning |
|---|---|---|
| `封面图` | fēng miàn tú | Cover image — one photograph with caption |
| `科技动态` | kē jì dòng tài | Tech news — six to ten short items with commentary |
| `AI 相关` | AI xiāng guān | AI-related — added to the schema in 2024 |
| `工具` | gōng jù | Tools — software, websites, hardware, dev utilities |
| `资源` | zī yuán | Resources — datasets, tutorials, reference sites, books |
| `图片` | tú piàn | Images — interesting photographs or infographics |
| `文摘` | wén zhāi | Digest — long-form excerpts from other writing |
| `言论` | yán lùn | Quotes — one-liners with attribution |
| `往年回顾` | wǎng nián huí gù | Past issues — backlinks to same-numbered issues from prior years |
| `（完）` | wán | "End" — the closing marker on its own line |

The H1 title and boilerplate paragraph appear in every issue. The closing `（完）` marker has been consistent from roughly issue #53 onward. Mid-issue sections come and go week to week — some weeks lack `图片`; others fold in a one-off `电子书` (e-book) or `文档` (documentation) section. Treat the schema as "common, not strict."

> [!NOTE]
> Reader submissions feature heavily in the `工具` and `资源` sections. When an entry came from a reader, the author appends an attribution like `（[@handle](https://github.com/ruanyf/weekly/issues/9633) 投稿）` — the GitHub handle and a backlink to the original submission issue. Click those backlinks to read the submitter's pitch, screenshots, and discussion.

### 4.3 Reading order

You do not have to read chronologically. Issues are self-contained: each one introduces and closes its own thoughts. The most common reading patterns:

- **Latest-first.** Bookmark the repository and check on Fridays. The newest bullet under the current month is the freshest issue.
- **Recent backlog.** Skim the last 6–12 issues to catch up after a hiatus. Cover essays carry across weeks; reading three in sequence reveals recurring themes.
- **Historical sweep.** Start at `docs/issue-1.md` (23 April 2018) and follow the author's thinking as the newsletter matured from a personal link list into its current structured form. Roughly the first 30 issues use the original name `每周分享` rather than `科技爱好者周刊`.
- **Topical archaeology.** Use search to find every appearance of a technology — search "Rust", "Kubernetes", "LLM", or any term across the archive to see how the author tracked its trajectory year over year.

### 4.4 Topic collections (`docs/subjects/`)

Eight topic pages collect tools and resources outside the weekly chronology. They are short, opinionated, and curated by the same author:

| File | Topic | Typical contents |
|---|---|---|
| `docs/subjects/css.md` | CSS | Minimal CSS libraries, style guides |
| `docs/subjects/database.md` | Databases | Reference resources |
| `docs/subjects/dev.md` | Developer tooling | Code hosting, CI, Makefile references |
| `docs/subjects/docker.md` | Docker | Beginner guides, hands-on tutorials |
| `docs/subjects/go.md` | Go | Go-language tutorials |
| `docs/subjects/linux.md` | Linux | Linux references |
| `docs/subjects/math.md` | Mathematics | Math-for-programmers material |
| `docs/subjects/web.md` | Web utilities | SVG optimizers, JS libraries, icon sets |

> [!IMPORTANT]
> Topic pages are **personal reading lists**, not exhaustive references. Most contain three to ten entries; some have fewer. They grow when the author finds something worth saving outside the weekly format. Do not expect comprehensive coverage — expect the author's curated highlights.

The topic pages are not always linked from the root `README.md`. Reach them by browsing the `docs/subjects/` directory in GitHub or your clone, by following links inside weekly issues, or by direct URL.

### 4.5 Free-resource pages

Three pages under `docs/` curate freely-usable creative resources:

| Page | What it lists |
|---|---|
| `docs/free-music.md` | Royalty-free music libraries (CCMixter, Bensound, Free Music Archive, Jamendo, Incompetech, Freesound, and others) |
| `docs/free-photos.md` | Commercially-usable stock-photo libraries (Unsplash, Pexels, Pixabay, Gratisography, Canva Photos, Pxhere, and others) |
| `docs/free-software.md` | Free creative tools (DaVinci Resolve, Shotcut, Inkscape, draw.io, Mermaid, code-server, StackBlitz, and many more), grouped by category |

These pages are useful when you need a free music bed, a stock image, or a no-cost tool and want a curated short-list rather than a search-engine deep dive.

### 4.6 The "Who's Hiring" job board

The newsletter operates an ongoing **谁在招人** ("Who's Hiring") job thread. The current iteration at the source commit is **[issue #9454](https://github.com/ruanyf/weekly/issues/9454)** — pinned to the repository, linked from the top of `README.md`, and mentioned in every weekly issue's boilerplate.

Mechanics:

1. Employers post recruiting messages as **comments** on the pinned issue. Each comment specifies company, role, location, salary band, and contact method (usually email or WeChat).
2. Job-seekers read the comments and apply directly. There is no résumé upload, no application tracking, no matching algorithm. The issue is a public bulletin board.
3. Postings span interns, full-time roles, contract gigs, and remote-friendly positions. The board is dominated by Chinese-tech-industry roles but is language-agnostic.
4. When a thread becomes unwieldy (typically once a year), the author opens a new pinned issue, updates the README, and closes the previous thread.

> [!NOTE]
> A pinned job thread can grow to hundreds or thousands of comments. Use your browser's `Ctrl+F` / `Cmd+F` find feature with keywords like `远程` (remote), `实习` (intern), or your target city's Chinese name to filter the comment list down to roles you can act on.

---

## 5. Common Tasks

### 5.1 Find a specific past issue

You remember reading something about a technology, but you do not remember the issue number.

1. Decide whether you are searching by **topic** or by **issue title**.
2. For topic searches, use one of:
   - GitHub repository search: `keyword` in the box at top of `github.com/ruanyf/weekly`.
   - Engine query: `site:ruanyifeng.com/blog weekly-issue keyword`.
   - Local clone: `grep -rli "keyword" docs/issue-*.md`.
3. For title searches, scroll the year sections of `README.md`. Titles are the most-recognizable surface — "脑腐状态", "AI 的贫富分化", "axios 投毒与好莱坞式骗术" all stand out at a glance.
4. To open issue #N directly: `https://github.com/ruanyf/weekly/blob/master/docs/issue-{N}.md`.

```bash
# Local clone — find every issue mentioning "Rust"
grep -rli "Rust" docs/issue-*.md | head -n 20
```

```text
docs/issue-127.md
docs/issue-201.md
docs/issue-258.md
docs/issue-302.md
...
```

### 5.2 Search the archive by tech keyword

The repository has **no tag system**. Topic search is keyword search. The most reliable approach combines two passes:

1. **Cast a wide net.** Search the GitHub repository search box for a single keyword (`Kubernetes`, `LLM`, `WebAssembly`). Every match across every Markdown file is returned.
2. **Refine.** GitHub search shows the matched line in context. Click any result to read the surrounding paragraph; if the issue is relevant, open it; if not, return to results.

For multilingual searches — say, looking for everything tagged with both `AI` and `招聘` (hiring) — use a local clone and chain `grep`:

```bash
grep -rl "AI" docs/issue-*.md | xargs grep -l "招聘"
```

```text
docs/issue-318.md
docs/issue-345.md
...
```

> [!TIP]
> The author's blog at `ruanyifeng.com` has a built-in search that handles CJK better than GitHub's search in some cases. If GitHub's results look incomplete, try `site:ruanyifeng.com/blog/2026 weekly-issue keyword` to narrow by year.

### 5.3 Subscribe to weekly delivery

You want the newsletter pushed to you, not to remember to check on Fridays.

1. Open your RSS reader of choice. If you do not have one, install Feedly (web), NetNewsWire (macOS), or Tiny Tiny RSS (self-hosted).
2. Add the feed URL: `https://www.ruanyifeng.com/blog/atom.xml`.
3. (Optional) Filter to weekly-only: most readers let you create a folder or rule that keeps only entries whose title starts with `科技爱好者周刊`.
4. Verify by waiting until the next Friday — a new entry should appear within a few hours of publication.

```text
Feed URL:    https://www.ruanyifeng.com/blog/atom.xml
Update:      Push (RSS poll, every 15–60 min depending on reader)
Frequency:   Weekly issue + occasional other posts from the author
```

If you would rather receive emails, point a free service like Blogtrottr, Kill the Newsletter, or Feed-to-Email at the same RSS URL — they will send each new entry as a per-post email.

> [!CAUTION]
> Some third-party "Ruan Yifeng newsletter" email mirrors are run by people who are not the author. They scrape the blog and re-send it. They are usually fine but are out of the author's control. The canonical, author-controlled distribution is the GitHub repository and the blog at `ruanyifeng.com` — anything else is a community mirror.

### 5.4 Submit a tool, website, or open-source project

You built something a `ruanyf/weekly` reader would care about and you want it featured.

1. Open a new issue in the GitHub tracker: `https://github.com/ruanyf/weekly/issues/new`.
2. Prefix the title with the appropriate self-recommendation tag:
   - `【工具自荐】` for a tool, app, or CLI utility
   - `【网站自荐】` for a website or online service
   - `【开源自荐】` for an open-source project
3. In the body, include:
   - A direct link to the project, repository, or live URL.
   - A two-to-four-sentence description of what the thing is and why developers would want it.
   - One or two screenshots, if visual. Drag-and-drop into the GitHub issue editor.
   - A disclosure that you are the author (the `自荐` prefix already implies this; an explicit line is appreciated).
4. Submit. The author reviews submissions weekly. If accepted, your project appears in an upcoming Friday issue with your GitHub handle linked back to the submission issue.

> [!TIP]
> Reviewers triage by skimming titles. A clear `【工具自荐】` prefix and a one-line description in the title give your submission the best chance of getting a careful read. Submissions without prefixes are not rejected, but they take longer to surface in triage.

There is no accept/reject notification. You find out by seeing your submission in a published issue, or by not seeing it after several weeks. The author does not maintain a public submission queue — silence is not rejection, but it is the most common outcome for borderline submissions.

### 5.5 Contribute corrections (typos, broken links, factual errors)

You found a typo, a dead outbound link, or a factual mistake in an existing issue.

1. Open a new issue at `https://github.com/ruanyf/weekly/issues/new`.
2. Title it with one of the following patterns:
   - `第 N 期更正` — correction for issue N (typo, wording, factual error).
   - `第 N 期链接失效` — broken link in issue N.
3. In the body, **quote the specific sentence or list item** verbatim, then propose the correction. For broken links, include the original URL and (if you know it) the current correct URL.
4. Short, focused issues are processed fastest. Do not bundle multiple corrections across multiple issues into one report — one issue per fix.

```markdown
<!-- Example issue body for a broken link -->
第 350 期 `工具` 第 3 项 `示例工具` 的链接

原链接：https://example.com/tool
当前状态：404
建议替换：https://example.com/new-path/tool
```

The author lands typo fixes as follow-up commits on the offending issue file, usually within a few days. Broken-link reports get either a strikethrough (`~~text~~`) annotation or a URL update, depending on the situation.

> [!WARNING]
> The issue tracker handles **both** submissions and bug reports. The two share a single inbox. Use a clear, prefixed title (`【工具自荐】` for submissions, `第 N 期更正` or `第 N 期链接失效` for bugs) so the author can triage at a glance. Free-form titles work but slow down review.

### 5.6 Mirror the archive for offline reading

You want a self-contained, browsable copy that works on a plane, in a tunnel, or behind a corporate firewall that blocks GitHub.

1. Clone the repository: `git clone https://github.com/ruanyf/weekly.git`.
2. (Optional) Download the images for full offline fidelity. A simple wget loop:

   ```bash
   # Extract every cdn.beekka.com / ruanyifeng.com image URL
   grep -rhoE 'https://(cdn\.beekka\.com|www\.ruanyifeng\.com)/blogimg/[^)" ]+' docs/ | sort -u > images.txt
   wget -i images.txt -P images/ --no-clobber --quiet
   ```

3. (Optional) Build a static-site mirror with MkDocs (see `§2.5`) so the local copy is searchable and themed.
4. (Optional) Rewrite image URLs in the cloned Markdown to point at your local `images/` directory if you need true offline reading without DNS.

> [!NOTE]
> Without local images, every Markdown file is still readable as plain text — you simply see broken-image placeholders. The text is the substance; images are accents. Most archive readers skip the local-image step and rely on online image loading.

---

## 6. Troubleshooting

### Error: GitHub renders the issue but full-width numbers (`1、`) look broken

**Cause:** Some clients or themes auto-convert full-width Chinese numerics to ASCII. The author's intended typography uses `1、`, `2、`, `3、` (full-width digit + ideographic comma U+3001) inside numbered sections.

**Solution:**

1. Confirm the file on GitHub itself — `https://github.com/ruanyf/weekly/blob/master/docs/issue-393.md` — to see the canonical rendering.
2. If your local renderer differs, check the renderer's CJK / typography settings.
3. If you are exporting to PDF or HTML, install a CJK-capable Markdown renderer (Typora, Marked) or use the blog cross-post URL instead.

**Prevention:** Stick to renderers known to preserve CJK punctuation. GitHub itself, Typora, and Pandoc with `--from gfm` all preserve the original typography.

### Error: `cdn.beekka.com` images return 403 or 404

**Cause:** Two common causes — a network-level block on the CDN domain (corporate firewalls sometimes flag `.beekka.com`), or a transient CDN hiccup. Permanent file-level deletions are rare.

**Solution:**

1. Confirm in a second browser or on a different network. Most 403s resolve themselves within minutes.
2. If the same image is dead in multiple browsers and networks, file an issue titled `第 N 期图片失效` with the issue number and full image URL.
3. For corporate-firewall blocks, ask your network team to allow `cdn.beekka.com` and `www.ruanyifeng.com/blogimg/`.

**Prevention:** If you maintain a long-term mirror, pre-fetch images locally (see `§5.6`) so a CDN outage does not break your archive.

### Error: My RSS reader is not picking up new issues

**Cause:** Either the feed URL is wrong, the reader's poll interval is too long, or the reader is filtering aggressively.

**Solution:**

1. Verify the feed URL is exactly `https://www.ruanyifeng.com/blog/atom.xml`.
2. Force a manual refresh in your reader.
3. Check whether your reader is grouping the weekly under another folder (some readers split feeds by post type).
4. Open the URL directly in a browser and confirm a new `<entry>` exists for the latest Friday.

**Prevention:** Keep the feed URL bookmarked alongside your reader's settings. If the blog domain ever changes, the URL above is the authoritative starting point.

### Error: `git clone` is slow or appears to stall

**Cause:** The repository is small in bytes but holds eight years of commit history (one commit per weekly issue plus typo-fix commits). Combined with a slow connection, the initial pack can take a while to materialize.

**Solution:**

```bash
git clone --depth 1 https://github.com/ruanyf/weekly.git
```

```text
Cloning into 'weekly'...
Receiving objects: 100% (410/410), 4.10 MiB | done.
```

A depth-1 clone fetches only the current snapshot and is dramatically faster on slow networks. The trade-off is no commit history.

**Prevention:** Use `--depth 1` for casual reading; use a full clone only if you want to inspect how an issue evolved post-publish.

### Error: Submitted a tool weeks ago, never heard back

**Cause:** The author does not send accept or reject notifications. Submissions either appear in a future issue or do not.

**Solution:**

1. Check every weekly issue published since your submission date. If you find your project, the attribution links back to your original issue.
2. If your project is not yet featured, it may still be in the backlog — the author sometimes revisits old submissions months later when the topic fits.
3. If the submission is dated and may have aged out of relevance, file a follow-up issue noting the new state of the project and let the original issue stand.

**Prevention:** Submit polished, complete pitches with screenshots and a clear value proposition. Submissions that are obviously rough drafts wait the longest.

### Error: My static-site generator (Hugo, MkDocs, Docusaurus) fails on these files

**Cause:** The repository ships no static-site configuration. You must write your own. Most failures are mismatches between front-matter expectations and the issue files, which have **no front-matter** at all.

**Solution:** Use a generator that accepts plain Markdown without front-matter. MkDocs (with the Material theme) is the simplest path; see `§2.5` for a working `mkdocs.yml`. If you must use Hugo, configure `frontmatter: false` for the `docs/` archetype.

**Prevention:** Validate your generator with one issue file (`docs/issue-393.md`) before running it across all 393 — failures repeat consistently.

### Error: Search returns no results for a Chinese keyword I know is in the archive

**Cause:** Search engines and grep both treat CJK whitespace and punctuation differently. Common pitfalls: searching for ASCII commas instead of `、`, searching for full-width parentheses with ASCII brackets, or searching with a keyboard input method that injected zero-width characters.

**Solution:**

1. Re-type the keyword fresh — paste from the issue file you saw earlier, not from a memory of the term.
2. Use the GitHub repository search box, which handles CJK input correctly.
3. For local grep, pass `-P` (Perl regex) and a UTF-8 locale: `LC_ALL=C.UTF-8 grep -rliP "关键词" docs/`.

**Prevention:** When in doubt, pick the keyword by copying directly from a known matching issue. Avoid retyping CJK terms from memory across keyboards.

### Error: A link in an old issue points to a parked domain or different site

**Cause:** Link rot. Eight years is long enough for many of the older outbound links to have died, been acquired, or been parked.

**Solution:** File a `第 N 期链接失效` issue with the original URL and what it currently shows. The author either strikethroughs the entry or updates to a new URL.

**Prevention:** When you find a great resource in a 2018-2020 issue, expect roughly one in five links to be dead. Search the resource name on the open web to find its current home before assuming it is gone.

---

## 7. FAQ

**Q: Who writes Tech Weekly?**

Ruan Yifeng (阮一峰), a Chinese software developer, technical author, and the most widely-read technical blogger on the Simplified-Chinese internet. His personal blog at `ruanyifeng.com` has been running since 2003 and his books on JavaScript, ECMAScript, and Git are standard references in the Chinese developer community. Reach him at `[email removed]`.

**Q: When does each issue come out?**

Every Friday. The discipline has held for eight years with rare exceptions (holidays, travel, occasionally noted in the previous issue's closing paragraph). At the source commit covered by this guide, **393 consecutive issues** have shipped between 2018-04-23 and 2026-04-17.

**Q: Is reading the newsletter free?**

Yes. The GitHub repository is public and the blog cross-posts are open. There is no paywall, no membership tier, no premium edition. Submission and corrections are also free — the issue tracker is open to any GitHub user.

**Q: Is there an official email subscription?**

No. The closest equivalent is the blog's RSS feed at `https://www.ruanyifeng.com/blog/atom.xml`. Many free RSS-to-email gateways (Blogtrottr, Kill the Newsletter, Feed-to-Email) will deliver the feed as per-post emails if you prefer that channel.

**Q: Can I republish or translate the content?**

The repository ships **no LICENSE file**, so the prose is implicitly copyrighted by the author. Short quotations with attribution fit within fair-use norms. Wholesale republication of an essay, commercial reuse, or formal translation requires written permission — email `[email removed]`. Some community translation forks exist; they are not endorsed by the author but are usually not contested either.

**Q: Why are early issues titled `每周分享` instead of `科技爱好者周刊`?**

The newsletter launched in April 2018 under the name `每周分享` ("Weekly Sharing"). It was renamed to the current `科技爱好者周刊` ("Technology Enthusiasts Weekly") a few dozen issues in. Old titles were not retroactively rewritten, so early files keep their original headings.

**Q: How do I cite a specific issue in my own writing?**

The canonical citation is the blog URL — for example, `https://www.ruanyifeng.com/blog/2026/04/weekly-issue-393.html` — because the URL is stable and accumulates comment history. The GitHub URL (`https://github.com/ruanyf/weekly/blob/master/docs/issue-393.md`) is also acceptable; engineers often prefer it because the rendering is cleaner and Markdown diffs are legible.

**Q: How do I find issues about a specific technology?**

Use one of three search strategies (see `§5.2`):

- GitHub repository search box at `github.com/ruanyf/weekly`.
- Engine query: `site:ruanyifeng.com/blog weekly-issue keyword`.
- Local clone: `grep -rli "keyword" docs/issue-*.md`.

There is no tag system — keyword search is the only mechanism.

**Q: Are there topic-organized landing pages?**

Yes — eight short topic pages under `docs/subjects/` cover CSS, databases, developer tooling, Docker, Go, Linux, math, and web utilities. Three free-resource pages under `docs/` cover music, photos, and software. None are exhaustive references; treat them as the author's personal reading lists.

**Q: Can I submit a paid tool, or only free tools?**

Both. Free-tier tools and paid-but-useful tools regularly appear in `工具` and `资源` sections. What gets rejected is pure advertising or affiliate-link drops; what gets accepted is "a thing a developer might pay for because it solves a real problem."

**Q: Can I submit an essay or guest article?**

The opinion essays are written by the author personally. There is no documented essay-submission channel. Your best path is to publish your essay on your own blog or platform and submit that URL as a website recommendation — it may end up in the `文摘` (Digest) section.

**Q: Where does the Who's Hiring board live, and how is it structured?**

The current pinned hiring thread is **[issue #9454](https://github.com/ruanyf/weekly/issues/9454)**. Employers post recruiting messages as comments; job-seekers read and apply directly using each poster's contact method. There is no résumé upload, no application tracking, no matching algorithm — just a public bulletin board. When a thread becomes unwieldy, a new issue is opened and pinned.

**Q: Are there any third-party email digests of the newsletter?**

Yes — community mirrors exist. They scrape the blog and re-send entries as emails. They are not run by the author and are out of his control. They are usually accurate, but the canonical source is always the GitHub repo and the blog at `ruanyifeng.com`.

**Q: Will the newsletter ever stop?**

The author has shipped 393 issues over eight years and shows no sign of stopping. If a shutdown is ever announced, the archive remains readable — the GitHub repository is public and the blog is self-hosted.

**Q: How do I unsubscribe from the Who's Hiring pinned issue if it is filling my GitHub notifications?**

Click the bell icon on `https://github.com/ruanyf/weekly/issues/9454` and set it to **Not watching**. GitHub stops emailing you about new comments. The issue thread stays readable; you simply stop receiving notifications.

**Q: Is there an English version of the newsletter?**

There is no official English edition. Some community translation forks exist on GitHub but are not endorsed. Modern machine translation (Google Translate, DeepL, ChatGPT) handles the prose well — the technical terms are mostly English loanwords, the author's style is direct, and individual issues are short.

**Q: What happens if I report a security disclosure?**

There is no running service to disclose against — the repository is content-only. If you find a hijacked outbound link, a compromised CDN path, or a phishing payload in an issue-tracker comment, email `[email removed]` rather than filing a public issue. Routine dead-link reports go in the public tracker.

**Q: Why does the issue index in `README.md` look hand-maintained?**

Because it is. There is no automated index regenerator. Each new issue ships with a manual `README.md` edit that adds a bullet at the top of the current month. This is robust — the author has not missed an entry in eight years — but it does mean the index is human-curated rather than build-output.

---

_Generated April 2026 from ruanyf/weekly at c5d3c9b. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._