docs: Copyedits of CLI and docfx.json pages (#8989)

docs/reference/docfx-cli-reference.md

@@ -97,16 +97,17 @@ docfx build [-o:<output_path>] [-t:<template 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]
-> Please note that `homepage` is not supported in `toc.md`.
-> And if `href` is referencing to a **folder**, it must end with `/`.
+> `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**. Can be a folder or a file *UNDER* current folder. A folder must end with `/`. In case of a folder, TOC.md inside the folder will be rendered as second level TABLE-OF-CONTENT. As in website, it will be rendered as a sidebar.
+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**

docs/reference/docfx-json-reference.md

@@ -71,29 +71,29 @@ allowCompilationErrors | When enabled, continues documentation generation in c
 Key | Description
 -------------------------|-----------------------------
 content | Contains all the files to generate documentation, including metadata `yml` files and conceptual `md` files. `name-files` file mapping with several ways to define it, as to be described in **Section4**. The `files` contains all the project files to have API generated.
-resource | Contains all the resource files that conceptual and metadata files dependent on, e.g. image files. `name-files` file mapping with several ways to define it, as to be described in **Section4**.
-overwrite | Contains all the conceptual files which contains yaml header with `uid` and is intended to override the existing metadata `yml` files. `name-files` file mapping with several ways to define it, as to be described in **Section4**.
+resource | Contains all the resource files that conceptual and metadata files depend on (e.g., image files). `name-files` file mapping with several ways to define it, as to be described in **Section4**.
+overwrite | Contains all the conceptual files that contain yaml headers with `uid` values and is intended to override the existing metadata `yml` files. `name-files` file mapping with several ways to define it, as to be described in **Section4**.
 globalMetadata | Contains metadata that will be applied to every file, in key-value pair format. For example, you can define `"_appTitle": "This is the title"` in this section, and when applying template `default`, it will be part of the page title as defined in the template.
 fileMetadata | Contains metadata that will be applied to specific files. `name-files` file mapping with several ways to define it, as to be described in **Section4**.
-globalMetadataFiles | Specify a list of JSON file path containing globalMetadata settings, as similar to `{"key":"value"}`. Please read **Section3.2.3** for detail.
-fileMetadataFiles | Specify a list of JSON file path containing fileMetadata settings, as similar to `{"key":"value"}`. Please read **Section3.2.3** for detail.
-template | The templates applied to each file in the documentation. It can be a string or an array. The latter ones will override the former ones if the name of the file inside the template collides. If omitted, embedded `default` template will be used.
+globalMetadataFiles | Specifies a list of JSON file paths containing globalMetadata settings, as similar to `{"key":"value"}`. See **Section3.2.3** for more detail.
+fileMetadataFiles | Specifies a list of JSON file paths containing fileMetadata settings, as similar to `{"key":"value"}`. See **Section3.2.3** for more detail.
+template | The templates applied to each file in the documentation. Specify a string or an array. The latter ones will override the former ones if the name of the file inside the template collides. If omitted, the embedded `default` template will be used.
 theme | The themes applied to the documentation. Theme is used to customize the styles generated by `template`. It can be a string or an array. The latter ones will override the former ones if the name of the file inside the template collides. If omitted, no theme will be applied, the default theme inside the template will be used.
 xref | Specifies the urls of xrefmap used by content files. Currently, it supports following scheme: http, https, file.
 exportRawModel | If set to true, data model to run template script will be extracted in `.raw.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.
+rawModelOutputFolder | Specifies the output folder for the raw model. If not set, the raw model will appear in the same folder as the output documentation.
 exportViewModel | If set to true, data model to apply template will be extracted in `.view.json` extension.
-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.
-dryRun | If set to true, template will not be actually applied to the documents. This option is always used with `--exportRawModel` or `--exportViewModel`, so that only raw model files or view model files are generated.
-maxParallelism | Set the max parallelism, 0 (default) is same as the count of CPU cores.
-markdownEngineProperties | Set the parameters for markdown engine, value is a JSON object.
-keepFileLink | If set to true, docfx does not dereference (aka. copy) file to the output folder, instead, it saves a `link_to_path` property inside `manifest.json` to indicate the physical location of that file. A file link will be created by incremental build and copy resource file.
-sitemap | In format [SitemapOptions](#125-sitemapoptions) Specifies the options for the sitemap.xml file.
-disableGitFeatures | Disable fetching Git related information for articles. Set to `true` if fetching git related information is slow for huge Git repositories. Default value is `false`.
+viewModelOutputFolder | Specifies the output folder for the view model. If not set, the view model will appear in the same folder as the output documentation.
+dryRun | If set to true, the template will not be applied to the documents. This option is always used with `--exportRawModel` or `--exportViewModel` so that only raw model files or view model files will be generated.
+maxParallelism | Sets the max parallelism. Setting 0 (default) is the same as setting to the count of CPU cores.
+markdownEngineProperties | Sets the parameters for the markdown engine, value is a JSON object.
+keepFileLink | If set to true, docfx does not dereference (i.e., copy) the file to the output folder, instead, it saves a `link_to_path` property inside `manifest.json` to indicate the physical location of that file. A file link will be created by incremental build and copy resource file.
+sitemap | In format [SitemapOptions](#125-sitemapoptions). Specifies the options for the sitemap.xml file.
+disableGitFeatures | Disable fetching Git related information for articles. Set to `true` if fetching Git related information is slow for huge Git repositories. Default value is `false`.
 
 #### 1.2.1 `Template`s and `Theme`s
 
-*Template*s are used to transform *YAML* files generated by `docfx` to human-readable *page*s. A *page* can be a markdown file, a html file or even a plain text file. Each *YAML* file will be transformed to ONE *page* and be exported to the output folder preserving its relative path to `src`. For example, if *page*s are in *HTML* format, a static website will be generated in the output folder.
+*Template*s are used to transform *YAML* files generated by `docfx` to human-readable *page*s. A *page* can be a markdown file, an html file or even a plain text file. Each *YAML* file will be transformed to ONE *page* and be exported to the output folder preserving its relative path to `src`. For example, if *page*s are in *HTML* format, a static website will be generated in the output folder.
 
 *Theme* is to provide general styles for all the generated *page*s. Files inside a *theme* will be generally **COPIED** to the output folder. A typical usage is, after *YAML* files are transformed to *HTML* pages, well-designed *CSS* style files in a *Theme* can then overwrite the default styles defined in *template*, e.g. *main.css*.
 
@@ -135,7 +135,7 @@ To use a custom template, one way is to specify template path with `--template`
 > DocFX has embedded templates: `default`, `default(zh-cn)`, `pdf.default`, `statictoc` and `common`.
 > Please avoid using these as template folder name.
 
-To custom theme, one way is to specify theme name with `--theme` command option, multiple themes must be separated by `,` with no spaces. The other way is to set key-value mapping in `docfx.json` as similar to defining template. Also, both `.zip` file and folder are supported.
+One way to set a custom theme is to specify the theme name with the `--theme` command option. Multiple themes must be separated by `,` with no spaces. The other way is to set a key-value mapping in `docfx.json` similar to the way templates are defined. Also, either a `.zip` file or a folder can be used.
 
 Please refer to [How to Create Custom Templates](../tutorial/howto_create_custom_template.md) to create custom templates.
 
@@ -202,13 +202,13 @@ _noindex | bool | File(s) specified are not returned in search res
 
 #### 1.2.3 Separated metadata files for global metadata and file metadata
 
-There're three ways to set metadata for a file in DocFX:
+There are three ways to set metadata for a file in DocFX:
 
-1. using global metadata, it will set metadata for every file.
-2. using file metadata, it will set metadata for files that match pattern.
-3. using YAML header, it will set metadata for current file.
+1. Using global metadata, which will set metadata for every file.
+2. Using file metadata, which will set metadata for files that match the pattern you specify.
+3. Using YAML header, which will set metadata for the current file.
 
-In above ways, the later way will always overwrite the former way if the same key of metadata is set.
+In the list above, the later method way will always overwrite the former if the same key of metadata is set.
 
 Here we will show you how to set global metadata and file metadata using separated metadata files. Take global metadata for example, you can set `globalMetadataFiles` in `docfx.json` or `--globalMetadataFiles` in build command line. The usage of `fileMetadataFiles` is the same as `globalMetadataFiles`.