使用Docfx 创建属于你的Github 文档页面

最近笔者在研究一个东西叫做 docfx 它是一个开源的文档生成工具,可以方便的创建类似下图风格的文档页面,并且把它放在github页面上
使用Docfx 创建属于你的Github 文档页面_第1张图片

开始

首先第一步需要使用 git clone docfx到本地,下载地址

  • 建议放在全英文路径

下载完成之后需要将当前地址添加到环境变量
使用Docfx 创建属于你的Github 文档页面_第2张图片
添加成功之后,打开你所想要创建文档的根目录,然后使用命令行输入

docfx init -q

即会在当前目录下创建一个 docfx_project 文件夹
使用Docfx 创建属于你的Github 文档页面_第3张图片

生成网页

打开 docfx_project 文件夹
在当前目录下使用命令行输入

docfx docfx.json

即会在 _site 文件夹下生成你的网站,使用Edge/IE 浏览器打开index.html
即可看到
使用Docfx 创建属于你的Github 文档页面_第4张图片
点击Articles 按钮 即可看到
使用Docfx 创建属于你的Github 文档页面_第5张图片
其实现在即可把这些页面上传到github上,创建你的个人github页面,即最后一步[发布到github 页面]
但是我们要对它做一些改动再上传

编辑文档

docfx的文档使用markdown格式进行编写
与csdn发博客的写作格式相同
markdown编辑器建议使用VSCode
宇宙第一IDE ,着实好用~
首先打开toc.yml
使用Docfx 创建属于你的Github 文档页面_第6张图片
在这里规定了主页和层级关系 homepage为主页

上面的 - name href 为可选文档
我们把它改动为
使用Docfx 创建属于你的Github 文档页面_第7张图片
再使用docfx docfx.json 进行生成即可看到
使用Docfx 创建属于你的Github 文档页面_第8张图片
现在我们对docfx_project 下的index.md进行编辑
使用Docfx 创建属于你的Github 文档页面_第9张图片
对/articles 文件夹下的 toc.yml 进行编辑 同时复制两次intro.md 为 intro_2.md 和 intro_3.md
使用Docfx 创建属于你的Github 文档页面_第10张图片
对三个intro.md 进行内容编辑 [略,详见我上传的github]
编辑完成后 退回主目录 使用 docfx docfx.json进行生成 得到
使用Docfx 创建属于你的Github 文档页面_第11张图片
使用Docfx 创建属于你的Github 文档页面_第12张图片

发布到github页面

现在我们即可对生成的网页进行上传发布

1.创建一个github 仓库并且clone到本地

2.复制_site文件夹下的内容

将内容复制到github clone后的文件夹
然后上传
使用Docfx 创建属于你的Github 文档页面_第13张图片

3.在github上设置发布

在github 仓库页面 选择Settings -> GitHub Pages 选择 master branch 即可发布
使用Docfx 创建属于你的Github 文档页面_第14张图片
等 ready to be published 状态改变为已发布 即可访问
点击此处 访问我的github发布
使用Docfx 创建属于你的Github 文档页面_第15张图片

注:项目已上传到我的github
docfx官方文档

你可能感兴趣的:(使用Docfx 创建属于你的Github 文档页面)