使用与更新教程

本站是公司文档中心，由 MkDocs + Material 生成、发布在 GitHub Pages 上。 这篇教程说明怎么维护、怎么更新、怎么发布，文末提供一键脚本和下载入口。

一句话原理

docs/ 里的 Markdown 是源文件 → 用 mkdocs 构建成静态网站 → 推送到仓库的 gh-pages 分支 → 域名 https://wiki.anxinddecs.cn/ 自动更新。

---

一、目录结构

AnxindeWiki/
├─ mkdocs.yml            # 站点配置(站点名、导航、主题)
├─ requirements.txt      # 依赖清单(mkdocs、material)
├─ docs/                 # ★ 所有文档正文都在这里
│  ├─ index.md           # 首页
│  ├─ wiki-guide.md      # 本教程
│  ├─ CNAME              # 自定义域名(勿删)
│  └─ geo/
│     ├─ basics.md       # GEO 新手教程
│     └─ images/         # 图片(83 张)
└─ scripts/              # 一键脚本
   ├─ publish.ps1        # 构建 + 发布
   ├─ serve.ps1          # 本地预览
   └─ publish.bat        # 双击即可发布(Windows)

未列出的页面

有些文章可能是刻意隐藏的：不加入导航、使用随机地址，并且不被搜索与站点地图收录。这类页面不会出现在上面的目录说明里。

---

二、方式 A：网页直接改（零环境，适合快速改错别字）

1. 打开仓库 https://github.com/Anxinde13/AnxindeWiki，进入要改的文件（如 docs/geo/basics.md）；
2. 点右上角 铅笔图标 编辑，改完在页面底部填一句说明，点 Commit changes；
3. 改动只进了 main 分支，还需要“发布”一次才会出现在网站上： 让有环境的同事在本地执行 scripts/publish.ps1（见第四节），或走方式 B。

重要

因为本站是本地构建发布（未使用 GitHub Actions 自动构建），所以网页改完后必须再发布一次，否则官网不会变。

---

三、方式 B：本地更新（推荐，可先预览再发布）

1. 下载或克隆仓库

• 直接下载 ZIP： 下载整站源码 ZIP
• 或用 Git：

git clone https://github.com/Anxinde13/AnxindeWiki.git

2. 安装环境（只做一次）

需要 Python 3.9+（安装时勾选 Add Python to PATH）。然后在仓库根目录执行：

python -m pip install -r requirements.txt

3. 本地预览

python -m mkdocs serve

浏览器打开 http://127.0.0.1:8000/，边改边看，Ctrl+C 停止。

4. 发布到官网

确认无误后执行：

python -m mkdocs gh-deploy --force

约 1 分钟后访问 https://wiki.anxinddecs.cn/ 即可看到更新。

---

四、一键脚本（推荐日常使用）

在 scripts/ 目录下已备好脚本，下载后放到仓库根目录的 scripts\ 里（ZIP 整包下载则已包含）。

脚本	作用	下载
publish.ps1	自动装依赖 → 构建 → 发布	下载
serve.ps1	自动装依赖 → 本地预览	下载
publish.bat	双击运行发布脚本	下载

用法：双击 publish.bat，或在仓库根目录执行：

powershell -ExecutionPolicy Bypass -File .\scripts\publish.ps1

publish.ps1 源码（构建 + 发布）

# publish.ps1 —— 一键构建并发布 AnxindeWiki 到 GitHub Pages
# 在仓库根目录执行： powershell -ExecutionPolicy Bypass -File .\scripts\publish.ps1
$ErrorActionPreference = "Stop"

$repo = Split-Path -Parent $PSScriptRoot
Set-Location -LiteralPath $repo

Write-Host "[1/3] 检查依赖 ..." -ForegroundColor Cyan
python -c "import mkdocs" 2>$null
if ($LASTEXITCODE -ne 0) {
    Write-Host "未检测到 mkdocs，正在安装 requirements.txt ..." -ForegroundColor Yellow
    python -m pip install -r requirements.txt
}

