docfx 简单使用方法、自动生成目录的工具
[摘要]
这是我编写的一个 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
晚上有事,今天的博客水完了。
docfx 简单使用方法、自动生成目录的工具的更多相关文章
- Word 2010文档自动生成目录和某页插入页码
一.Word 2010文档自动生成目录 关于Word文档自动生成目录一直是我身边同学们最为难的地方,尤其是毕业论文,经常因为目录问题,被要求修改,而且每次修改完正文后,目录的内容和页码可能都会发生变化 ...
- 第 10 篇:小细节 Markdown 文章自动生成目录,提升阅读体验
目录 在文中插入目录 在页面的任何地方插入目录 处理空目录 美化标题的锚点 URL 作者:HelloGitHub-追梦人物 文中涉及的示例代码,已同步更新到 HelloGitHub-Team 仓库 上 ...
- Word自动生成目录
博主最近在写报告的时候要在Word里面做个目录,再做个页码,然后上网搜了一些方法,非常零散,我弄了好久才弄好.在这里我把整套方法分享一下. 声明:内容完全独创! 工具:Word 2016. 效果:如下 ...
- Thinkphp5.0实战开发二------自动生成目录结构
序言 ThinkPHP5.0 具备自动创建功能,可以用来自动生成需要的模块及目录结构和文件等,自动生成主要调用\think\Build 类库.ThinkPHP5.0中模块文件夹在application ...
- tp5自动生成目录
1.// 定义应用目录 define('APP_PATH', __DIR__ . '/../application/'); // 加载框架引导文件 require __DIR__ . '/../thi ...
- Idea_学习_09_Idea 方法自动生成参数默认名
一.方法 1.快捷键 生成方法后,还空着参数,可以使用 ctrl + alt + 空格 ,列出参数,然后选择参数即可. 2.使用插件 二.参考资料 1.Intellij Idea 方法自动生成参数默认 ...
- csdn自动生成目录索引、插入代码片快捷键
文章目录 自动生成目录索引 插入代码片 自动生成目录索引 文章开头加入 @[TOC](目录描述) 目录描述可不写 插入代码片 cmd/ctrl + shift + k
- Markdown自动生成目录
Markdown自动生成目录 使用npm语法生成 1.安装npm 2.安装doctoc插件 3.执行生成 参考 Markdown自动生成目录 使用npm语法生成 1.安装npm 我的系统是deepin ...
- 去除office自动生成目录后生成的小框框(内容控件,目录控件)
如何自动生成目录在这里就不进行阐述了,想必能看到这这里的人已经完成了目录的自动生成,那我就来直接演示如何去除自动生成目录后烦人的目录内容控件吧 直接上图片
随机推荐
- Java生鲜电商平台-IntelliJ IDEA 最新注册码,亲测可用
2019年IntelliJ IDEA 最新注册码(截止到2020年3月11日) 操作步骤: 第一步: 修改 hosts 文件 ~~~ 在hosts文件中,添加以下映射关系: 0.0.0.0 acco ...
- DDL、DML、TCL
一.DDL 1.创建表(CREATE) (1)数据库对大小写不敏感,只对字符串大小写敏感. (2)使用create关键字创建表.(-- 表示注释). 格式: CREATE TABLE 表名( 字段名1 ...
- 微信语音短消息amr文件转WAV
- amr说明 - 转WAV程序 我对SILK编码库稍作修改,编译了一个Windows下可直接将SILK V3编码转换为WAV格式,并支持原生的微信语音短消息amr文件的版本,提供给大家使用,压缩包( ...
- 【转载】每个 Android 开发者必须知道的消息机制问题总结
Android的消息机制几乎是面试必问的话题,当然也并不是因为面试,而去学习,更重要的是它在Android的开发中是必不可少的,占着举足轻重的地位,所以弄懂它是很有必要的.下面就来说说最基本的东西. ...
- 【Android】基于A星寻路算法的简单迷宫应用
简介 基于[漫画算法-小灰的算法之旅]上的A星寻路算法,开发的一个Demo.目前实现后退.重新载入.路径提示.地图刷新等功能.没有做太多的性能优化,算是深化对A星寻路算法的理解. 界面预览: 初始化: ...
- Python的包package的导入与被导入(包的类和方法的导入,__init__()怎么写)
包package的导入与被导入: 参考一下: https://blog.csdn.net/guowujun321/article/details/80764468 1.文件目录: | |-- A/ ...
- Linux中raid磁盘阵列
一.磁盘阵列(Redundant Arrays of Independent Disks,RAID) 有“独立磁盘构成的具有冗余能力的阵列”之意. 磁盘阵列是由很多价格较便宜的磁盘,以硬件(RAID卡 ...
- PHP配置篇(一)--php开启redis扩展
因为最近要用到Redis,下面记录下如何给PHP开启redis的扩展. 一.安装redis 1.安装redis:https://github.com/MSOpenTech/redis/releases ...
- 如何在VIM中保存编辑的只读文件
我们经常碰到这样的情景:在VIM中编辑了一个系统配置文件,当需要保存时才发现当前的用户对该文件没有写入的权限, 这时候怎么办呢? 当需要保存时,输入以下的命令: :w !sudo tee %
- arXiv网站
arXiv 原先是由物理学家保罗·金斯巴格在1991年建立的网站, 我们会将预稿上传到arvix作为预收录,因此这就是个可以证明论文原创性(上传时间戳)的文档收录网站.