Documentation updates

README.md

@@ -18,14 +18,14 @@ create a documentation site that fits your needs, hosted in any static web hosti
 - [🚀 Features](#-features)
 - [💿 Installation](#-installation)
 - [⚡ Quick Start](#-quick-start)
-  - [CLI](#cli)
-    - [Markdown](#markdown)
-    - [OpenApi](#openapi)
-    - [Changelog](#changelog)
+    - [CLI](#cli)
+        - [Markdown](#markdown)
+        - [OpenApi](#openapi)
+        - [Changelog](#changelog)
 - [▶️ Available Commands](#️-available-commands)
-  - [Markdown](#markdown-1)
-  - [OpenApi](#openapi-1)
-  - [Changelog](#changelog-1)
+    - [Markdown](#markdown-1)
+    - [OpenApi](#openapi-1)
+    - [Changelog](#changelog-1)
 - [🔬 Defining a configuration file](#-defining-a-configuration-file)
 - [🌐 Translation](#-translation)
 - [⤵︎ Importing to your project](#︎-importing-to-your-project)
@@ -140,9 +140,8 @@ apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir f
 
 | Flag                              | Alias | Description                                                                                                                                                                                              | Default          | Required |
 |-----------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------|
-| `--sourceDir`                     | `-s`  | The directory where the source files are located.                                                                                                                                                        | N/A              | *        |
-| `--sourceDirs`                    | N/A   | Multiple source directories (space-separated). Cannot be used with `--sourceDir` or `--useSfdxProjectJson`.                                                                                              | N/A              | *        |
-| `--useSfdxProjectJson`            | N/A   | Read source directories from `sfdx-project.json` packageDirectories. Cannot be used with `--sourceDir` or `--sourceDirs`.                                                                                | `false`          | *        |
+| `--sourceDir`                     | `-s`  | The directory or directories where the source files are located.                                                                                                                                         | N/A              | *        |
+| `--useSfdxProjectJson`            | N/A   | Read source directories from `sfdx-project.json` packageDirectories. Cannot be used with `--sourceDir`.                                                                                                  | `false`          | *        |
 | `--sfdxProjectPath`               | N/A   | Path to directory containing `sfdx-project.json` (defaults to current directory). Only used with `--useSfdxProjectJson`.                                                                                 | `process.cwd()`  | No       |
 | `--targetDir`                     | `-t`  | The directory where the generated files will be placed.                                                                                                                                                  | `docs`           | No       |
 | `--scope`                         | `-p`  | A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible.                                                                                      | `[global]`       | No       |
@@ -158,8 +157,7 @@ apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir f
 | `--includeInlineHelpTextMetadata` | N/A   | Whether to include the inline help text for fields in the generated files.                                                                                                                               | `false`          | No       |
 
 > **Note:** The `*` in the Required column indicates that **one** of the source directory options must be specified:
-> - `--sourceDir` (single directory)
-> - `--sourceDirs` (multiple directories)
+> - `--sourceDir` (single directory or array of directories)
 > - `--useSfdxProjectJson` (read from sfdx-project.json)
 >
 > These options are mutually exclusive - you cannot use more than one at the same time.
@@ -396,61 +394,6 @@ There are hooks for both Markdown and Changelog operations (but not for OpenApi)
 
 #### Markdown Hooks
 
-##### **macros**
-
-Allows defining custom macros that can be used in the documentation.
-
-Macros are reusable pieces of text that can be injected into the documentation,
-allowing you to define common pieces of text that you can use across multiple files.
-
-A common use case is injecting copyright or license information, without
-having to copy-paste the same text across multiple classes, polluting your
-source code.
-
-A macro can be defined in your documentation using the `{{macro_name}}` syntax.
-In the configuration file, you can then define the macro behavior as a key-value pair, where the key is the name of the
-macro, and the value is a function that returns the text to inject in place of the macro.
-
-**Type**
-
-```typescript
-type MacroSourceMetadata = {
-  type: 'apex' | 'customobject' | 'customfield' | 'custommetadata' | 'trigger';
-  name: string;
-  filePath: string;
-};
-
-type MacroFunction = (metadata: MacroSourceMetadata) => string;
-```
-
-Notice that the `metadata` object contains information about the source of the file for which the macro is being
-injected. This allows you to optionally
-return different text based on the source of the file.
-
-Example: Injecting a copyright notice
-
-```typescript
-//...
-macros: {
-  copyright: () => {
-    return `@copyright Copyright (c) ${new Date().getFullYear()} My Name`;
-  }
-}
-//...
-```
-
-And then in your source code, you can use the macro like this:
-
-```apex
-/**
- * {{copyright}}
- * @description This is a class
- */
-public class MyClass {
-    //...
-}
-```
-
 ##### **transformReferenceGuide**
 
 Allows changing the frontmatter and content of the reference guide, or if creating a reference guide page altogether
@@ -563,6 +506,61 @@ export default {
 };
 ```
 
+##### **macros**
+
+Allows defining custom macros that can be used in the documentation.
+
+Macros are reusable pieces of text that can be injected into the documentation,
+allowing you to define common pieces of text that you can use across multiple files.
+
+A common use case is injecting copyright or license information, without
+having to copy-paste the same text across multiple classes, polluting your
+source code.
+
+A macro can be defined in your documentation using the `{{macro_name}}` syntax.
+In the configuration file, you can then define the macro behavior as a key-value pair, where the key is the name of the
+macro, and the value is a function that returns the text to inject in place of the macro.
+
+**Type**
+
+```typescript
+type MacroSourceMetadata = {
+  type: 'apex' | 'customobject' | 'customfield' | 'custommetadata' | 'trigger';
+  name: string;
+  filePath: string;
+};
+
+type MacroFunction = (metadata: MacroSourceMetadata) => string;
+```
+
+Notice that the `metadata` object contains information about the source of the file for which the macro is being
+injected. This allows you to optionally
+return different text based on the source of the file.
+
+Example: Injecting a copyright notice
+
+```typescript
+//...
+macros: {
+  copyright: () => {
+    return `@copyright Copyright (c) ${new Date().getFullYear()} My Name`;
+  }
+}
+//...
+```
+
+And then in your source code, you can use the macro like this:
+
+```apex
+/**
+ * {{copyright}}
+ * @description This is a class
+ */
+public class MyClass {
+    //...
+}
+```
+
 #### Changelog Hooks
 
 ##### **transformChangeLogPage**