站点构建与部署说明

本仓库可以构建为一个纯静态文档站(风格参考 vibevibe.cn):每个 Markdown 文档生成一个独立 HTML 页面,带左侧章节树、全文搜索、代码高亮、KaTeX 公式、上一篇/下一篇导航和本页目录。产物输出到 site/ 目录,可部署到任意静态文件服务器(Nginx / Caddy / 对象存储等),无需后端。

构建步骤

bashnpm install        # 首次安装依赖
npm run build:site # 生成静态站点到 ./site/

构建完成后 site/ 即为完整站点(约 313 个文档页 + 引用的图片/视频等资源)。

体积提示:完整站点约 885 MB,其中教程演示视频/GIF 约 400 MB、图片约 341 MB、页面与代码约 144 MB。如果服务器空间或带宽有限,可以只上传部分章节目录,或先不上传 *.mp4(对应视频页会暂时看不到演示视频,其余内容不受影响)。

本地预览(任选其一):

bashnpx serve site
# 或
python -m http.server 8000 --directory site

然后访问 http://localhost:8000 (或 serve 提示的端口)。

部署到服务器

把 site/ 目录的全部内容上传到服务器站点根目录,例如:

bashrsync -avz --delete site/ user@your-server:/var/www/every-embodied/

Nginx 参考配置

nginxserver {
    listen 80;
    server_name your-domain.com;
    charset utf-8;
    root /var/www/every-embodied;
    index index.html;

    # gzip 压缩(站点 HTML/JSON 较大,强烈建议开启)
    gzip on;
    gzip_types text/html text/css application/javascript application/json image/svg+xml;
    gzip_min_length 1024;

    location / {
        try_files $uri $uri/ =404;
    }

    error_page 404 /404.html;
}

要点:

charset utf-8; 必须有——文档路径包含中文(浏览器会自动按百分号编码请求,Nginx 会正确解码)。
页面全部是真实 .html 文件,不依赖任何 rewrite/SPA fallback。
建议开启 gzip;site/assets/search-index.json(约 1.1 MB)压缩后约 300 KB。

站点功能

导航:顶栏 Logo 回首页;左侧章节树,当前章节展开,其余分组点击展开(首次展开时加载 assets/sidebar.json)。
搜索:右上角搜索框,快捷键 / 或 Ctrl/⌘+K,支持标题/正文匹配与关键词高亮。
阅读:代码一键复制(带 highlight.js 语法高亮)、表格横向滚动、图片/视频自适应、KaTeX 数学公式、标题锚点链接、宽屏右侧"本页目录"高亮跟随、上一篇/下一篇、回到顶部。
外观:自动适配浅色/深色模式(跟随系统)。
404:404.html 已生成,Nginx 配置 error_page 即可。

重新生成

内容(markdown)更新后重新执行 npm run build:site 即可。构建脚本会:

重新收集所有中文文档(英文 en/、.translation/ 等内部目录自动排除);
渲染每个文档为 HTML(服务端完成,浏览器无需渲染 Markdown);
仅拷贝文档中实际引用的图片/视频/PDF 等资源(仓库其余大文件不进站点);
构建结束后自检所有内部链接,失效链接会以 broken internal links 列表输出。

已知:当前内容中有约 40 条失效链接,均为源 markdown 本身指向不存在的文件(例如作者本地路径 C:/Users/...、被 gitignore 的数据目录 demo_data/ 等),不影响站点其他页面,可按需修源文件。