Simple Usage of DocFX and Tools for Automatic Table of Contents Generation

[Abstract]

This is an automatic generation tool for Docfx documents that I have developed. As long as you write the Markdown document well, this tool can quickly generate configurations for the directory and files, and then you can directly run docfx.

https://github.com/whuanle/CZGL.DocfxBuild.Yml/releases/tag/1.0

1. Install Docfx

Download link: https://github.com/dotnet/docfx/releases

After downloading, unzip the package and remember the directory path.

Search for "Environment Variables" in Windows, and you will see "Edit the System Environment Variables".

Then ⬇️

Create a new directory to store the markdown files. Open the directory, hold down Shift + Right Click to open PowerShell.

Two commands:

docfx init -q

 docfx docfx_project\docfx.json --serve   // use actual path

2. Create Docfx Project

Use this command to initialize a docfx project in the directory.

docfx init -q

The -q parameter means to ignore queries and generate directly. If you need to customize the configuration, you can remove the -q parameter.

Open the docfx_project folder. The directory structure is as follows:

docfx_project 
.
├── api
│   ├── index.md
│   └── toc.yml
├── apidoc
├── articles
│   ├── intro.md
│   └── toc.yml
├── docfx.json
├── images
├── index.md
├── src
└── toc.yml

Create API Documentation for Code

The src directory is used to store the projects for which you need to generate documentation. Just put the entire project (solution) into it.

Generate documentation:

 docfx docfx_project\docfx.json --serve

Preview:

For projects, you can quickly generate object documentation and code documentation.

Here is a detailed method for generating REST API documentation:

https://dotnet.github.io/docfx/tutorial/intro_rest_api_documentation.html

3. Text Documentation

The text documentation is written using Markdown files and stored in the articles directory.

    ├── intro.md
    └── toc.yml

These two files are the defaults. The toc.yml file generates the default directory structure, while intro.md is the default view when opening the documentation, which can be understood as the cover content, for example, like the Readme.md of a GitHub repository.

To generate a multi-level directory, it is recommended that each directory should have a toc.yml file.

The simplest syntax:

- name: xxx
  href: xxxx

Used to generate detailed directory structures and documentation files. The href can be a directory, .md file, or .yml file.

If href refers to a .yml, a directory structure will be generated.

Using:

  items:
    - name: Topic2_1
      href: Topic2_1.md
      ...
      ...

You can also generate a hierarchy.

  homepage: index.md

This is used to generate the homepage file, and it is not very useful for subdirectories.

Files and directories used for testing:

.
└── 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

After using CZGL.DocfxBuild.Yml to automatically generate:

.
└── 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

Generate documentation:

 docfx docfx_project\docfx.json --serve

Using CZGL.DocfxBuild.Yml can help you quickly generate documentation directories.

The toc.yml file in the root directory:

- 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

The name is the directory name.

The href points to the toc.yml file in the subdirectory.

Structure of directory 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:\Temporary Cache\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

Each directory has a .yml file.

If there are subdirectories in this directory, link to the .yml file of the subdirectory. If it is a subfile, link to the .md file.

This can quickly generate the documentation directory.

Of course, you can also try items.

The official detailed documentation can be found at:

https://dotnet.github.io/docfx/tutorial/intro_toc.html

In my spare time, I wrote a feature to automatically generate the docfx directory. Download link:

https://github.com/whuanle/CZGL.DocfxBuild.Yml/releases/tag/1.0

Preview of the result: https://doc.whuanle.cn

I have things to do tonight, finished today's blog post.