docs: Document concurrentRunners configuration option

docs/get-started/config/contexts/index.md

@@ -1,7 +1,7 @@
 ---
 title: Contexts
 layout: default
-nav_order: 1
+nav_order: 2
 parent: Configuration
 description: Define the contexts (platform and browser combinations) where tests should run.
 ---

docs/get-started/config/index.md

@@ -0,0 +1,123 @@
+---
+title: Configuration
+layout: default
+nav_order: 1
+description: Configure Doc Detective for your testing needs with options for parallel execution, file types, and more.
+---
+
+# Configuration
+
+Doc Detective provides extensive configuration options to customize how tests are executed. You can configure Doc Detective using a `.doc-detective.json` file in your project root, or by passing configuration options directly via the command line.
+
+## Configuration File
+
+Create a `.doc-detective.json` file in your project root to define your configuration:
+
+```json
+{
+  "input": "docs/",
+  "output": "test-results/",
+  "logLevel": "info",
+  "concurrentRunners": true,
+  "recursive": true
+}
+```
+
+## Key Configuration Options
+
+### Parallel Execution
+
+Control how many tests run simultaneously using the `concurrentRunners` option:
+
+- **`concurrentRunners: true`** - Automatically detects your CPU count and uses up to 4 concurrent runners
+- **`concurrentRunners: 8`** - Uses exactly 8 concurrent runners (no cap on explicit values)
+- **`concurrentRunners: 1`** - Runs tests sequentially (default)
+
+```json
+{
+  "concurrentRunners": true
+}
+```
+
+**Examples:**
+- On a 2-core system: `concurrentRunners: true` → 2 runners
+- On an 8-core system: `concurrentRunners: true` → 4 runners (capped)
+- On a 16-core system: `concurrentRunners: true` → 4 runners (capped)
+- Explicit value: `concurrentRunners: 8` → 8 runners (no cap)
+
+### Input and Output
+
+- **`input`** - Path(s) to test specifications and documentation files
+- **`output`** - Directory for test results and generated files
+- **`recursive`** - Whether to search directories recursively (default: `true`)
+
+```json
+{
+  "input": ["tests/", "docs/"],
+  "output": "test-results/",
+  "recursive": true
+}
+```
+
+### Logging
+
+Control the amount of detail in test output:
+
+```json
+{
+  "logLevel": "info"
+}
+```
+
+Available levels: `silent`, `error`, `warning`, `info`, `debug`
+
+### Environment Variables
+
+Load environment variables from a `.env` file:
+
+```json
+{
+  "loadVariables": ".env"
+}
+```
+
+### File Types
+
+Configure which file types Doc Detective should process:
+
+```json
+{
+  "fileTypes": ["markdown", "asciidoc", "html"]
+}
+```
+
+## Complete Example
+
+```json
+{
+  "input": "docs/",
+  "output": "test-results/",
+  "recursive": true,
+  "concurrentRunners": true,
+  "logLevel": "info",
+  "loadVariables": ".env",
+  "origin": "https://example.com",
+  "fileTypes": ["markdown"],
+  "runOn": [
+    {
+      "platforms": ["windows", "mac", "linux"],
+      "browsers": "chrome"
+    }
+  ]
+}
+```
+
+## Command Line Overrides
+
+You can override configuration file settings using command line arguments:
+
+```bash
+npx doc-detective --input tests/ --config custom-config.json
+```
+
+For a complete list of configuration options, see the [config schema reference](/docs/references/schemas/config).

docs/references/schemas/config.md

@@ -13,6 +13,7 @@ input | one of:<br/>- string<br/>- array of string | Optional. Path(s) to test s
 output | string | Optional. Path of the directory in which to store the output of Doc Detective commands. If a file path is specified, Doc Detective attempts to honor the file name specified, but file path behavior is controlled by the configured reporters. | `.`
 recursive | boolean | Optional. If `true` searches `input`, `setup`, and `cleanup` paths recursively for test specifications and source files. | `true`
 relativePathBase | string | Optional. Whether paths should be interpreted as relative to the current working directory (`cwd`) or to the file in which they're specified (`file`).<br/><br/>Accepted values: `cwd`, `file` | `file`
+concurrentRunners | one of:<br/>- boolean<br/>- number | Optional. Number of concurrent test runners to use for parallel execution. If set to `true`, automatically detects CPU count and caps at 4 runners. If set to a number, uses that exact value with no cap. | `1`
 loadVariables | string | Optional. Load environment variables from the specified `.env` file. | 
 origin | string | Optional. Default protocol and domain to use for relative URLs. | 
 beforeAny | one of:<br/>- string<br/>- array of string | Optional. Path(s) to test specifications to perform before those specified by `input`. Useful for setting up testing environments. | 
@@ -43,6 +44,22 @@ environment | object([Environment details](/docs/references/schemas/Environment%
 }
 ```
 
+```json
+{
+  "input": "tests/",
+  "concurrentRunners": true,
+  "logLevel": "info"
+}
+```
+
+```json
+{
+  "input": "tests/",
+  "concurrentRunners": 8,
+  "logLevel": "debug"
+}
+```
+
 ```json
 {
   "fileTypes": [