若君只欲一篇而尽知 JekyllNet 今可如何用，此文即其总册。
项目入口
- 仓库地址：https://github.com/JekyllNet/JekyllNet
- 文档网站：https://jekyllnet.help
- GitHub Pages 站点入口（仓库 Pages）：https://jekyllnet.github.io/JekyllNet/
一、安装与运行环境
今以 .NET 10 为基。
先验环境：
dotnet --version
克隆并进入仓库后，先跑一次测试以确认环境可用：
dotnet test .\JekyllNet.slnx
二、最小可用路径（5 分钟跑通）
1) 构建示例站点
dotnet run --project .\JekyllNet.Cli -- build --source .\sample-site
输出目录默认为 sample-site\_site。
2) 构建文档站
dotnet run --project .\JekyllNet.Cli -- build --source .\docs --destination .\artifacts\docs-site
3) 本地预览
dotnet run --project .\JekyllNet.Cli -- serve --source .\docs --port 5055
浏览器访问 http://localhost:5055。
三、日常编辑工作流
1) 连续编辑时
dotnet run --project .\JekyllNet.Cli -- watch --source .\docs
watch 适于改 Markdown、布局、include、样式并实时重建。
2) 稳定预览时
dotnet run --project .\JekyllNet.Cli -- serve --source .\docs --port 5055 --no-watch
serve --no-watch 适于演示或对照验证。
3) 含草稿与未来文章的预览
dotnet run --project .\JekyllNet.Cli -- serve --source .\sample-site --drafts --future --unpublished
四、配置与内容组织（推荐顺序）
- 先配置
_config.yml：站点信息、URL、分页、多语。 - 再配置
_layouts与_includes：统一页面壳层。 - 再整理
_posts、_docs、集合与 front matter。 - 最后补 Sass/SCSS 与静态资源结构。
建议先读：
- 配置指南
- 特性总览
- 兼容性说明
五、多语与 AI 翻译
JekyllNet 已具多语路线，可结合 AI 翻译做增量更新。
你可在 _config.yml 中配置翻译 provider、目标语言、缓存与术语表策略，再将中文源内容批量生成英文或其他语种页面。
详见：
- AI 翻译工作流
六、发布与自动化
1) GitHub Pages 直接发布 docs
仓库设置中选择：
- Deploy from a branch
- Branch:
main - Folder:
/docs
2) 用 GitHub Actions 构建产物
可复用 JekyllNet/action@v2 在 CI 中构建并上传 docs-site artifact。
详见：
- 站点部署
- CLI 与开发工作流
3) dotnet tool 打包
dotnet pack .\JekyllNet.Cli\JekyllNet.Cli.csproj -c Release
七、常见排错
1) 样式未编译
检查 Sass/SCSS 入口文件是否带 YAML Front Matter。
2) 链接异常
检查 _config.yml 的 url 与 baseurl 是否匹配当前部署方式。
3) 本地能过，CI 失败
优先对齐：
dotnet版本- 构建输入目录
- 是否遗漏
docs与生成器代码共同变更触发条件
八、按角色速查
- 内容编辑：先看 快速开始 与 CLI 与开发工作流
- 主题适配：先看 兼容性说明 与 特性总览
- 发布运维：先看 站点部署 与 项目新闻
- 多语运营：先看 AI 翻译工作流
九、一句话建议
先以 sample-site 验核心能力，再以 docs 验真实发布链路；本地跑通 build + serve 后，再接入 CI 与多语翻译，成功率最高。