Write-Host "[2/3] 本地构建 ..." -ForegroundColor Cyan
python -m mkdocs build
if ($LASTEXITCODE -ne 0) { throw "构建失败，请检查上面的报错。" }

Write-Host "[3/3] 发布到 GitHub Pages（gh-pages 分支）..." -ForegroundColor Cyan
python -m mkdocs gh-deploy --force
if ($LASTEXITCODE -ne 0) { throw "发布失败（检查网络 / GitHub 登录 / 推送权限）。" }

Write-Host "完成！约 1 分钟后访问 https://wiki.anxinddecs.cn/" -ForegroundColor Green

serve.ps1 源码（本地预览）

# serve.ps1 —— 本地预览 AnxindeWiki
$ErrorActionPreference = "Stop"

$repo = Split-Path -Parent $PSScriptRoot
Set-Location -LiteralPath $repo

python -c "import mkdocs" 2>$null
if ($LASTEXITCODE -ne 0) { python -m pip install -r requirements.txt }

Write-Host "本地预览： http://127.0.0.1:8000/  （Ctrl+C 停止）" -ForegroundColor Green
python -m mkdocs serve

publish.bat 源码（双击发布）

@echo off
chcp 65001 >nul
powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0publish.ps1"
echo.
pause

---

五、新增 / 修改内容

新增一篇文档

1. 在 docs/ 下新建 .md 文件，例如 docs/geo/faq.md，第一行写标题：

   # 常见问题
   

2. 在 mkdocs.yml 的 nav: 里加一行（缩进对齐）：

   nav:
     - 首页: index.md
     - 安信德GEO优化系统手册:
         - GEO 新手教程: geo/basics.md
         - 常见问题: geo/faq.md   # ← 新增
   

3. 用 serve.ps1 预览，无误后 publish.ps1 发布。

插入图片

1. 把图片放到 docs/geo/images/，例如 docs/geo/images/faq_01.png；
2. 在文档里用相对路径引用：

   ![图片说明](images/faq_01.png)
   

小技巧

也可以直接把图片拖进 GitHub 网页编辑框，自动上传并生成链接，省去手动放图片。

隐藏一篇文章（不公开）

想让某篇文章“不进导航、只能靠特定地址访问”，按 5 步做：

1. 把文件改成随机文件名，例如 docs/geo/xxxxxxxx.md（地址越乱越难猜）；
2. 从 mkdocs.yml 的 nav: 里删掉它，并在文件顶部加元数据，让它不进搜索：

   ---
   search:
     exclude: true
   ---
   

3. 在 mkdocs.yml 顶部登记为“有意不进导航”（否则构建会告警）：

   not_in_nav: |
     geo/xxxxxxxx.md
   

4. 删掉所有指向它的链接（首页、其它文章里的引用）；
5. 发布后，只有知道完整地址的人能访问：https://wiki.anxinddecs.cn/geo/xxxxxxxx/。

它能挡住谁

这种方式只是“不给入口”，不是真正的权限：仓库是公开的，知道地址、或去翻源码的人仍然能看到内容。需要真正保密请用登录门禁（如 Cloudflare Access）。

---

六、常见问题

发布后官网没变化？

• 确认执行的是 publish.ps1（或 mkdocs gh-deploy --force）而不是只 commit；
• GitHub Pages 有 1 分钟左右构建延迟，稍等再刷新（可用 Ctrl+F5 强制刷新）。

提示 mkdocs 不是内部或外部命令？

用 python -m mkdocs ... 的写法即可（脚本里已经是这种写法）。若仍报错，说明 Python 未装好或没加入 PATH。

推送时要求登录 / 报 403？

发布需要本机能推送到 Anxinde13/AnxindeWiki。用 Git 凭据管理器登录一次，或先用 gh auth login 登录 GitHub。

域名怎么绑定的？

docs/CNAME 文件固定为 wiki.anxinddecs.cn，DNS 里配一条 CNAME wiki -> anxinde13.github.io，GitHub 仓库 Settings → Pages 中 Custom domain 填 wiki.anxinddecs.cn 并勾选 Enforce HTTPS。不要删除 docs/CNAME。