fix: issue 86, and last updated missing fix (#87)

* fix(docs): correct LED wiring in GPIO article (refs #86)

原文「反过来接——阳极接引脚、阴极接地」与第一种接法(阳极接引脚、阴极接地)完全相同,且与下文「板载 LED 低电平点亮」自相矛盾。改为明确区分两种接法:源电流(source,电阻+LED 在引脚与地之间,高电平点亮)与灌电流(sink,电阻+LED 在电源与引脚之间,低电平点亮),并点明 PC13 板载 LED 为灌电流接法。CN/EN 同步修正。

* fix(site): restore Last Updated across split build

分卷构建(scripts/build.ts)把 md 复制到 gitignored 的 site/.vitepress/.build-tmp/ 再交 VitePress 构建。VitePress 的 lastUpdated 默认对构建源文件跑 git log 取时间,副本不在 git index 里拿不到历史(实测返回空),导致线上 Last Updated 消失。新增 git-timestamp.ts:transformPageData 用 pageData.relativePath 定位 documents/ 下真实源文件(副本保留目录结构、EN 带 en/ 前缀),对其 git log 取毫秒时间戳覆盖 pageData.lastUpdated,单位对齐 VitePress 内部 +new Date(--pretty=%ai)。本地构建验证:GPIO 页渲染 <time datetime=2026-06-15T11:08:53Z>,全站 1009 页含 last-updated 块。

Author: Charliechen114514

documents/en/vol8-domains/embedded/01-led/02-what-is-gpio.md

@@ -37,7 +37,11 @@ The physical condition for an LED (Light Emitting Diode) to light up is actually
 
 This is a purely passive circuit. As long as the power is connected, the LED stays lit, and you have no means of control.
 
-Now, let's replace VCC with a pin from the microcontroller. When this pin outputs a high level (for STM32, that is a voltage close to 3.3V), a path for current is established, and the LED lights up. When the pin outputs a low level (close to 0V), there is almost no voltage difference across the LED, no current flows, and the LED turns off. Thus, by controlling the level state of the pin, we achieve control over the LED's on/off state. Of course, you can also connect it the other way around—anode to pin, cathode to ground—in which case the LED lights up when the pin outputs a high level. Both methods are common in actual projects, and the onboard LED on the STM32F103C8T6 minimum system board uses the low-level-active connection, connected to the PC13 pin.
+Now, let's replace VCC with a pin from the microcontroller, and things get interesting. The most intuitive wiring puts the current-limiting resistor and LED in series between the pin and ground — the LED's anode (through the resistor) connects to the pin, and its cathode connects to ground. When the pin outputs a high level (for STM32, a voltage close to 3.3V), current flows out of the pin, through the resistor, through the LED, and back to ground, completing the loop and lighting the LED; when the pin outputs a low level (close to 0V), there is almost no voltage difference across the LED, no current flows, and the LED stays off. Here the pin is the "source" of current — current flows out of the pin into the external component — so this is called the current sourcing configuration, and the LED is active-high.
+
+But the LED can also be wired the other way around — with the resistor and LED in series between VCC and the pin — the LED's anode (through the resistor) connects to VCC, and its cathode connects to the pin. Now the loop only closes when the pin pulls low: with the pin low, current travels from VCC, through the resistor, through the LED, into the pin and back to ground inside the chip, lighting the LED; with the pin high, the anode sits at 3.3V and so does the cathode, the voltage difference is about zero, no current flows, and the LED stays off. Here the pin is the "sink" for current — current flows into the pin from the external component — so this is called the current sinking configuration, and the LED is active-low.
+
+Both configurations are common in real projects, and the choice usually comes down to hardware routing and the characteristics of the surrounding components. The onboard LED on the STM32F103C8T6 minimum system board (the so-called "Blue Pill") uses exactly the current-sinking configuration — it is connected to the PC13 pin and is active-low. This is also why, when we drive it later on, we have to keep its "lights up on low" temperament in mind.
 
 Next question: How does a microcontroller pin "output" a high or low level? A pin is not a wire; it cannot generate voltage out of thin air. Behind the pin is a complete set of digital circuits—MOSFETs (Metal-Oxide-Semiconductor Field-Effect Transistors), registers, and multiplexers. The code we write simply writes a value to a specific memory address. This value is translated by the hardware circuit into the conduction or cutoff of MOSFETs, and the conduction state of the MOSFETs determines whether the pin is at VDD (high level) or VSS (low level).
 

documents/vol8-domains/embedded/01-led/02-what-is-gpio.md

@@ -31,7 +31,11 @@ GPIO，全称General Purpose Input/Output，翻译过来就是"通用输入输
 
 这是一个纯粹的被动电路。只要电源接通，LED就一直亮着，你没有任何控制手段。
 
-现在，我们把VCC替换成单片机的一个引脚。当这个引脚输出高电平（对于STM32来说，就是接近3.3V的电压）时，电流有了通路，LED亮了。当引脚输出低电平（接近0V）时，LED两端几乎没有电压差，没有电流流过，LED灭。就这样，我们通过控制引脚的电平状态，实现了对LED亮灭的控制。当然你也可以反过来接——阳极接引脚、阴极接地——这时候引脚输出高电平LED才亮。两种方式在实际项目中都常见，而STM32F103C8T6最小系统板上那颗板载LED就是低电平点亮的接法，它连在PC13引脚上。
+现在，我们把VCC替换成单片机的一个引脚，事情就有意思起来了。最直观的接法，是把限流电阻和LED串接在引脚与地之间——LED的阳极（经电阻）接引脚，阴极接地。当引脚输出高电平（对于STM32来说，就是接近3.3V的电压）时，电流从引脚流出，经过电阻、流过LED、回到地，形成完整回路，LED亮；当引脚输出低电平（接近0V）时，LED两端几乎没电压差，没有电流流过，LED灭。这种接法里，引脚是电流的"源头"，电流从引脚流向外部器件，所以叫源电流（source current）接法，对应的LED是高电平点亮。
+
+但LED也可以反过来接——把限流电阻和LED串接在电源与引脚之间——LED的阳极（经电阻）接VCC，阴极接引脚。这时候回路要靠引脚拉低才能打通：引脚输出低电平时，电流从VCC出发，经过电阻、流过LED，从引脚灌入单片机内部回到地，LED亮；引脚输出高电平时，LED的阳极是3.3V、阴极也是3.3V，两端电压差约等于零，没有电流，LED灭。这种接法里，引脚是电流的"汇"，电流从外部器件流入引脚，所以叫灌电流（sink current）接法，对应的LED是低电平点亮。
+
+两种接法在实际项目里都很常见，选哪种往往取决于硬件布线和外围器件的特性。而STM32F103C8T6最小系统板（也就是常说的"蓝色药丸"Blue Pill）上那颗板载LED，用的正是灌电流接法——它连在PC13引脚上，低电平点亮。这也是为什么我们后面驱动它时，要特别留意它"低电平才亮"的脾气。
 
 接下来问题来了：单片机的引脚是如何"输出"高电平或低电平的？引脚不是电线，它不能自己凭空产生电压。引脚的背后是一整套数字电路——MOSFET（金属氧化物半导体场效应管）、寄存器、多路选择器。我们写的代码只是往某个内存地址写了一个数值，这个数值被硬件电路翻译成MOSFET的导通或关断，MOSFET的导通状态决定了引脚上是VDD（高电平）还是VSS（低电平）。
 

site/.vitepress/config/git-timestamp.ts

@@ -0,0 +1,52 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// 本文件恒定位于 site/.vitepress/config/,上推三级 = 项目根。
+// 用 import.meta.url 定位,分卷构建时本文件仍从真实位置加载(不被复制),路径稳定。
+const HERE = fileURLToPath(new URL('./', import.meta.url))
+const DOCUMENTS = join(HERE, '..', '..', '..', 'documents')
+
+const cache = new Map<string, number | undefined>()
+
+/**
+ * 返回某 markdown 源文件最后的 git 提交时间(毫秒),供 VitePress 的
+ * `transformPageData` 覆盖 `pageData.lastUpdated` 用。
+ *
+ * 为什么需要它:`scripts/build.ts` 分卷构建会把 `documents/` 下的 md 复制到
+ * `site/.vitepress/.build-tmp/`(gitignored) 再交给 VitePress 构建。VitePress 的
+ * `lastUpdated` 默认对构建源文件跑 `git log` 取时间,但这些副本不在 git index 里、
+ * 拿不到任何历史(实测 `git log` 对副本返回空),导致线上 "Last Updated" 一片空白。
+ *
+ * 解法:`transformPageData` 拿到的 `pageData.relativePath` 反映的是文件在 documents/
+ * 树里的相对位置——分卷副本原样保留了目录结构,EN 副本也带 `en/` 前缀——所以直接用
+ * 它在真实的 `documents/` 下定位源文件、对源文件跑 `git log`,把毫秒级时间戳喂回
+ * `pageData.lastUpdated`,绕开副本丢历史的问题。dev / 单体构建(srcDir 指向 documents/)
+ * 下查的也是同一份真实文件,行为与 VitePress 默认一致。
+ *
+ * 单位对齐:VitePress 内部 `getGitTimestamp` 用 `+new Date(git log --pretty=%ai)`,
+ * 结果是毫秒;这里用 `git log --format=%at`(秒) × 1000 对齐,避免显示成 1970 年。
+ */
+export function getGitTimestampMs(relativePath: string): number | undefined {
+  if (!relativePath) return undefined
+  if (cache.has(relativePath)) return cache.get(relativePath)
+
+  const realPath = join(DOCUMENTS, relativePath)
+  let result: number | undefined
+  if (existsSync(realPath)) {
+    try {
+      const out = execFileSync(
+        'git',
+        ['log', '-1', '--format=%at', '--', realPath],
+        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+      ).trim()
+      const sec = out ? parseInt(out, 10) : NaN
+      result = Number.isFinite(sec) ? sec * 1000 : undefined
+    } catch {
+      result = undefined // 非 git 仓库 / 无历史 → 回退,交由 VitePress 默认行为
+    }
+  }
+  cache.set(relativePath, result)
+  return result
+}

site/.vitepress/config/shared.ts

@@ -1,5 +1,6 @@
-import type { DefaultTheme } from 'vitepress'
+import type { DefaultTheme, PageData } from 'vitepress'
 import { navZh, navEn } from './nav'
+import { getGitTimestampMs } from './git-timestamp'
 import { kbdPlugin } from '../plugins/kbd-plugin'
 import { cppTemplateEscapePlugin } from '../plugins/escape-cpp-templates'
 import { mermaidPlugin } from '../plugins/mermaid-plugin'
@@ -38,6 +39,16 @@ export const sharedBase = {
   cleanUrls: true,
   lastUpdated: true,
 
+  // 分卷构建(scripts/build.ts)把 md 复制到 gitignored 的临时目录再交给 VitePress,
+  // VitePress 默认对副本跑 `git log` 拿不到历史,"Last Updated" 渲染不出来。这里改用
+  // documents/ 下真实源文件的提交时间覆盖 pageData.lastUpdated。详见 git-timestamp.ts。
+  async transformPageData(pageData: PageData) {
+    const ms = getGitTimestampMs(pageData.relativePath)
+    if (ms) {
+      pageData.lastUpdated = ms
+    }
+  },
+
   vite: {
     build: {
       chunkSizeWarningLimit: 5000,