[摘要]
這是我編寫的一個 Docfx 文檔自動生成工具，只要寫好 Markdown 文檔，使用此工具可為目錄、文件快速生成配置，然后直接使用 docfx 運行即可。
https://github.com/whuanle/CZGL.DocfxBuild.Yml/releases/tag/1.0
一，安裝Docfx
下載地址 https://github.com/dotnet/docfx/releases
下載后解壓壓縮包，記錄好目錄路徑。
Win 搜索 “環境變量”，會出現 “編輯系統環境變量”。
然后 ↓
新建一個目錄，用來存放 markdown 文件。打開目錄，按住 Shift + 鼠標右鍵 ，打開 Powershell 。
兩個命令
docfx init -q
docfx docfx_project\docfx.json --serve // 以實際路徑為准
二， 創建 Docfx 項目
使用此命令在目錄下初始一個 docfx 項目
docfx init -q
-q 這個參數表示忽略詢問，直接生成。如果需要自定義配置，可取消 -q 這個參數。
打開 docfx_project 文件夾，目錄結構如下：
docfx_project
.
├── api
│ ├── index.md
│ └── toc.yml
├── apidoc
├── articles
│ ├── intro.md
│ └── toc.yml
├── docfx.json
├── images
├── index.md
├── src
└── toc.yml
為代碼創建 API 文檔
src 目錄用來存放你需要生成文檔的項目，直接把整個項目(解決方案)放進去即可。
生成文檔
docfx docfx_project\docfx.json --serve
預覽
對於 項目，可以快速生成對象文檔、代碼文檔。
這里有關於 REST API 生成文檔的詳細方法
https://dotnet.github.io/docfx/tutorial/intro_rest_api_documentation.html
三， 文字文檔
文字文檔使用 markdown 文件編寫，存放位置 articles 。
├── intro.md
└── toc.yml
這兩個文件是默認的， toc.yml 由於默認生成目錄結構，intro.md 是打開文檔是默認看到的，可以理解為封面內容。例如 Github 倉庫的 Readme.md 。
為了生成多級目錄，建議每個目錄有應該有一個 toc.yml 文件。
最簡單的語法
- name: xxx href: xxxx
用於生成目錄結構詳細、文檔文件，href 可以是 目錄、 .md 文件、.yml 文件。
但 href 為 .yml 是，會生成目錄結構。
使用
items:
- name: Topic2_1
href: Topic2_1.md
...
...
也可以生成層次結構。
homepage: index.md
用來生成首頁文件，對於子目錄，用處不大。
用來測試的文件和目錄
.
└── articles
├── a
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ └── d.md
├── b
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ └── d.md
├── c
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ └── d.md
├── d
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ └── d.md
├── intro.md
└── toc.yml
使用 CZGL.DocfxBuild.Yml 自動生成后
.
└── articles
├── a
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ ├── d.md
│ └── toc.yml
├── b
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ ├── d.md
│ └── toc.yml
├── c
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ ├── d.md
│ └── toc.yml
├── d
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ ├── d.md
│ └── toc.yml
├── intro.md
└── toc.yml
生成文檔：
docfx docfx_project\docfx.json --serve
使用 CZGL.DocfxBuild.Yml 可以幫助你快速生成文檔目錄。
根目錄的 toc.yml 文件：
- name: a
href: a/toc.yml
- name: b
href: b/toc.yml
- name: c
href: c/toc.yml
- name: d
href: d/toc.yml
- name: intro
href: intro.md
homepage: intro.md
name 為目錄名稱。
href 指向子目錄下的 toc.yml 文件
目錄 a 的結構
.
├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ ├── d.md
│ └── toc.yml
├── a.md
├── b
│ ├── a.md
│ ├── b.md
│ ├── c.md
│ ├── d.md
│ └── toc.yml
├── b.md
├── c
│ ├── a.md
│ ├── b.md
│ ├── c.md
│ ├── d.md
│ └── toc.yml
├── c.md
├── d
│ ├── a.md
│ ├── b.md
│ ├── c.md
│ ├── d.md
│ └── toc.yml
├── d.md
└── toc.yml
### G:\臨時緩存\docfx\docfx_project\articles\a
- name: a
href: a/toc.yml
- name: b
href: b/toc.yml
- name: c
href: c/toc.yml
- name: d
href: d/toc.yml
- name: a
href: a.md
- name: b
href: b.md
- name: c
href: c.md
- name: d
href: d.md
homepage: a.md
每個目錄一個 .yml 文件
如果這個目錄下有目錄，則連接子目錄的 .yml 文件，如果是子文件，則鏈接這個 .md 文件。
這樣能夠快速生成文檔目錄。
當然也可以嘗試 items
官方詳細文檔地址
https://dotnet.github.io/docfx/tutorial/intro_toc.html
利用空閑時間寫了自動生成 docfx 目錄的功能，下載地址
https://github.com/whuanle/CZGL.DocfxBuild.Yml/releases/tag/1.0
晚上有事，今天的博客水完了。