Document the Heft config files

_data/navigation.yaml

@@ -29,12 +29,12 @@ docs_nav:
         url: /pages/heft/overview
       - title: Architecture
         url: /pages/heft/architecture
-      - title: Core Plugins
+      - title: Core plugins
         url: /pages/heft/core_plugins
-      - title: Heft Command Line
+      - title: Heft command line
         url: /pages/heft/cli
 
-  - title: Heft Tasks
+  - title: Heft tasks
     subitems:
       - title: api-extractor
         url: /pages/heft_tasks/api-extractor
@@ -51,12 +51,25 @@ docs_nav:
       - title: webpack
         url: /pages/heft_tasks/webpack
 
+  - title: Heft config files
+    subitems:
+      - title: clean.json
+        url: /pages/heft_configs/clean_json
+      - title: copy-static-assets.json
+        url: /pages/heft_configs/copy-static-assets_json
+      - title: plugins.json
+        url: /pages/heft_configs/plugins_json
+      - title: typescript.json
+        url: /pages/heft_configs/typescript_json
+      - title: webpack.json
+        url: /pages/heft_configs/webpack_json
+
   - title: Contributing
     subitems:
-      - title: Getting Started
+      - title: Getting started
         url: /pages/contributing/get_started
 
   - title: Help
     subitems:
-      - title: Getting Support
+      - title: Getting support
         url: /pages/help/support

pages/contributing/get_started.md

@@ -1,6 +1,6 @@
 ---
 layout: page
-title: Getting Started
+title: Getting started
 navigation_source: docs_nav
 ---
 

pages/heft/architecture.md

@@ -1,6 +1,6 @@
 ---
 layout: page
-title: Heft Architecture
+title: Heft architecture
 navigation_source: docs_nav
 ---
 
@@ -15,5 +15,5 @@ Heft's operation is organized around the following concepts:
 
  
 > **Future plans:** Today Rush commands can only invoke Heft actions.  However, in the future we want to implement a "multiphase build" feature that will enable Rush to orchestrate more granular steps of work.  For example, once a library dependency has compiled its output, Rush could start building the application before the library finishes running its unit tests.  This feature will bring some additional jargon:
