[摘要]

这是我编写的一个 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

效果预览 https://doc.whuanle.cn

晚上有事,今天的博客水完了。

docfx 简单使用方法、自动生成目录的工具的更多相关文章

  1. Word 2010文档自动生成目录和某页插入页码

    一.Word 2010文档自动生成目录 关于Word文档自动生成目录一直是我身边同学们最为难的地方,尤其是毕业论文,经常因为目录问题,被要求修改,而且每次修改完正文后,目录的内容和页码可能都会发生变化 ...

  2. 第 10 篇:小细节 Markdown 文章自动生成目录,提升阅读体验

    目录 在文中插入目录 在页面的任何地方插入目录 处理空目录 美化标题的锚点 URL 作者:HelloGitHub-追梦人物 文中涉及的示例代码,已同步更新到 HelloGitHub-Team 仓库 上 ...

  3. Word自动生成目录

    博主最近在写报告的时候要在Word里面做个目录,再做个页码,然后上网搜了一些方法,非常零散,我弄了好久才弄好.在这里我把整套方法分享一下. 声明:内容完全独创! 工具:Word 2016. 效果:如下 ...

  4. Thinkphp5.0实战开发二------自动生成目录结构

    序言 ThinkPHP5.0 具备自动创建功能,可以用来自动生成需要的模块及目录结构和文件等,自动生成主要调用\think\Build 类库.ThinkPHP5.0中模块文件夹在application ...

  5. tp5自动生成目录

    1.// 定义应用目录 define('APP_PATH', __DIR__ . '/../application/'); // 加载框架引导文件 require __DIR__ . '/../thi ...

  6. Idea_学习_09_Idea 方法自动生成参数默认名

    一.方法 1.快捷键 生成方法后,还空着参数,可以使用 ctrl + alt + 空格 ,列出参数,然后选择参数即可. 2.使用插件 二.参考资料 1.Intellij Idea 方法自动生成参数默认 ...

  7. csdn自动生成目录索引、插入代码片快捷键

    文章目录 自动生成目录索引 插入代码片 自动生成目录索引 文章开头加入 @[TOC](目录描述) 目录描述可不写 插入代码片 cmd/ctrl + shift + k

  8. Markdown自动生成目录

    Markdown自动生成目录 使用npm语法生成 1.安装npm 2.安装doctoc插件 3.执行生成 参考 Markdown自动生成目录 使用npm语法生成 1.安装npm 我的系统是deepin ...

  9. 去除office自动生成目录后生成的小框框(内容控件,目录控件)

    如何自动生成目录在这里就不进行阐述了,想必能看到这这里的人已经完成了目录的自动生成,那我就来直接演示如何去除自动生成目录后烦人的目录内容控件吧 直接上图片

随机推荐

  1. Java生鲜电商平台-IntelliJ IDEA 最新注册码,亲测可用

    2019年IntelliJ IDEA 最新注册码(截止到2020年3月11日) 操作步骤: 第一步:  修改 hosts 文件 ~~~ 在hosts文件中,添加以下映射关系: 0.0.0.0 acco ...

  2. DDL、DML、TCL

    一.DDL 1.创建表(CREATE) (1)数据库对大小写不敏感,只对字符串大小写敏感. (2)使用create关键字创建表.(-- 表示注释). 格式: CREATE TABLE 表名( 字段名1 ...

  3. 微信语音短消息amr文件转WAV

    - amr说明 - 转WAV程序 我对SILK编码库稍作修改,编译了一个Windows下可直接将SILK V3编码转换为WAV格式,并支持原生的微信语音短消息amr文件的版本,提供给大家使用,压缩包( ...

  4. 【转载】每个 Android 开发者必须知道的消息机制问题总结

    Android的消息机制几乎是面试必问的话题,当然也并不是因为面试,而去学习,更重要的是它在Android的开发中是必不可少的,占着举足轻重的地位,所以弄懂它是很有必要的.下面就来说说最基本的东西. ...

  5. 【Android】基于A星寻路算法的简单迷宫应用

    简介 基于[漫画算法-小灰的算法之旅]上的A星寻路算法,开发的一个Demo.目前实现后退.重新载入.路径提示.地图刷新等功能.没有做太多的性能优化,算是深化对A星寻路算法的理解. 界面预览: 初始化: ...

  6. Python的包package的导入与被导入(包的类和方法的导入,__init__()怎么写)

    包package的导入与被导入: 参考一下: https://blog.csdn.net/guowujun321/article/details/80764468 1.文件目录: | |--  A/ ...

  7. Linux中raid磁盘阵列

    一.磁盘阵列(Redundant Arrays of Independent Disks,RAID) 有“独立磁盘构成的具有冗余能力的阵列”之意. 磁盘阵列是由很多价格较便宜的磁盘,以硬件(RAID卡 ...

  8. PHP配置篇(一)--php开启redis扩展

    因为最近要用到Redis,下面记录下如何给PHP开启redis的扩展. 一.安装redis 1.安装redis:https://github.com/MSOpenTech/redis/releases ...

  9. 如何在VIM中保存编辑的只读文件

    我们经常碰到这样的情景:在VIM中编辑了一个系统配置文件,当需要保存时才发现当前的用户对该文件没有写入的权限, 这时候怎么办呢? 当需要保存时,输入以下的命令: :w !sudo tee %

  10. arXiv网站

    arXiv 原先是由物理学家保罗·金斯巴格在1991年建立的网站, 我们会将预稿上传到arvix作为预收录,因此这就是个可以证明论文原创性(上传时间戳)的文档收录网站.