OI Wiki 项目指南：编程竞赛知识库的内容体系与本地部署实践-酒店常州论坛

OI Wiki 项目指南：编程竞赛知识库的内容体系与本地部署实践

【免费下载链接】OI-wiki:star2: Wiki of OI / ICPC for everyone. （某大型游戏线上攻略，内含炫酷算术魔法）项目地址: https://gitcode.com/GitHub_Trending/oi/OI-wiki

OI Wiki（本项目仓库名为OI-wiki/OI-wiki）是一个面向编程竞赛（Competitive Programming / OI / ICPC）的免费开源知识整合站点，采用 MkDocs 静态站点生成器构建。本文以仓库 README.md 为线索，结合仓库内的构建配置与脚本源码，系统介绍该知识库的内容组织方式、技术栈构成、完整的本地部署流程（含镜像与离线版本）以及参与贡献和版权使用的要点，帮助你快速在本机搭建一套可浏览、可调试的 OI Wiki 环境，并理解其站点构建流水线的底层原理。

项目定位：一份持续更新的编程竞赛知识整合站点

编程竞赛发展多年，难度越来越高、内容越来越复杂，而网上资料大多零散，初学者往往不知道如何系统地学习相关知识。为方便热爱编程竞赛的小伙伴更好地入门，2018 年 7 月起 OI Wiki 迁移至 GitHub 并持续演进至今，致力于成为一个免费开放且持续更新的知识整合站点，为读者提供竞赛中的基础知识、常见题型、解题思路以及常用工具等内容，帮助大家更快速深入地学习编程竞赛。

当前仓库仍处于持续完善阶段，知识点覆盖尚不全面，也存在一些低质量页面需要修改。这类待完善内容的跟踪主要依靠 GitHub Issues 以及标签为 "Iteration Plan / 迭代计划" 的迭代计划页面。项目源于社区、提倡知识自由，并明确承诺未来不会商业化，始终保持独立自由的性质。

内容体系：从语言基础到专题实战的十大板块

站点的全部页面位于仓库 docs/ 目录下，由根目录 mkdocs.yml 中的nav字段统一定义导航结构。从当前仓库的导航配置看，内容按以下大板块组织：

板块	主要内容	文档目录
简介	项目介绍、如何参与、格式手册、数学符号表、F.A.Q.、镜像站列表	docs/intro/
比赛相关	OI / ICPC 赛事与赛制、题型、学习路线、常见错误与技巧、出题	docs/contest/
工具软件	编辑器、评测工具、命令行、编译器、Testlib、Polygon、Git 等	docs/tools/
语言基础	C++ 语法、STL 容器与算法、面向对象、Lambda、pb_ds、Python/Java 速成	docs/lang/
算法基础	复杂度、枚举、模拟、分治、贪心、十余种排序、前缀和、二分、倍增、构造	docs/basic/
搜索	DFS/BFS、双向搜索、启发式搜索、A、IDA、Dancing Links、Alpha–Beta 剪枝	docs/search/
动态规划	背包、区间、树形、状压、数位、插头、计数、动态 DP 及多种 DP 优化	docs/dp/
字符串	哈希、Trie、KMP、AC 自动机、后缀数组/自动机、Manacher、回文树等	docs/string/
数学	数论、多项式与生成函数、组合数学、线性代数、线性规划、抽象代数、概率论、博弈论	docs/math/
数据结构	栈、队列、哈希、并查集、堆、线段树族、平衡树族、可持久化结构、动态树等	docs/ds/
图论	存储与遍历、树论、最短路、生成树、网络流、图匹配、Prüfer 序列等	docs/graph/
计算几何	二维/三维基础、凸包、扫描线、旋转卡壳、半平面交、最近点对	docs/geometry/
杂项	离散化、双指针、离线算法（CDQ 分治、整体二分、莫队族）、随机化、Kahan 求和等	docs/misc/
专题	RMQ、并查集应用、括号序列、线段树与离线询问	docs/topic/

值得注意的仓库特色是：每个知识板块都配有可编译验证的示例代码与输入输出样例。例如 docs/basic/code/ 下按排序算法分子目录存放 C++ / Python / Java 实现，docs/basic/examples/ 下则一一对应.in/.ans数据文件；数学、数据结构、图论等板块同样遵循code/+examples/的配套结构。这为文档中的每个算法提供了"可运行、可对照"的实证支撑。

技术栈与构建体系

核心构建工具：MkDocs + Python + uv

项目采用 MkDocs 中锁定了核心依赖版本：

mkdocs==1.5.3
pymdown-extensions==10.16.1
markdown==3.9
pygments（代码高亮）
beautifulsoup4、requests
python-markdown-document-offsets-injection-extension==0.5.16（文档偏移注入，用于锚点定位）
mkdocs-toggle-sidebar-plugin==0.0.8（侧边栏折叠）

项目要求 Python 版本不低于 3.10。依赖索引在 pyproject.toml 中同时配置了官方 PyPI 与清华 TUNA 镜像作为 extra-index，便于国内网络环境安装。

自定义主题与第三方资源

