【DocFX文档翻译】演练1: 为文档网站添加简单文档

演练1: 为文档网站添加简单文档

通过完成本演练教程，您将熟悉 docfx的工作流程以及在 docfx 中组织文档的一般性原则。 您将通过生成一个可以发布到任何主机服务的静态网站来完成本演练。 在这里下载本演练中将使用到的文件 。

第1步. 安装DocFX

从http://dotnet.github.io/docfx/ 下载 docfx. docfx 入门 一文描述了如何安装 docfx. 演练教程使用方式1: 直接使用 docfx.exe 。

1. 下载 docfx.zip 文件并解压到 D:\docfx\
2. 添加D:\docfx\ 到环境变量 PATH 以便命令行可以直接在任何路径运行 docfx. (在window下面使用命令, set PATH=%PATH%;D:\docfx\ 设置）

第2步. 初始化 DocFX 项目

1. 创建一个新目录 D:\docfx_walkthrough
2. 在 D:\docfx_walkthrough 目录下面启动命令行控制台。
3. 运行 docfx init -q 命令。 这个命令会生成一个 docfx_project 目录，里面包含默认的 docfx.json 文件. docfx.json 文件是 docfx 用来生成文档的配置文件。 -q 选项代表静默状态下生成项目, 您还可以尝试使用 'docfx init' 初始化项目要，并按照提示说明进行设置。

第3步. 生成网站

运行命令 docfx docfx_project/docfx.json。注意项目下面会生成一个新的 _site 目录。这是生成静态网站的地方。

第4步. 预览网站

生成的静态网站不需要做任何修改就可以发布到 GitHub pages, Azure 网站,或者你的托管服务。你也可以运行命令 docfx serve docfx_project/_site 在本地预览网站。

如果 8080 端口没有被占用, docfx 将在 http://localhost:8080 托管 _site 站点. 如果 8080 端口被占用了, 你需要使用 docfx serve _site -p 修改 docfx 使用的端口。

祝贺你! 运行成功以后你可以看到下面网站了:

Homepage

---

第5步. 添加一系列文章到网站

1. 放置更多 .md 文件到 articles 目录, 例如. details1.md, details2.md, details3.md. 如果引用到了其他的资源，把这些资源放到 images 目录。

2. 为了能够组织这些文件，我们要把这些文件添加到 articles 子目录下面的 toc.yml 文件中. toc.yml 的内容如下所示:

   - name: Introduction
     href: intro.md
   - name: Details 1
     href: details1.md
   - name: Details 2
     href: details2.md
   - name: Details 3
     href: details3.md
   

   现在的文件目录结构如下：

   |- index.md
   |- toc.yml
   |- articles
   |    |- intro.md
   |    |- details1.md
   |    |- details2.md
   |    |- details3.md
   |    |- toc.yml
   |- images
       |- details1_image.png
   

3. 再次重复步骤 第3步 和 第4步*, 生成的网站如下：
   

   

   Step7
   .

注意更多的项目被添加到了 Articles 导航页。 侧边栏中的标题正是我们在 articles 文件夹``toc.yml`文件的里面设置的标题。

结论

通过演练教程, 我们使用一系列 .md 文件生成了一个静态网站. 我们称这些 .md 文件为 Conceptual Documentation（概念文档）. 在演练教程2中, 我们将学习如何添加 API 文档 到我们的网站. API 文档 是直接从 .NET 源代码中抽取出来的。 在高级演练教程中, 我们将学习到 docfx中的高级概念，例如文章之间的引用，其他文档的外部引用等。我们还将学习如何定制我们的网站，从主题到布局到元数据提取。

更多相关文档

• 演练2: 为文档网站添加API文档

• 高级演练: 自定义文档网站