若君只欲一篇而尽知 JekyllNet 今可如何用此文即其总册。项目入口仓库地址https://github.com/JekyllNet/JekyllNet文档网站https://jekyllnet.helpGitHub 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-site3) 本地预览dotnet run --project .\JekyllNet.Cli -- serve --source .\docs --port 5055浏览器访问http://localhost:5055。三、日常编辑工作流1) 连续编辑时dotnet run --project .\JekyllNet.Cli -- watch --source .\docswatch适于改 Markdown、布局、include、样式并实时重建。2) 稳定预览时dotnet run --project .\JekyllNet.Cli -- serve --source .\docs --port 5055 --no-watchserve --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 branchBranch:mainFolder:/docs2) 用 GitHub Actions 构建产物可复用JekyllNet/actionv2在 CI 中构建并上传docs-siteartifact。详见站点部署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 与多语翻译成功率最高。