静态站点与文档站：完整实践与解答

需能阅读 YAML 与 Markdown 相对链接。两页文档站示例固定 MkDocs 1.6.1，使用 pages/ 存源码、output/ 存构建结果，并演示 /handbook/ 子路径；先对照 mkdocs.yml、页面链接和 README，再判断导航与输出地址。 示例未在本轮执行；本页完整源码与README列出输入、阅读顺序和预期。

静态站点 完整项目

静态站点完整项目包含mkdocs.yml、两篇Markdown与requirements.txt。示例未执行；nav、docs_dir和site_dir相互一致，代码围栏与普通链接不依赖额外插件，README列出构建和清理范围。

静态站点 地址练习

题目：站点部署在/handbook/，链接写成/about/有什么问题？

参考答案

根相对链接跳到域名根下about，可能404；本例在首页使用guide.md让生成器解析页面地址，并核对最终生成路径。

静态站点 输出清理

静态站点输出清理仅针对配置中独立site_dir目录。先检查绝对目标确实在练习目录内，不把docs_dir当输出删除；重建能恢复生成HTML，不能恢复误删的原始文章。

完整源码、配置与输入

下列文件与仓库同源，包含完整实现和输入；不是运行证明。部分练习只需人工阅读配置，不强制构造模拟器。

mkdocs.yml

site_name: Offline Handbook
site_url: https://example.invalid/handbook/
docs_dir: pages
site_dir: output
use_directory_urls: true
theme:
  name: mkdocs
nav:
  - Home: index.md
  - Guide: guide.md
markdown_extensions:
  - fenced_code

pages/index.md

# Offline Handbook

This is a fictional handbook. Read the [guide](guide.md).

pages/guide.md

# Guide

Keep source in pages and generated files in output.

```text
source -> generator -> HTML
```

Return [home](index.md).

requirements.txt

# Teaching version, not a claim about the latest release.
mkdocs==1.6.1

项目README与完整依赖

README提供前置、完整自跑或阅读方式、预期、失败案例与恢复清理。本轮没有执行任何示例、产品CLI、模型或外部API。

# 静态站点与文档站：完整教学包

示例未执行。全部输入为教学虚构资料，不能用于真实账号、生产数据或外部系统。

## 前置与依赖

MkDocs1.6.1教学版本，依赖见requirements.txt，标准主题；各OS命令相同但必须提前备好环境。

## 文件与输入

- `mkdocs.yml`：本包完整文件。
- `pages/index.md`：本包完整文件。
- `pages/guide.md`：本包完整文件。
- `requirements.txt`：本包完整文件。

## 读者将来自跑或阅读

复制本包所有文件到独立目录，在该目录作为当前工作目录。以下是读者自用资料，本轮禁止执行。

```text
mkdocs build --config-file mkdocs.yml --strict
```

## 正常预期

将来安装requirements声明版本后，在独立目录构建output/index.html与output/guide/index.html；不是发布。

## 失败案例与恢复

nav写missing.md或首页链接不存在文件时严格构建应报告问题；本轮未安装或执行，不声称实际诊断文本一致。

## 清理及能力边界

不运行mkdocs serve或部署命令；人工核对output绝对路径后仅删除该输出，保留pages和mkdocs.yml。

## 来源

- [官方依据](https://www.mkdocs.org/user-guide/configuration/)（2026-10-17资料核对；不是运行证明）

依据与适用范围

• 本课官方依据，资料核对日2026-10-17。

本课完成的是列明任务的理论与静态资料，不代表产品全部能力或三平台运行通过。历史文档保留旧URL；涉及账号、版本、价格与界面位置时，以对应官方资料及实际授权环境为准。