站点主题并非 MkDocs 内置 Material 主题，而是通过 Git 子模块引入的自定义主题仓库。根目录 .gitmodules 声明了子模块mkdocs-material（指向OI-wiki/mkdocs-material），主题模板目录为 mkdocs-material/material/templates。mkdocs.yml 中通过theme.custom_dir指向该目录，并启用了深色/浅色双配色（palette）、代码复制按钮（content.code.copy）、即时导航（navigation.instant）等 Material 特性。

主题运行还依赖两类需联网下载的第三方资源，下载链接可在构建前通过环境变量覆盖：

MathJax（数学公式渲染库）：默认从 npm registry 下载mathjax-4.0.0.tgz；
Material 图标字体。

这两类资源的下载逻辑见 scripts/pre-build/install-theme-vendor.sh，其中MATHJAX_URL与MATERIAL_ICONS_URL是控制下载链接的配置项。

站点配置要点（mkdocs.yml）

mkdocs.yml 中还有几个值得关注的点：

服务器端渲染 MathJax：extra_javascript引入了_static/js/math-csr.js?math-csr与assets/vendor/mathjax/tex-mml-chtml.js?math-csr，即本项目采用服务器端渲染（CSR，即构建时渲染）数学公式，而非纯浏览器端渲染；markdown_extensions中的pymdownx.arithmatex配合generic: true提供了$$...$$/$...$数学语法支持；
Hooks 自定义 Jinja 过滤器：hooks字段注册了 hooks/on_env.py，它在构建时向模板环境注入nav_math过滤器，用于在导航标题中正确渲染内联数学公式；
反馈系统注入：extra_javascript/extra_css中形如{OIWikiFeedbackSystemFrontendJS}的占位符，会在构建前由 scripts/pre-build/pre-build.sh 调用install-feedback-sys-frontend.ts替换为实际的前端资源路径（对应产物可见于 docs/_static/js/oiwiki-feedback-sys-frontend.js）。

本地部署全流程

官方推荐在本地部署，需要安装 Python3 和 uv。完整步骤如下（与 README.md 保持一致）：

git clone https://github.com/OI-wiki/OI-wiki.git --depth=1 cd OI-wiki # 安装 uv (如果尚未安装) pip install uv # 安装依赖 uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple/ # 使用我们的自定义主题（Windows 下请使用 Git Bash 执行） # 安装主题时将连接网络下载资源，可通过以下配置项控制下载链接 # .gitmodules: # - url # scripts/pre-build/install-theme-vendor.sh: # - MATHJAX_URL # - MATERIAL_ICONS_URL ./scripts/pre-build/install-theme.sh # 两种方法（选其一即可）： # 1. 运行一个本地服务器，访问 http://127.0.0.1:8000 可以查看效果 uv run mkdocs serve -v # 2. 在 site 文件夹下得到静态页面 uv run mkdocs build -v # 获取 mkdocs 的命令行工具的说明（解释了命令和参数的含义） uv run mkdocs --help

各步骤说明与底层原理

git clone --depth=1：浅克隆只拉取最新提交，能显著减少仓库体积。克隆后仓库内同时包含文档源码、mkdocs.yml配置、scripts/构建脚本以及mkdocs-material/主题子模块目录。
uv sync --index-url ...：uv 依据 pyproject.toml 与uv.lock创建虚拟环境并安装全部依赖。--index-url指定 PyPI 镜像源，国内可替换为清华 TUNA 源以加速。
./scripts/pre-build/install-theme.sh：这一步执行 scripts/pre-build/install-theme.sh，内部完成两件事：
- git submodule update --init --recursive拉取mkdocs-material主题子模块；
- 调用install-theme-vendor.sh下载 MathJax 与 Material 图标等第三方资源到mkdocs-material/material/templates/assets/vendor目录。
若处于 Netlify 环境（PREBUILD_NETLIFY=1），脚本会先清理主题缓存。如果该步骤下载资源失败，脚本会给出错误提示并保留临时目录供排查（见 install-theme-vendor.sh 的_when_error处理逻辑）。
uv run mkdocs serve -v：启动内置开发服务器并监听http://127.0.0.1:8000，-v输出详细日志，适合边编辑文档边实时预览。
uv run mkdocs build -v：生成静态站点到site/目录，可直接交给任意静态文件服务器托管。

自定义主题安装的可控性

README 特别指出，安装主题时需要联网下载资源，且下载链接是可配置的，涉及两处文件：

.gitmodules 中的url字段：控制主题子模块的拉取地址，网络受限时可替换为镜像仓库；
scripts/pre-build/install-theme-vendor.sh 中的MATHJAX_URL与MATERIAL_ICONS_URL环境变量：控制 MathJax 与 Material 图标资源的下载链接（MathJax 默认值为https://registry.npmjs.org/mathjax/-/mathjax-4.0.0.tgz）。

用 Docker 快速搭建构建环境

仓库根目录的 Dockerfile 提供了一条容器化路径，适合不想污染本机 Python/Node 环境的用户。其构建逻辑包括：

