From 63a16c873195c2559fe18bf2bef5d4a9d95c53ba Mon Sep 17 00:00:00 2001
From: filzrev <103790468+filzrev@users.noreply.github.com>
Date: Thu, 22 Feb 2024 21:37:49 +0900
Subject: [PATCH] docs: Split docfx CLI reference docs based on commands
 (#9708)

docs: split docfx CLI reference docs based on commands
---
 docs/docs/toc.yml                             |   3 +-
 docs/reference/docfx-cli-reference.md         | 148 -----------------
 .../docfx-cli-reference/docfx-build.md        | 142 +++++++++++++++++
 .../docfx-cli-reference/docfx-download.md     |  43 +++++
 .../docfx-cli-reference/docfx-init.md         |  35 ++++
 .../docfx-cli-reference/docfx-merge.md        |  58 +++++++
 .../docfx-cli-reference/docfx-metadata.md     | 105 ++++++++++++
 .../docfx-cli-reference/docfx-pdf.md          |  54 +++++++
 .../docfx-cli-reference/docfx-serve.md        |  56 +++++++
 .../docfx-cli-reference/docfx-template.md     |  56 +++++++
 docs/reference/docfx-cli-reference/docfx.md   | 150 ++++++++++++++++++
 .../reference/docfx-cli-reference/overview.md |  42 +++++
 docs/reference/docfx-cli-reference/toc.yml    |  10 ++
 src/docfx/Models/BuildCommandOptions.cs       |   2 +-
 14 files changed, 754 insertions(+), 150 deletions(-)
 delete mode 100644 docs/reference/docfx-cli-reference.md
 create mode 100644 docs/reference/docfx-cli-reference/docfx-build.md
 create mode 100644 docs/reference/docfx-cli-reference/docfx-download.md
 create mode 100644 docs/reference/docfx-cli-reference/docfx-init.md
 create mode 100644 docs/reference/docfx-cli-reference/docfx-merge.md
 create mode 100644 docs/reference/docfx-cli-reference/docfx-metadata.md
 create mode 100644 docs/reference/docfx-cli-reference/docfx-pdf.md
 create mode 100644 docs/reference/docfx-cli-reference/docfx-serve.md
 create mode 100644 docs/reference/docfx-cli-reference/docfx-template.md
 create mode 100644 docs/reference/docfx-cli-reference/docfx.md
 create mode 100644 docs/reference/docfx-cli-reference/overview.md
 create mode 100644 docs/reference/docfx-cli-reference/toc.yml

diff --git a/docs/docs/toc.yml b/docs/docs/toc.yml
index 3f1c7a4b9c6..711c69513ac 100644
--- a/docs/docs/toc.yml
+++ b/docs/docs/toc.yml
@@ -17,7 +17,8 @@
 
 - name: Reference
 - href: ../reference/docfx-json-reference.md
-- href: ../reference/docfx-cli-reference.md
+- name: Commandline Reference
+  href: ../reference/docfx-cli-reference/toc.yml
 - href: ../reference/docfx-environment-variables-reference.md
 - href: api-page.yml
 
diff --git a/docs/reference/docfx-cli-reference.md b/docs/reference/docfx-cli-reference.md
deleted file mode 100644
index efe6bdf5c54..00000000000
--- a/docs/reference/docfx-cli-reference.md
+++ /dev/null
@@ -1,148 +0,0 @@
-# Commandline Reference
-
-## Introduction
-
-`docfx` is used to generate documentation for programs. It has the ability to:
-
-1. Extract language metadata for programing languages as defined in [Metadata Format Specification](../spec/metadata_format_spec.md). Currently `C#` and `VB` are supported (although see note below regarding `VB` support). The language metadata is saved in `YAML` format as described in [YAML 1.2][1].
-2. Look for available conceptual files as provided and link them with existing programs using the syntax described in [Metadata Yaml Format](../spec/metadata_format_spec.md). Supported conceptual files are *plain text* files, *html* files, and *markdown* files.
-3. Generate documentation to
-   a. Visualize language metadata, with extra **content** provided by linked conceptual files using the syntax described in [Metadata Yaml Format](../spec/metadata_format_spec.md).
-   b. Organize and render available conceptual files which can be easily cross-referenced with language metadata pages. Docfx supports **Docfx Flavored Markdown(DFM)** for writing conceptual files. **DFM** supports all *Github Flavored Markdown(GFM)* syntax with 2 exceptions when resolving [list](../docs/markdown.md#differences-introduced-by-dfm-syntax). It also adds several new features including *file inclusion*, *cross reference*, and *yaml header*. For detailed description about DFM, please refer to [DFM](../spec/docfx_flavored_markdown.md).
-
-> [!NOTE]
-> Although Docfx is able to process `VB` projects and individual `VB` source code files and extract metadata from them, the documentation output from Docfx is always in `C#` format, i.e. types and member signatures, etc., are shown in `C#` format and not `VB` format.
-
-Currently generating documentation to a *client only* **website** is supported. The generated **website** can be easily published to whatever platform such as *Github Pages* and *Azure Website* with little extra effort.
-
-Generating offline documentation such as **PDF** is also supported.
-
-## Syntax
-
-```
-docfx <command> [<args>]
-```
-
-Run `docfx --version` to get the version of the docfx.
-
-Run `docfx --help` or `docfx -h` to get a list of all available commands and options. Run `docfx <command> --help` or `docfx <command> -h` to get help on a specific command.
-
-## Commands
-
-### Init command `docfx init`
-`docfx init` helps generate an `docfx.json` file.
-
-### Extract language metadata command `docfx metadata`
-
-**Syntax**
-```
-docfx metadata [<projects>] [--property <n1>=<v1>;<n2>=<v2>]
-```
-
-**Layout**
-```
-|-- <metadata folder>
-      |-- api
-      |     |-- <namespace>.yml
-      |     |-- <class>.yml
-      |-- toc.yml
-      |-- index.yml
-```
-
-
-#### Optional arguments for the `docfx metadata` command
-
-* **`<projects>` argument (optional)**
-
-    `<projects>` specifies the projects to have metadata extracted. There are several approaches to extract language metadata.
-
-    1. From a supported file or file list
-      Supported file extensions include `.csproj`, `.vbproj`, `.sln`, `.slnf`, `exe`, `dll` assembly file, `.cs` source file and `.vb` source file.
-
-      Multiple files are separated by whitespace, e.g. `docfx metadata Class1.cs a.csproj`
-
-      > [!Note]
-      > Glob pattern is **NOT** supported in command line options.
-
-    2. From *docfx.json* file, as described in **Section3**.
-
-    3. If the argument is not specified, `docfx` will try reading `docfx.json` under current directory.
-
-    The default output folder is `_site/` folder if it is not specified in `docfx.json` under current directory.
-
-* **`--shouldSkipMarkup` command option**
-
-    If adding option `--shouldSkipMarkup` in metadata command, it means that DocFX would not render triple-slash-comments in source code as markdown.
-
-    e.g. `docfx metadata --shouldSkipMarkup`
-
-* **`--property <n1>=<v1>;<n2>=<v2>` command option**
-
-An optional set of MSBuild properties used when interpreting project files. These are the same properties that are passed to msbuild via the /property:<n1>=<v1>;<n2>=<v2> command line argument.
-For example: `docfx metadata --property TargetFramework=net48` generates metadata files with .NET framework 4.8. This command can be used when the project supports multiple `TargetFrameworks`.
-
-### Generate documentation command `docfx build`
-
-**Syntax**
-```
-docfx build [-o:<output_path>] [-t:<template folder>]
-```
-`docfx build` generates documentation for current folder.
-
-If `toc.yml` or `toc.md` is found in current folder, it will be rendered as the top level TABLE-OF-CONTENT. As in website, it will be rendered as the top navigation bar. Path in `toc.yml` or `toc.md` are relative to the TOC file.
-
-> [!Note]
-> `homepage` is not supported in `toc.md`.
-> If `href` is referencing a **folder**, it must end with `/`.
-
-**toc.yml syntax**
-
-`toc.yml` is an array of items. Each item can have following properties:
-
-Property | Description
----------|-----------------------------
-name     | **Required**. The title of the navigation page.
-href     | **Required**. A folder or a file *UNDER* the current folder. A folder must end with `/`. If referencing a folder, a TOC.md file inside the folder will be rendered as a second level TABLE-OF-CONTENT. As in website, it will be rendered as a sidebar.
-homepage | The default content shown when no article is selected.
-
-  **TOC.yml Sample**
-  ```yaml
-  - name: Home
-    href: articles/Home.md
-  - name: Roslyn Wiki
-    href: roslyn_wiki/
-  - name: Roslyn API
-    href: api_roslyn/
-    homepage: homepages/roslyn_language_features.md
-  ```
-  **TOC.md Sample**
-  ```markdown
-  ## [Home](articles/Home.md)
-  ## [Roslyn Wiki](roslyn_wiki/)
-  ## [Roslyn API](api_roslyn/)
-  ```
-
-#### Optional arguments for the `docfx build` command
-
-* **`<output_path>` argument (optional)**
-
-    The default output folder is `_site/` folder
-
-* **`<template folder>` argument (optional)**
-
-  If specified, use the template from template folder
-
-**Template Folder Structure**
-```
-|-- <template folder>
-      |-- index.html
-      |-- styles
-      |     |-- docascode.css
-      |     |-- docascode.js
-      |-- template
-      |     |-- toc.html
-      |     |-- navbar.html
-      |     |-- yamlContent.html
-      |-- favicon.ico
-      |-- logo.ico
-```
diff --git a/docs/reference/docfx-cli-reference/docfx-build.md b/docs/reference/docfx-cli-reference/docfx-build.md
new file mode 100644
index 00000000000..17ec92b3a87
--- /dev/null
+++ b/docs/reference/docfx-cli-reference/docfx-build.md
@@ -0,0 +1,142 @@
+# docfx build
+
+## Name
+
+`docfx build [config] [OPTIONS]` - Generate static site contents from input files.
+
+## Usage
+
+```pwsh
+docfx build [config] [OPTIONS]
+```
+
+Run `docfx build --help` or `docfx -h` to get a list of all available options.
+
+## Arguments
+
+- `[config]` <span class="badge text-bg-primary">optional</span>
+
+  Specify the path to the docfx configuration file.
+  By default, the `docfx.json' file path is used.
+
+## Options
+
+- **-h|--help**
+
+  Prints help information.
+
+- **-l|--log**
+
+  Save log as structured JSON to the specified file.
+
+- **--logLevel**
+
+  Set log level to error, warning, info, verbose or diagnostic.
+
+- **--verbose**
+
+  Set log level to verbose.
+
+- **--warningsAsErrors**
+
+  Treats warnings as errors.
+
+- **-o|--output**
+
+  Specify the output base directory.
+
+- **-m|--metadata**
+
+  Specify a list of global metadata in key value pairs (e.g. --metadata _appTitle="My App" --metadata _disableContribution)
+
+- **-x|--xref**
+
+  Specify the urls of xrefmap used by content files.
+
+- **-t|--template**
+
+  Specify the template name to apply to. If not specified, output YAML file will not be transformed.
+
+- **--theme**
+
+  Specify which theme to use. By default 'default' theme is offered.
+
+- **-s|--serve**
+
+  Host the generated documentation to a website.
+
+- **-n|--hostname**
+
+  Specify the hostname of the hosted website (e.g., 'localhost' or '*')
+
+- **-p|--port**
+
+  Specify the port of the hosted website.
+
+- **--open-browser**
+
+  Open a web browser when the hosted website starts.
+
+- **--open-file<RELATIVE_PATH>**
+
+  Open a file in a web browser when the hosted website starts.
+
+- **--debug**
+
+  Run in debug mode. With debug mode, raw model and view model will be exported automatically when it encounters error when applying templates. If not specified, it is false.
+
+- **--debugOutput**
+
+  The output folder for files generated for debugging purpose when in debug mode. If not specified, it is ${TempPath}/docfx.
+
+- **--exportRawModel**
+
+  If set to true, data model to run template script will be extracted in .raw.model.json extension.
+
+- **--rawModelOutputFolder**
+
+  Specify the output folder for the raw model. If not set, the raw model will be generated to the same folder as the output documentation.
+
+- **--viewModelOutputFolder**
+
+  Specify the output folder for the view model. If not set, the view model will be generated to the same folder as the output documentation.
+
+- **--exportViewModel**
+
+  If set to true, data model to apply template will be extracted in .view.model.json extension.
+
+- **--dryRun**
+
+  If set to true, template will not be actually applied to the documents.
+  This option is always used with --exportRawModel or --exportViewModel is set so that only raw model files or view model files are generated..
+
+- **--maxParallelism**
+
+  Set the max parallelism, 0 is auto.
+
+- **--markdownEngineProperties**
+
+  Set the parameters for markdown engine, value should be a JSON string.
+
+- **--postProcessors**
+
+  Set the order of post processors in plugins.
+
+- **--disableGitFeatures**
+
+  Disable fetching Git related information for articles. By default it is enabled and may have side effect on performance when the repo is large.
+
+## Examples
+
+- Build static site contents with default `docfx.json` config file.
+
+```pwsh
+docfx build
+```
+
+- Build static site contents with default `docfx.json` config file.
+  Then serve generated site, and open site with default browser.
+
+```pwsh
+docfx build --serve --open-browser
+```
diff --git a/docs/reference/docfx-cli-reference/docfx-download.md b/docs/reference/docfx-cli-reference/docfx-download.md
new file mode 100644
index 00000000000..c760e42e1fd
--- /dev/null
+++ b/docs/reference/docfx-cli-reference/docfx-download.md
@@ -0,0 +1,43 @@
+# docfx download
+
+## Name
+
+`docfx download <path> [OPTIONS]` - Download remote xref map file and create an xref archive(`.zip`) in local.
+
+## Usage
+
+```pwsh
+docfx download <path> [OPTIONS]
+```
+
+Run `docfx download --help` or `docfx -h` to get a list of all available options.
+
+
+## Arguments
+
+- `[path]` <span class="badge text-bg-primary">required</span>
+
+  Specify the path for the downloaded file.
+
+## Options
+
+- **-h|--help**
+
+  Prints help information
+
+- **-x|--xref**
+
+  Specify the url of xrefmap file (`.json` or `.yml`).
+  e.g.: `https://github.com/dotnet/docfx/raw/main/.xrefmap.json`
+
+## Examples
+
+- Download xrefmap file and save as zip archived file.
+
+```pwsh
+docfx download xrefmap.zip --xref https://github.com/dotnet/docfx/raw/main/.xrefmap.json
+```
+
+> [!NOTE]
+> Downloaded file is archived as `.zip` file regardless of the file extension specified.
+> Zip archive content is converted to `xrefmap.yml`.
diff --git a/docs/reference/docfx-cli-reference/docfx-init.md b/docs/reference/docfx-cli-reference/docfx-init.md
new file mode 100644
index 00000000000..d86d4cb64ac
--- /dev/null
+++ b/docs/reference/docfx-cli-reference/docfx-init.md
@@ -0,0 +1,35 @@
+# docfx init
+
+## Name
+
+`docfx init [OPTIONS]` - Generate an initial docfx.json following the instructions.
+
+## Usage
+
+```pwsh
+docfx init [OPTIONS]
+```
+
+Run `docfx init --help` or `docfx -h` to get a list of all available options.
+
+## Options
+
+- **-h|--help**
+
+  Prints help information
+
+- **-y|--yes**
+
+  Yes to all questions
+
+- **-o|--output**
+
+  Specify the output directory of the generated files
+
+## Examples
+
+- Generate an initial docfx files to current directory with default configurations.
+
+```pwsh
+docfx init --yes
+```
diff --git a/docs/reference/docfx-cli-reference/docfx-merge.md b/docs/reference/docfx-cli-reference/docfx-merge.md
new file mode 100644
index 00000000000..b54c0014d18
--- /dev/null
+++ b/docs/reference/docfx-cli-reference/docfx-merge.md
@@ -0,0 +1,58 @@
+# docfx merge
+
+> [!WARNING]
+> `docfx merge` command was introduced to support API metadata files that are generated for multiple `TargetFrameworks` into one YAML file.  
+> But currently `docfx merge` command is broken. It's not works as expected. (See: https://github.com/dotnet/docfx/issues/2289)
+
+## Name
+
+`docfx merge [config] [OPTIONS]` - Merge .NET base API in YAML files and toc files.
+
+## Usage
+
+```pwsh
+docfx merge [OPTIONS]
+```
+
+Run `docfx merge --help` or `docfx -h` to get a list of all available options.
+
+## Arguments
+
+- `[config]` <span class="badge text-bg-primary">optional</span>
+
+  Specify the path to the docfx configuration file.
+  By default, the `docfx.json' file is used.
+
+## Options
+
+- **-h|--help**
+
+    Prints help information
+
+- **-l|--log**
+
+  Save log as structured JSON to the specified file
+
+- **--logLevel**
+
+  Set log level to error, warning, info, verbose or diagnostic
+
+- **--verbose**
+
+  Set log level to verbose
+
+- **--warningsAsErrors**
+
+  Treats warnings as errors
+
+- **-o|--output**
+
+  Specify the output folder
+
+## Examples
+
+- Merge specified API metadata files to single YAML file.
+
+```pwsh
+docfx merge
+```
diff --git a/docs/reference/docfx-cli-reference/docfx-metadata.md b/docs/reference/docfx-cli-reference/docfx-metadata.md
new file mode 100644
index 00000000000..5afe3b03ec4
--- /dev/null
+++ b/docs/reference/docfx-cli-reference/docfx-metadata.md
@@ -0,0 +1,105 @@
+# docfx metadata
+
+## Name
+
+`docfx metadata [config] [OPTIONS]` - Generate YAML files from source code.
+
+## Usage
+
+```pwsh
+docfx metadata [config] [OPTIONS]
+```
+
+Run `docfx metadata --help` or `docfx -h` to get a list of all available options.
+
+
+## Arguments
+
+- `[config]` <span class="badge text-bg-primary">optional</span>
+
+  Specify the path to the docfx configuration file.
+  By default, the `docfx.json' file is used.
+
+## Options
+
+- **-h|--help**
+
+    Prints help information
+
+- **-l|--log**
+
+  Save log as structured JSON to the specified file
+
+- **--logLevel**
+
+  Set log level to error, warning, info, verbose or diagnostic
+
+- **--verbose**
+
+  Set log level to verbose
+
+- **--warningsAsErrors**
+
+  Treats warnings as errors
+
+- **--shouldSkipMarkup**
+
+  Skip to markup the triple slash comments
+
+- **-o|--output**
+
+  Specify the output base directory
+
+- **--outputFormat**
+
+  Specify the output type.
+  - `mref`
+  - `markdown`
+  - `apiPage`
+
+- **--filter**
+
+  Specify the filter config file.
+
+- **--globalNamespaceId**
+
+  Specify the name to use for the global namespace.
+
+- **--property**
+
+  --property <n1>=<v1>;<n2>=<v2> An optional set of MSBuild properties used when interpreting project files. These are the same properties that are passed to MSBuild via the /property:<n1>=<v1>;<n2>=<v2> command line argument.
+
+- **--disableGitFeatures**
+
+  Disable fetching Git related information for articles. By default it is enabled and may have side effect on performance when the repo is large.
+
+- **--disableDefaultFilter**
+
+  Disable the default API filter (default filter only generate public or protected APIs).
+
+- **--namespaceLayout**
+
+  Determines the namespace layout in table of contents.
+
+    - `Flattened`
+      - Renders the namespaces as a single flat list,
+    - `Nested`
+      - Renders the namespaces in a nested tree form.
+
+- **--memberLayout**
+
+  Determines the member page layout.
+
+  - `SamePage`
+    - Place members in the same page as their containing type.
+  - `SeparatePages`
+    - Place members in separate pages.
+
+## Examples
+
+- Generate YAML files with default config.
+
+```pwsh
+docfx metadata
+```
+
diff --git a/docs/reference/docfx-cli-reference/docfx-pdf.md b/docs/reference/docfx-cli-reference/docfx-pdf.md
new file mode 100644
index 00000000000..53d79682f90
--- /dev/null
+++ b/docs/reference/docfx-cli-reference/docfx-pdf.md
@@ -0,0 +1,54 @@
+# docfx pdf
+
+## Name
+
+`docfx pdf [config] [OPTIONS]` - Generate pdf file.
+
+## Usage
+
+```pwsh
+docfx pdf [config] [OPTIONS]
+```
+
+Run `docfx pdf --help` or `docfx -h` to get a list of all available options.
+
+## Arguments
+
+- `[config]` <span class="badge text-bg-primary">optional</span>
+
+  Specify the path to the docfx configuration file.
+  By default, the `docfx.json' file is used.
+
+## Options
+
+- **-h|--help**
+
+    Prints help information
+
+- **-l|--log**
+
+  Save log as structured JSON to the specified file.
+
+- **--logLevel**
+
+  Set log level to error, warning, info, verbose or diagnostic.
+
+- **--verbose**
+
+  Set log level to verbose.
+
+- **--warningsAsErrors**
+
+  Treats warnings as errors.
+
+- **-o|--output**
+
+  Specify the output base directory.
+
+## Examples
+
+- Generate PDF files in the output directory specified by `docfx.json`.
+
+```pwsh
+docfx pdf
+```
diff --git a/docs/reference/docfx-cli-reference/docfx-serve.md b/docs/reference/docfx-cli-reference/docfx-serve.md
new file mode 100644
index 00000000000..3a95eb802d8
--- /dev/null
+++ b/docs/reference/docfx-cli-reference/docfx-serve.md
@@ -0,0 +1,56 @@
+# docfx serve
+
+## Name
+
+`docfx serve [directory] [OPTIONS]` - Host a local static website.
+
+## Usage
+
+```pwsh
+docfx serve [directory] [OPTIONS]
+```
+
+Run `docfx serve --help` or `docfx -h` to get a list of all available options.
+
+## Arguments
+
+- `[directory]` <span class="badge text-bg-primary">optional</span>
+
+   Path to the directory to serve.
+   If not specified. Current directory is used.
+
+## Options
+
+- **-h|--help**
+
+    Prints help information
+
+- **-n|--hostname.**
+
+  Specify the hostname of the hosted website
+
+- **-p|--port.**
+
+  Specify the port of the hosted website
+
+- **--open-browser.**
+
+  Open a web browser when the hosted website starts.
+
+- **--open-file<RELATIVE_PATH>.**
+
+  Open a file in a web browser when the hosted website starts.
+
+## Examples
+
+- Host a website that generated by `docfx build` command.
+
+```pwsh
+docfx serve _site
+```
+
+- Host a website that generated by `docfx build` command. And launch default browser.
+
+```pwsh
+docfx --serve _site --open-browser
+```
diff --git a/docs/reference/docfx-cli-reference/docfx-template.md b/docs/reference/docfx-cli-reference/docfx-template.md
new file mode 100644
index 00000000000..0280dfacaca
--- /dev/null
+++ b/docs/reference/docfx-cli-reference/docfx-template.md
@@ -0,0 +1,56 @@
+# docfx build
+
+## Name
+
+`docfx template [sub command]` - List available templates or export template files.
+
+## Usage
+
+```pwsh
+docfx template list [OPTIONS]
+
+docfx template export [template] [OPTIONS]
+```
+
+Run `docfx template --help` or `docfx -h` to get a list of all available options.
+
+## Arguments
+
+- `[template]` <span class="badge text-bg-primary">optional</span>
+
+  Specify the name of template.
+  If not specified. All the available templates will be exported.
+
+## Options
+
+- **-h, --help**
+  Prints help information
+
+- **-a|--all**
+
+  If specified, all the available templates will be exported.
+
+- **-o|--output**
+
+  Specify the output folder path for the exported templates.
+  If not specified. `_exported_templates` is used.
+
+## Examples
+
+- Print all the available template names.
+
+```pwsh
+docfx template list
+```
+
+- Export all the available templates.
+
+```pwsh
+docfx template export --all
+```
+
+- Export modern templates contents.
+
+```pwsh
+docfx template export modern
+```
\ No newline at end of file
diff --git a/docs/reference/docfx-cli-reference/docfx.md b/docs/reference/docfx-cli-reference/docfx.md
new file mode 100644
index 00000000000..46b10624031
--- /dev/null
+++ b/docs/reference/docfx-cli-reference/docfx.md
@@ -0,0 +1,150 @@
+# docfx
+
+## Name
+
+`docfx [config] [OPTIONS]` - Runs metadata, build and pdf commands.
+
+## Usage
+
+```pwsh
+docfx [config] [OPTIONS]
+```
+
+Run `docfx --version` to get the version of the docfx.
+
+Run `docfx --help` or `docfx -h` to get a list of all available commands and options.
+
+Run `docfx <command> --help` or `docfx <command> -h` to get help on a specific command.
+
+## Arguments
+
+- `[config]` <span class="badge text-bg-primary">optional</span>
+
+  Specify the path to the docfx configuration file.
+  By default, the `docfx.json' file is used.
+
+## Options
+
+- **-h|--help**
+
+  Prints help information
+
+- **-l|--log**
+
+  Save log as structured JSON to the specified file
+
+- **--logLevel**
+
+  Set log level to error, warning, info, verbose or diagnostic
+
+- **--verbose**
+
+  Set log level to verbose
+
+- **--warningsAsErrors**
+
+  Treats warnings as errors
+
+- **-o|--output**
+
+  Specify the output base directory
+
+- **-m|--metadata**
+
+  Specify a list of global metadata in key value pairs (e.g., --metadata _appTitle="My App" --metadata _disableContribution)
+
+- **-x|--xref**
+
+  Specify the urls of xrefmap used by content files.
+
+- **-t|--template**
+
+  Specify the template name to apply to. If not specified, output YAML file will not be transformed.
+
+- **--theme**
+
+  Specify which theme to use. By default 'default' theme is offered.
+
+- **-s|--serve**
+
+  Host the generated documentation to a website
+
+- **-n|--hostname**
+
+  Specify the hostname of the hosted website (e.g., 'localhost' or '*')
+
+- **-p|--port**
+
+  Specify the port of the hosted website
+
+- **--open-browser**
+
+  Open a web browser when the hosted website starts.
+
+- **--open-file<RELATIVE_PATH>**
+
+  Open a file in a web browser when the hosted website starts.
+
+- **--debug**
+
+  Run in debug mode. With debug mode, raw model and view model will be exported automatically when it encounters error when applying templates. If not specified, it is false.
+
+- **--debugOutput**
+
+  The output folder for files generated for debugging purpose when in debug mode. If not specified, it is ${TempPath}/docfx
+
+- **--exportRawModel**
+
+  If set to true, data model to run template script will be extracted in .raw.model.json extension
+
+- **--rawModelOutputFolder**
+
+  Specify the output folder for the raw model. If not set, the raw model will be generated to the same folder as the output documentation
+
+- **--viewModelOutputFolder**
+
+  Specify the output folder for the view model. If not set, the view model will be generated to the same folder as the output documentation
+
+- **--exportViewModel**
+
+  If set to true, data model to apply template will be extracted in .view.model.json extension
+
+- **--dryRun**
+
+  If set to true, template will not be actually applied to the documents. This option is always used with --exportRawModel or --exportViewModel is set so that only raw model files or view model files are generated.
+
+- **--maxParallelism**
+
+  Set the max parallelism, 0 is auto.
+
+- **--markdownEngineProperties**
+
+  Set the parameters for markdown engine, value should be a JSON string.
+
+- **--postProcessors**
+
+  Set the order of post processors in plugins
+
+- **--disableGitFeatures**
+
+  Disable fetching Git related information for articles. By default it is enabled and may have side effect on performance when the repo is large.
+
+- **-v|--version**
+
+  Prints version information
+
+## Examples
+
+- Runs `metadata`, `build` and `pdf` commands.
+  with default `docfx.json` config file.
+
+```pwsh
+docfx
+```
+
+- Runs `metadata`, `build` and `pdf` commands.
+  Then serve generated site, and open site with default browser.
+
+```pwsh
+docfx --serve --open-browser
+```
\ No newline at end of file
diff --git a/docs/reference/docfx-cli-reference/overview.md b/docs/reference/docfx-cli-reference/overview.md
new file mode 100644
index 00000000000..202e75618e3
--- /dev/null
+++ b/docs/reference/docfx-cli-reference/overview.md
@@ -0,0 +1,42 @@
+---
+title: Overview
+---
+
+# Commandline Overview
+
+## Introduction
+
+`docfx` is used to generate documentation for programs. It has the ability to:
+
+1. Extract language metadata for programing languages as defined in [Metadata Format Specification](../../spec/metadata_format_spec.md).
+   Currently `C#` and `VB` are supported (although see note below regarding `VB` support).
+   The language metadata is saved in `YAML` format as described in [YAML 1.2](https://yaml.org/spec/1.2.2).
+2. Look for available conceptual files as provided and link them with existing programs using the syntax described in [Metadata Yaml Format](../../spec/metadata_format_spec.md).
+   Supported conceptual files are *plain text* files, *html* files, and *markdown* files.
+3. Generate documentation to
+   a. Visualize language metadata, with extra **content** provided by linked conceptual files using the syntax described in [Metadata Yaml Format](../../spec/metadata_format_spec.md).
+   b. Organize and render available conceptual files which can be easily cross-referenced with language metadata pages.
+   Docfx supports **CommonMark** for writing conceptual files.
+   **DFM** supports all *Github Flavored Markdown(GFM)* syntax with 2 exceptions when resolving [list](../../docs/markdown.md#differences-introduced-by-dfm-syntax).
+   It also adds several new features including *file inclusion*, *cross reference*, and *yaml header*.
+
+> [!NOTE]
+> Although Docfx is able to process `VB` projects and individual `VB` source code files and extract metadata from them, the documentation output from Docfx is always in `C#` format, i.e. types and member signatures, etc., are shown in `C#` format and not `VB` format.
+
+Currently generating documentation to a *client only* **website** is supported. The generated **website** can be easily published to whatever platform such as *Github Pages* and *Azure Website* with little extra effort.
+
+Generating offline documentation such as **PDF** is also supported.
+
+## `docfx` commands
+
+| Command                             | Description                                                                |
+|-------------------------------------|----------------------------------------------------------------------------|
+| [docfx](docfx.md)                   | Runs metadata, build and pdf commands.                                     |
+| [docfx metadata](docfx-metadata.md) | Generate YAML files from source code.                                      |
+| [docfx build](docfx-build.md)       | Generate static site contents from input files.                            |
+| [docfx pdf](docfx-pdf.md)           | Generate pdf file.                                                         |
+| [docfx serve](docfx-serve.md)       | Host a local static website.                                               |
+| [docfx init](docfx-init.md)         | Generate an initial docfx.json following the instructions.                 |
+| [docfx template](docfx-template.md) | List available templates or export template files.                         |
+| [docfx download](docfx-download.md) | Download remote xref map file and create an xref archive(`.zip`) in local. |
+| [docfx merge](docfx-merge.md)       | Merge .NET base API in YAML files and toc files.                           |
diff --git a/docs/reference/docfx-cli-reference/toc.yml b/docs/reference/docfx-cli-reference/toc.yml
new file mode 100644
index 00000000000..92548146a54
--- /dev/null
+++ b/docs/reference/docfx-cli-reference/toc.yml
@@ -0,0 +1,10 @@
+- href: overview.md
+- href: docfx.md
+- href: docfx-metadata.md
+- href: docfx-build.md
+- href: docfx-pdf.md
+- href: docfx-serve.md
+- href: docfx-init.md
+- href: docfx-template.md
+- href: docfx-download.md
+- href: docfx-merge.md
diff --git a/src/docfx/Models/BuildCommandOptions.cs b/src/docfx/Models/BuildCommandOptions.cs
index a85aad72b2b..5accb2d7c52 100644
--- a/src/docfx/Models/BuildCommandOptions.cs
+++ b/src/docfx/Models/BuildCommandOptions.cs
@@ -17,7 +17,7 @@ internal class BuildCommandOptions : LogOptions
     [CommandArgument(0, "[config]")]
     public string ConfigFile { get; set; }
 
-    [Description("Specify a list of global metadata in key value pairs (e.g., --metadata _appTitle=\"My App\" --metadata _disableContribution)")]
+    [Description("Specify a list of global metadata in key value pairs (e.g. --metadata _appTitle=\"My App\" --metadata _disableContribution)")]
     [CommandOption("-m|--metadata")]
     public string[] Metadata { get; set; }