演練1: 為文檔網(wǎng)站添加簡單文檔
通過完成本演練教程，您將熟悉 docfx的工作流程以及在 docfx 中組織文檔的一般性原則吱七。 您將通過生成一個可以發(fā)布到任何主機(jī)服務(wù)的靜態(tài)網(wǎng)站來完成本演練刚盈。 在這里下載本演練中將使用到的文件 羡洛。
第1步. 安裝DocFX
從http://dotnet.github.io/docfx/ 下載 docfx. docfx 入門 一文描述了如何安裝 docfx. 演練教程使用方式1: 直接使用 docfx.exe 。
- 下載 docfx.zip 文件并解壓到
D:\docfx\ - 添加
D:\docfx\到環(huán)境變量PATH以便命令行可以直接在任何路徑運(yùn)行docfx. (在window下面使用命令,set PATH=%PATH%;D:\docfx\設(shè)置）
第2步. 初始化 DocFX 項(xiàng)目
- 創(chuàng)建一個新目錄
D:\docfx_walkthrough - 在
D:\docfx_walkthrough目錄下面啟動命令行控制臺藕漱。 - 運(yùn)行
docfx init -q命令欲侮。 這個命令會生成一個docfx_project目錄，里面包含默認(rèn)的docfx.json文件.docfx.json文件是docfx用來生成文檔的配置文件谴分。-q選項(xiàng)代表靜默狀態(tài)下生成項(xiàng)目, 您還可以嘗試使用 'docfx init' 初始化項(xiàng)目要锈麸，并按照提示說明進(jìn)行設(shè)置。
第3步. 生成網(wǎng)站
運(yùn)行命令 docfx docfx_project/docfx.json牺蹄。注意項(xiàng)目下面會生成一個新的 _site 目錄忘伞。這是生成靜態(tài)網(wǎng)站的地方。
第4步. 預(yù)覽網(wǎng)站
生成的靜態(tài)網(wǎng)站不需要做任何修改就可以發(fā)布到 GitHub pages, Azure 網(wǎng)站,或者你的托管服務(wù)。你也可以運(yùn)行命令 docfx serve docfx_project/_site 在本地預(yù)覽網(wǎng)站氓奈。
如果 8080 端口沒有被占用, docfx 將在 http://localhost:8080 托管 _site 站點(diǎn). 如果 8080 端口被占用了, 你需要使用 docfx serve _site -p <port> 修改 docfx 使用的端口翘魄。
祝賀你! 運(yùn)行成功以后你可以看到下面網(wǎng)站了:
第5步. 添加一系列文章到網(wǎng)站
放置更多
.md文件到articles目錄, 例如.details1.md,details2.md,details3.md. 如果引用到了其他的資源，把這些資源放到images目錄舀奶。-
為了能夠組織這些文件暑竟，我們要把這些文件添加到
articles子目錄下面的toc.yml文件中.toc.yml的內(nèi)容如下所示:- name: Introduction href: intro.md - name: Details 1 href: details1.md - name: Details 2 href: details2.md - name: Details 3 href: details3.md現(xiàn)在的文件目錄結(jié)構(gòu)如下：
|- index.md |- toc.yml |- articles | |- intro.md | |- details1.md | |- details2.md | |- details3.md | |- toc.yml |- images |- details1_image.png -
再次重復(fù)步驟 第3步 和 第4步*, 生成的網(wǎng)站如下：
.Step7
注意更多的項(xiàng)目被添加到了 Articles 導(dǎo)航頁。 側(cè)邊欄中的標(biāo)題正是我們在 articles 文件夾``toc.yml`文件的里面設(shè)置的標(biāo)題育勺。
結(jié)論
通過演練教程, 我們使用一系列 .md 文件生成了一個靜態(tài)網(wǎng)站. 我們稱這些 .md 文件為 Conceptual Documentation（概念文檔）. 在演練教程2中, 我們將學(xué)習(xí)如何添加 API 文檔 到我們的網(wǎng)站. API 文檔 是直接從 .NET 源代碼中抽取出來的但荤。 在高級演練教程中, 我們將學(xué)習(xí)到 docfx中的高級概念，例如文章之間的引用涧至，其他文檔的外部引用等腹躁。我們還將學(xué)習(xí)如何定制我們的網(wǎng)站，從主題到布局到元數(shù)據(jù)提取南蓬。
