Docfx.Build.ConceptualDocuments 2.71.0

使用 docfx 构建您的文档

• 入门
• 贡献
• 路线图
• 许可证
• .NET 基金会

使用 docfx 构建您的技术文档网站，包括首页、Markdown、.NET、REST API 的 API 文档等等。

⚠️⚠️⚠️ 注意 ⚠️⚠️⚠️

DocFX 正在过渡到 .NET 基金会，作为官方 .NET 项目！

• DocFX 团队正在改进主分支。这将向项目引入新功能和错误修复，删除一些不再必要的较旧代码和功能，以及更新依赖关系和简化项目结构。请关注路线图。
• 由于网站架构变更，DocFX 无法再直接支持构建Microsoft Learn 内容。仍将接受 Markdown 内容的 pull request 和更改的开源存储库保留，但它们不能直接与 DocFX 一起构建。
• 向前推进，我们只支持该工具作为新网站的静态网站生成器，而不是作为在 Microsoft Learn 上构建官方 Microsoft 内容的工具。

入门

1. 将 docfx 安装为全局工具

   dotnet tool install -g docfx
   

2. 在本地创建并启动一个网站

   docfx init -q
   docfx build docfx_project\docfx.json --serve
   

3. 访问 https://127.0.0.1:8080 查看示例网站。

获取更多信息，请参阅 入门指南。

贡献

对于问题和一般讨论，请使用 讨论区。通过 问题追踪报告错误和提出功能建议。

我们欢迎通过拉取请求贡献代码。标记为 help-wanted 的问题很适合开始贡献代码。

先决条件

• 安装 Visual Studio 2022（社区版或更高版本） 并确保您有最新的更新。
• 安装 .NET Core SDK 6.x 和 7.x。
• 安装 NodeJS（18.x.x）。
• 可选：在 Windows 上安装 wkhtmltopdf 以测试 PDF，使用 choco install wkhtmltopdf。

构建和测试

• 在 templates 目录下构建网站模板
  • 运行 npm install 以恢复 npm 依赖项。
  • 运行 npm run build 以构建模板。
• 运行 dotnet build 以构建项目或使用 Visual Studio 构建 docfx.sln。
• 运行 dotnet test 以测试项目或使用 Visual Studio 测试资源管理器。
  • 运行 git lfs checkout 以检出文件以进行快照测试

分支和发布

main 分支是用于拉取请求和大多数其他开发活动的默认分支。我们有时使用 feature/* 分支进行史诗级功能开发。

发布基于稳定的 main 分支提交，使用 GitHub 发布。鼓励使用 约定提交。

Docfx 并非按照定期节奏发布，新版本会在维护者看到足够多的变更而认为值得发布新版本时推出。有时我们会使用预发布版来测试破坏性更改并从社区获取反馈。

路线图

我们使用 重要里程碑 来沟通即将到来的 Docfx 更改。

• 工作集 是目前正在积极开发的功能。并非此分类中的每个功能都将包含在下一个版本中，但它们反映了维护者未来一段时间的优先级。

• 待办事项 是针对未来某些版本的功能候选集，但不是正在积极开发的功能。

许可证

本项目遵循 MIT 许可协议。

.NET 基金会

本项目由 .NET 基金会 支持。

本项目采用由贡献者公约定义的行为准则，以阐明我们社区中的预期行为。更多信息请参阅 .NET 基金会行为准则。