-> - **command** - A monorepo command-line action as defined globally in [command-line.json](https://rushjs.io/pages/configs/command_line_json/).
+> - **command** - A monorepo command-line action as defined globally in [command-line.json](https://rushjs.io/pages/configs/command-line_json/).
 > - **phase** - This is similar to Heft's "stage", except that phases will be defined globally so that Rush can model their dependency relationships.

pages/heft/cli.md

@@ -1,6 +1,6 @@
 ---
 layout: page
-title: Heft Command Line
+title: Heft command line
 navigation_source: docs_nav
 ---
 

pages/heft/core_plugins.md

@@ -1,6 +1,6 @@
 ---
 layout: page
-title: Core Plugins
+title: Core plugins
 navigation_source: docs_nav
 ---
 

pages/heft_configs/clean_json.md

@@ -0,0 +1,29 @@
+---
+layout: page
+title: clean.json
+navigation_source: docs_nav
+---
+
+## Supported file paths
+
+- **common/config/heft/clean.json**
+- **<project folder>/.heft/clean.json**
+
+## Template
+
+```js
+/**
+ * Configures the "clean" stage for Heft.
+ */
+ {
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/clean.schema.json",
+
+  /**
+   * Glob patterns to be deleted by the "heft clean" action.  The paths are resolved relative to the project folder.
+   */
+  // "pathsToDelete": [
+  //   "lib",
+  //   "*.tmp"
+  // ]
+}
+```

pages/heft_configs/copy-static-assets_json.md

@@ -0,0 +1,43 @@
+---
+layout: page
+title: copy-static-assets.json
+navigation_source: docs_nav
+---
+
+## Supported file paths
+
+- **common/config/heft/copy-static-assets.json**
+- **<project folder>/.heft/copy-static-assets.json**
+
+## Template
+
+```js
+/**
+ * Configures the "copy-static-assets" task for Heft.
+ */
+ {
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/copy-static-assets.schema.json",
+
+  /**
+   * File extensions that should be copied from the src folder to the destination folder(s).
+   */
+  // "fileExtensions": [
+  //   ".css"
+  // ],
+
+  /**
+   * Glob patterns that should be explicitly included.
+   */
+  // "includeGlobs": [
+  //   "some/path/*.js"
+  // ],
+
+  /**
+   * Glob patterns that should be explicitly excluded. This takes precedence over globs listed
+   * in "includeGlobs" and files that match the file extensions provided in "fileExtensions".
+   */
+  // "excludeGlobs": [
+  //   "some/path/*.css"
+  // ]
+}
+```

pages/heft_configs/plugins_json.md

@@ -0,0 +1,43 @@
+---
+layout: page
+title: plugins.json
+navigation_source: docs_nav
+---
+
+## Supported file paths
+
+- **common/config/heft/plugins.json**
+- **<project folder>/.heft/plugins.json**
+
+## Template
+
+```js
+/**
+ * Specifies the plugins that will be loaded by Heft.
+ */
+ {
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/plugins.schema.json",
+
+  /**
+   * The list of Heft plugins to be loaded.
+   */
+  "plugins": [
+    /**
+     * The list of Heft plugins to be loaded.
+     */
+
+    // {
+    //  /**
+    //   * The path to the plugin package.
+    //   */
+    //  "plugin": "path/to/my-plugin",
+    //
+    //  /**
+    //   * An optional object that provides additional settings that may be defined by the plugin.
+    //   */
+    //  // "options": { }
+    // }
+  ]
+}
+```
+

pages/heft_configs/typescript_json.md

@@ -0,0 +1,59 @@
+---
+layout: page
+title: typescript.json
+navigation_source: docs_nav
+---
+
+## Supported file paths
+
+- **common/config/heft/typescript.json**
+- **<project folder>/.heft/typescript.json**
+
+## Template
+
+```js
+/**
+ * Configures the TypeScript plugin for Heft.  This plugin also manages linting.
+ */
+ {
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/typescript.schema.json",
+
+  /**
+   * Can be set to "copy" or "hardlink". If set to "copy", copy files from cache.
+   * If set to "hardlink", files will be hardlinked to the cache location.
+   * This option is useful when producing a tarball of build output as TAR files don't
+   * handle these hardlinks correctly. "hardlink" is the default behavior.
+   */
+  // "copyFromCacheMode": "copy",
+
+  /**
+   * If provided, emit these module kinds in addition to the modules specified in the tsconfig.
+   * Note that this option only applies to the main tsconfig.json configuration.
+   */
+  "additionalModuleKindsToEmit": [
+    // {
+    //   /**
+    //    * (Required) Must be one of "commonjs", "amd", "umd", "system", "es2015", "esnext"
+    //    */
+    //  "moduleKind": "amd",
+    //
+    //   /**
+    //    * (Required) The path where the output will be written.
+    //    */
+    //    "outFolderPath": "lib-amd"
+    // }
+  ]
+
+  /**
+   * If set to "true", the TSlint task will not be invoked.
+   */
+  // "disableTslint": true,
+
+  /**
+   * Set this to change the maximum number of file handles that will be opened for writing.
+   * The default is 50.
+   */
+  // "maxWriteParallelism": 50
+}
+
+```

pages/heft_configs/webpack_json.md

@@ -0,0 +1,27 @@
+---
+layout: page
+title: webpack.json
+navigation_source: docs_nav
+---
+
+## Supported file paths
+
+- **common/config/heft/webpack.json**
+- **<project folder>/.heft/webpack.json**
+
+## Template
+
+```js
+/**
+ * Configures the Webpack plugin for Heft.
+ */
+ {
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/webpack.schema.json",
+
+  /**
+   * A path to a Webpack configuration JS file. If this isn't specified, and a Webpack configuration isn't
+   * specified via another plugin, Webpack won't be run.
+   */
+  // "webpackConfigFilePath": "webpack.config.js"
+}
+```

pages/help/support.md

@@ -1,6 +1,6 @@
 ---
 layout: page
-title: Getting Support
+title: Getting support
 navigation_source: docs_nav
 ---
 

pages/news.md

@@ -1,6 +1,6 @@
 ---
 layout: page
-title: What's New
+title: What's new
 ---
 
 For general planning updates, please see the [Project roadmap]({% link pages/overview/roadmap.md %}).