docs: generate reference properties from source

AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md
+
+## Task Completion Requirements
+- Always review your work and verify the results of your work using the appropriate tools before considering tasks completed.
+
+## Project Snapshot
+
+[Nx plugin](https://nx.dev) for [Atlassian Forge](https://developer.atlassian.com/platform/forge/) that aims to assist in efficient, scalable app development and remove the mental overhead of how to set up a Forge project.
+
+## Core Priorities
+
+1. Reliability first.
+2. Simplicity and correctness.
+3. Avoid accidental complexity.
+
+If a tradeoff is required, choose correctness and robustness over short-term convenience.
+
+## Maintainability
+
+Long-term maintainability is a core priority. If you add new functionality, first check if there is shared logic that can be extracted to a separate module. Duplicate logic across multiple files is a code smell and should be avoided. Don't be afraid to change existing code. Don't take shortcuts by just adding local logic to solve a problem. If you are not sure, research to find a good solution. 

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

docs/.vitepress/config.mts

@@ -1,6 +1,25 @@
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
 import { defineConfig } from 'vitepress';
+import {
+  injectReferenceOptions,
+  validateReferenceDocs,
+} from '../../tools/docs/src/lib/reference-docs';
 
 const base = '/nx-forge/';
+const workspaceRoot = fileURLToPath(new URL('../..', import.meta.url));
+
+function normalizeViteId(id: string): string {
+  return id.replace(/\\/g, '/').split('?', 1)[0];
+}
+
+function isReferenceMarkdownFile(id: string): boolean {
+  const normalizedId = normalizeViteId(id);
+
+  return (
+    normalizedId.includes('/docs/reference/') && normalizedId.endsWith('.md')
+  );
+}
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -18,6 +37,36 @@ export default defineConfig({
     ],
   ],
   cleanUrls: true,
+  vite: {
+    plugins: [
+      {
+        name: 'nx-forge-reference-docs',
+        enforce: 'pre',
+        buildStart() {
+          validateReferenceDocs(workspaceRoot);
+        },
+        load(id) {
+          if (!isReferenceMarkdownFile(id)) {
+            return null;
+          }
+
+          const filePath = normalizeViteId(id);
+          const markdown = readFileSync(filePath, 'utf8');
+
+          return injectReferenceOptions(markdown, filePath, workspaceRoot);
+        },
+        transform(code, id) {
+          if (!isReferenceMarkdownFile(id)) {
+            return null;
+          }
+
+          const filePath = normalizeViteId(id);
+
+          return injectReferenceOptions(code, filePath, workspaceRoot);
+        },
+      },
+    ],
+  },
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
     search: {

docs/reference/executors.md

@@ -4,8 +4,6 @@ Documents [the executors](https://nx.dev/concepts/executors-and-configurations)
 
 Append `--help` or `-h` for any of the plugin executors to explore all available options.
 
-[//]: # (Used https://brianwendt.github.io/json-schema-md-doc/ to generate the properties markdown from schema.json files)
-
 ## Forge
 
 ```shell
@@ -20,52 +18,30 @@ Where a custom executor is provided by Nx Forge, prefer using the custom executo
 
 :::
 
-**_Properties_**
+### Options
 
-- <b id="#/properties/outputPath">outputPath</b> `required`
-  - _The output path of the Forge app files._
-  - Type: `string`
+| Option | Type                       | Description                         | Default |
+| --- |----------------------------|-------------------------------------| --- |
+| `--outputPath` | `string`<br>**[required]** | Output path of the Forge app files. | - |
 
 Nx Forge-provided executors ensure that the Nx project configuration is updated where necessary when the Forge command has run. For example, registering a Forge app using `nx forge <nx-forge-app-name> register` will invoke the Forge CLI directly and only update the Forge app ID in the manifest file in the output directory. The next time you run `nx build <nx-forge-app-name>` the manifest file in the output path will be overwritten.
 The correct way to do this is to run [`nx register <nx-forge-app-name>`](#register), which will update the app ID of the `manifest.yml` within the `<nx-forge-app-name>` project root.
 
 ## Build <Badge type="warning" text="Deprecated" />
 
+::: warning
+The `build` executor is deprecated in favor of a native Nx build (webpack or esbuild) in combination with the `package` executor. Refer to the [migration guide](../guides/migrating-to-package-executor) for more information.
+:::
+
 ```shell
 nx build <nx-forge-app-name>
 ```
 
-Builds the Forge app project named `<nx-forge-app-name>` to the directory specified in the `outputPath` property. If the Forge app project has dependent resource projects (Custom UI), this will build dependent projects first before building the Forge app itself. 
+Builds the Forge app project named `<nx-forge-app-name>` to the directory specified in the `outputPath` option. If the Forge app project has dependent resource projects (Custom UI), this will build dependent projects first before building the Forge app itself.
 
-::: warning
-The `build` executor is deprecated in favor of a native Nx build (webpack or esbuild) in combination with the `package` executor. Refer to the [migration guide](../guides/migrating-to-package-executor) for more information.
-:::
+### Options
 
-**_Properties_**
-
-- <b id="#/properties/outputPath">outputPath</b> `required`
-  - _Output path of the generated files._
-  - Type: `string`
-- <b id="#/properties/customUIPath">customUIPath</b>
-  - _Custom UI output path relative to the outputPath._
-  - Type: `string`
-- <b id="#/properties/resourceOutputPathMap">resourceOutputPathMap</b>
-  - _Map of resource project names to their respective output path (relative to the workspace root)._
-  - Type: `object`
-  - Default: `{}`
-- <b id="#/properties/watch">watch</b>
-  - _Enable re-building when files change._
-  - Type: `boolean`
-  - Default: _false_
-- <b id="#/properties/sourceMap">sourceMap</b>
-  - _Output sourcemaps. Use 'hidden' for use with error reporting tools without generating sourcemap comment._
-- <b id="#/properties/webpackConfig">webpackConfig</b>
-  - _Path to a function which takes a webpack config, some context and returns the resulting webpack config. See https://nx.dev/guides/customize-webpack_
-  - Type: `string`
-- <b id="#/properties/uiKit2Packaging">uiKit2Packaging</b> <Badge type="warning" text="Experimental" />
-  - _Enables UI Kit compatible packaging._
-  - Type: `boolean`
-  - Default: _false_
+<!-- nx-forge:options executor=build -->
 
 ## Package
 
@@ -79,26 +55,9 @@ Packages the Forge app project named `<nx-forge-app-name>` into a deployable art
 The `package` executor is intended to be used with a standard Nx `build` executor, for example, Webpack or esbuild. Refer to the [migration guide](../guides/migrating-to-package-executor) for more information.
 :::
 
-**_Properties_**
-
- - <b id="#/properties/outputPath">outputPath</b> `required`
-	 - _Output path of the generated files._
-	 - Type: `string`
- - <b id="#/properties/resourcePath">resourcePath</b>
-	 - _Path where resource files such as Custom UI output is placed relative to the outputPath._
-	 - Type: `string`
- - <b id="#/properties/resourceOutputPathMap">resourceOutputPathMap</b>
-   - _Map of resource project names to their respective output path (relative to the workspace root)._
-   - Type: `object`
-   - Default: `{}`
-- <b id="#/properties/tsConfig">tsConfig</b>
-  - _The path for the TypeScript configuration file, relative to the current project._
-  - Type: `string`
-  - Default: _"tsconfig.app.json"_
-- <b id="#/properties/uiKit2Packaging">uiKit2Packaging</b> <Badge type="warning" text="Experimental" />
-  - _Enables UI Kit compatible packaging._
-  - Type: `boolean`
-  - Default: _false_
+### Options
+
+<!-- nx-forge:options executor=package -->
 
 This executor will copy the output of dependent resource project builds to the `resourcePath` directory. To do this, the executor tries to infer the output path of dependent resources (Custom UI, UI Kit) from the dependent project's `build` target configuration as follows:
 
@@ -118,30 +77,9 @@ Deploys the Forge app project named `<nx-forge-app-name>` to the Forge platform.
 
 _Mirrors the [deploy command](https://developer.atlassian.com/platform/forge/cli-reference/deploy/) of the Forge CLI._
 
-**_Properties_**
-
-- <b id="#/properties/outputPath">outputPath</b> `required`
-  - _The output path of the Forge app files._
-  - Type: `string`
-- <b id="#/properties/environment">environment</b>
-  - _Environment to deploy to._
-  - Type: `string`
-  - Default: _"development"_
-- <b id="#/properties/verify">verify</b>
-  - _Run pre-deployment checks._
-  - Type: `boolean`
-  - Default: _true_
-- <b id="#/properties/interactive">interactive</b>
-  - _Run deployment with or without input prompts._
-  - Type: `boolean`
-  - Default: _true_
-- <b id="#/properties/verbose">verbose</b>
-  - _Run deployment in verbose mode._
-  - Type: `boolean`
-  - Default: _false_
-- <b id="#/properties/manifestTransform">manifestTransform</b>
-  - _A JSONata expression that transforms the manifest.yml content before the deployment._
-  - Type: `string`
+### Options
+
+<!-- nx-forge:options executor=deploy -->
 
 For details on how to use the `manifestTransform` parameter, refer to the [guide on transforming the manifest](../guides/transforming-the-manifest).
 
@@ -155,27 +93,15 @@ Registers the Forge app project named `<nx-forge-app-name>` with the Forge platf
 
 _Mirrors the [register command](https://developer.atlassian.com/platform/forge/cli-reference/register/) of the Forge CLI._
 
-**_Properties_**
-
-- <b id="#/properties/outputPath">outputPath</b> `required`
-  - _The output path of the Forge app files._
-  - Type: `string`
-- <b id="#/properties/appName">appName</b> `required`
-  - _Name of the app on the Forge platform. The app name can include dashes, spaces, and underscores. Defaults to the project name_
-  - Type: `string`
-- <b id="#/properties/developerSpaceId">developerSpaceId</b>
-  - _ID of the Forge developer space this app should be part of._
-  - Type: `string`
-- <b id="#/properties/acceptTerms">acceptTerms</b>
-  - _Automatically accept terms and conditions in non-interactive mode._
-  - Type: `boolean`
-  - Default: _false_
-- <b id="#/properties/verbose">verbose</b>
-  - _Run registration in verbose mode._
-  - Type: `boolean`
-  - Default: _false_
-
-## Install
+### Options
+
+<!-- nx-forge:options executor=register -->
+
+## Install <Badge type="warning" text="Deprecated" />
+
+::: warning
+The `install` executor is deprecated in favor of the [`forge` executor](#forge).
+:::
 
 ```shell
 nx install <nx-forge-app-name>
@@ -185,42 +111,9 @@ Installs the Forge app project named `<nx-forge-app-name>` for the given site an
 
 _Mirrors the [install command](https://developer.atlassian.com/platform/forge/cli-reference/install/) of the Forge CLI._
 
-**_Properties_**
-
-- <b id="#/properties/outputPath">outputPath</b> `required`
-  - _The output path of the Forge app files._
-  - Type: `string`
-- <b id="#/properties/site">site</b> `required`
-  - _Atlassian site URL (example.atlassian.net)_
-  - Type: `string`
-- <b id="#/properties/product">product</b> `required`
-  - _Atlassian product: jira, confluence, compass, bitbucket_
-  - Type: `string`
-  - The value is restricted to the following:
-    1. _"jira"_
-    2. _"confluence"_
-    3. _"compass"_
-    4. _"bitbucket"_
-- <b id="#/properties/environment">environment</b>
-  - _Environment to install to._
-  - Type: `string`
-  - Default: _"development"_
-- <b id="#/properties/upgrade">upgrade</b>
-  - _Upgrade an existing installation._
-  - Type: `boolean`
-  - Default: _false_
-- <b id="#/properties/confirmScopes">confirmScopes</b>
-  - _Skip confirmation of scopes for the app before installing or upgrading the app._
-  - Type: `boolean`
-  - Default: _false_
-- <b id="#/properties/interactive">interactive</b>
-  - _Run installation with or without input prompts._
-  - Type: `boolean`
-  - Default: _true_
-- <b id="#/properties/verbose">verbose</b>
-  - _Run installation in verbose mode._
-  - Type: `boolean`
-  - Default: _false_
+### Options
+
+<!-- nx-forge:options executor=install -->
 
 
 ## Tunnel <Badge type="warning" text="Experimental" />
@@ -233,20 +126,6 @@ Starts the `tunnel` target for all Custom UI projects defined in the `manifest.y
 
 _Mirrors the [tunnel command](https://developer.atlassian.com/platform/forge/cli-reference/tunnel/) of the Forge CLI._
 
-**_Properties_**
-
-- <b id="#/properties/outputPath">outputPath</b> `required`
-  - _The output path of the Forge app files._
-  - Type: `string`
-- <b id="#/properties/debug">debug</b>
-  - _Run Forge tunnel in debug mode._
-  - Type: `boolean`
-  - Default: _false_
-- <b id="#/properties/verbose">verbose</b>
-  - _Run Forge tunnel in verbose mode._
-  - Type: `boolean`
-  - Default: _false_
-- <b id="#/properties/preTunnelTimeout">preTunnelTimeout</b>
-  - _Max milliseconds to wait for tunnel preparation tasks._
-  - Type: `number`
-  - Default: `5000`
+### Options
+
+<!-- nx-forge:options executor=tunnel -->

docs/reference/generators.md

@@ -4,8 +4,6 @@ Documents [the generators](https://nx.dev/features/generate-code) provided by th
 
 Append `--help` or `-h` for any of the plugin generators to explore all available options.
 
-[//]: # (Used https://brianwendt.github.io/json-schema-md-doc/ to generate the properties markdown from schema.json files)
-
 ## Application
 
 ```shell
@@ -14,57 +12,6 @@ nx generate @toolsplus/nx-forge:app apps/<nx-forge-app-name>
 
 Generates a blank Forge app project named `<nx-forge-app-name>`. In almost all cases, you probably want to run [the Forge app registration task](executors#register) immediately after this generator to register the app with the Forge platform.
 
-**_Properties_**
+### Options
 
-- <b id="#NxForgeApplicationGenerator/properties/directory">directory</b> `required`
-  - _Directory of the new application_
-  - Type: `string`
-- <b id="#NxForgeApplicationGenerator/properties/name">name</b>
-  - _Name of the application._
-  - Type: `string`
-  - The value must match this pattern: `^[a-zA-Z][^:]*$`
-- <b id="#NxForgeApplicationGenerator/properties/bundler">bundler</b>
-  - _Bundler which is used to package the application_
-  - Type: `string`
-  - The value is restricted to the following:
-    1. _"esbuild"_
-    2. _"webpack"_
-  - Default: _"webpack"_
-- <b id="#NxForgeApplicationGenerator/properties/skipFormat">skipFormat</b>
-  - _Skip formatting files._
-  - Type: `boolean`
-  - Default: _false_
-- <b id="#NxForgeApplicationGenerator/properties/linter">linter</b>
-  - _Tool to use for running lint checks._
-  - Type: `string`
-  - The value is restricted to the following:
-    1. _"eslint"_
-    2. _"none"_
-  - Default: _"eslint"_
-- <b id="#NxForgeApplicationGenerator/properties/unitTestRunner">unitTestRunner</b>
-  - _Test runner to use for unit tests._
-  - Type: `string`
-  - The value is restricted to the following:
-    1. _"jest"_
-    2. _"none"_
-  - Default: _"jest"_
-- <b id="#NxForgeApplicationGenerator/properties/tags">tags</b>
-  - _Add tags to the project (used for linting)_
-  - Type: `string`
-- <b id="#NxForgeApplicationGenerator/properties/swcJest">swcJest</b>
-  - _Use `@swc/jest` instead `ts-jest` for faster test compilation._
-  - Type: `boolean`
-  - Default: _false_
-- <b id="#NxForgeApplicationGenerator/properties/babelJest">babelJest</b> <Badge type="warning" text="Deprecated" />
-  - _Use `babel` instead of `ts-jest`._
-  - Type: `boolean`
-  - Default: _false_
-  - _Deprecated: Use `--swcJest` instead_
-- <b id="#NxForgeApplicationGenerator/properties/js">js</b>
-  - _Generate JavaScript files rather than TypeScript files._
-  - Type: `boolean`
-  - Default: _false_
-- <b id="#NxForgeApplicationGenerator/properties/setParserOptionsProject">setParserOptionsProject</b>
-  - _Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons._
-  - Type: `boolean`
-  - Default: _false_
+<!-- nx-forge:options generator=application -->