基于 Ubuntu 22.04，安装git、wget、curl、gcc/g++、make以及 Node.js 18；
通过官方脚本安装 uv；
通过构建参数WIKI_REPO（可指向任何镜像仓库，避免 GitHub 不可达）、PYPI_MIRROR（PyPI 镜像源）、LISTEN_IP/LISTEN_PORT（默认0.0.0.0:8000）控制克隆与安装行为；
在容器内执行uv sync与yarn --frozen-lockfile完成依赖安装。

生产环境构建（CI / Netlify）

GitHub Actions：生产构建流程见.github/workflows/build.yml（README 中提及用于服务器端渲染 MathJax 的参考实现，需要安装 Node.js）。构建前后脚本的分类说明见 scripts/README.md：
- pre-build：安装主题与第三方库（install-theme.sh、install-theme-vendor.sh），以及 CI 生产构建脚本pre-build.sh（安装主题、将 Git 短哈希写入mkdocs.yml的githash字段、注入反馈系统前端资源）；
- post-build：渲染页面中的数学公式、渲染 Git commits 信息（更新时间与贡献者列表）、生成跳转页面；
- post-deploy：baidu-push.sh与convert-sitemap.py用于将 sitemap 转换并推送至百度搜索。
Netlify 预览构建：netlify.toml 将构建基目录设为scripts/以跳过平台自动装依赖，再执行 scripts/netlify/build.sh，其流程为：安装 uv →uv sync+yarn --frozen-lockfile→PREBUILD_NETLIFY=1运行pre-build.sh→mkdocs build→ 用 Node.js 执行html-postprocess.ts（commits-info、math、external-links 等后处理），并设置了 3 GB 的 Node 内存上限（NODE_OPTIONS="--max_old_space_size=3072"）。

镜像站点与离线版本

主站部署在 oi-wiki.org，同时在 status.oi-wiki.org 维护了一份镜像站列表，镜像内容与主站保持一致。

镜像仓库克隆

若 GitHub 访问不便，可使用码云（Gitee）上的镜像仓库，内容与 GitHub 仓库相同：

git clone https://gitee.com/OI-wiki/OI-wiki.git

离线版

可以直接使用gh-pages分支的内容——该分支保存的是已构建好的静态站点产物：

git clone https://gitee.com/OI-wiki/OI-wiki.git -b gh-pages

克隆后在本地启动一个 http 服务器即可浏览，无需任何构建步骤：

# 如果是 python3 python3 -m http.server # 如果是 python2 python2 -m SimpleHTTPServer # 有些环境下找不到名叫 python3/python2 的可执行文件，不妨运行 python 试试

注意：python2 -m SimpleHTTPServer仅适用于 Python 2 环境；现代系统一般只有 Python 3，直接使用python3 -m http.server即可（默认端口 8000）。

参与贡献与质量保障

OI Wiki 欢迎社区成员编写内容、分享所学。具体的贡献方式说明见站点内 docs/intro/htc.md（如何参与）。仓库同时提供了一套文档质量保障脚本，可作为贡献时的自检工具（详见 scripts/README.md）：

scripts/check-characters.py：扫描修改的 Markdown 与 TeX 文件，检测异常非可见字符与可替换为 CJK 字符的部首/笔画字符；
scripts/correctness_check.py 与get_files_to_test.py：用于测试文档中的示例代码能否正常编译运行（对应测试目录 test/）；
scripts/linter/：配合 scripts/linter_patch.py 修正文档格式化问题，其 README 与单元测试位于 scripts/linter/README.md 和 test/linter/；
scripts/celebration.py：自动创建庆祝 star 数量里程碑的 issue。

如果本地部署或使用遇到问题，可先查阅 docs/intro/faq.md（F.A.Q.）了解更多信息。

版权声明与引用方式

除特别注明外，项目中除了代码部分，均采用知识共享署名-相同方式共享 4.0 国际许可协议（CC BY-SA 4.0）及附加的 The Star And Thank Author License（SATA）进行许可。换言之，使用过程中可以自由地共享、演绎，但必须署名、以相同方式共享、分享时没有附加限制，并且应为 GitHub 仓库点赞（Star）。

如需在论文或技术报告中引用该仓库，README 提供了现成的 BibTeX 条目：

@misc{oiwiki, author = {OI Wiki Team}, title = {OI Wiki}, year = {2016}, publisher = {GitHub}, journal = {GitHub Repository}, howpublished = {\url{https://github.com/OI-wiki/OI-wiki}}, }

总结

OI Wiki 仓库是一个"文档即代码"的典型实践：知识内容以 Markdown 形式存放在 docs/，配套可编译的示例代码与测试数据；构建体系以 MkDocs + uv 为核心，辅以自定义 Material 主题子模块、服务器端 MathJax 渲染、Git 子模块资源管理和一套完整的 pre-build / post-build / post-deploy 流水线。按照本文给出的命令，你可以轻松在本机serve预览或build出完整静态站点，也可以通过镜像仓库或gh-pages离线分支快速获取站点内容，在本地搭建起属于自己的编程竞赛知识环境。

【免费下载链接】OI-wiki:star2: Wiki of OI / ICPC for everyone. （某大型游戏线上攻略，内含炫酷算术魔法）项目地址: https://gitcode.com/GitHub_Trending/oi/OI-wiki

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析