Add custom logging documentation to advanced tutorial

docs/tutorial-advanced/custom-logging.md

@@ -0,0 +1,71 @@
+# Custom Logging
+
+psake routes all internal messages through configurable output handlers. You can override these handlers in your [`psake-config.ps1`](./psake-config.md) file to integrate with your own logging system.
+
+## Default Handlers
+
+psake ships with handlers for six message types:
+
+| Type | Default Behavior |
+|------|-----------------|
+| `heading` | Cyan colored output |
+| `default` | `Write-Output` |
+| `debug` | `Write-Debug` |
+| `warning` | Yellow colored output |
+| `error` | Red colored output |
+| `success` | Green colored output |
+
+Unknown message types fall back to the `default` handler.
+
+## Override Specific Message Types
+
+To customize how individual message types are handled, override entries in `$config.outputHandlers` in your `psake-config.ps1`:
+
+```powershell
+# psake-config.ps1
+
+# Send warnings to a log file instead of the console
+$config.outputHandlers.warning = {
+    Param($output)
+    Add-Content -Path "build-warnings.log" -Value $output
+}
+
+# Suppress debug messages entirely
+$config.outputHandlers.debug = {
+    Param($output)
+    # do nothing
+}
+```
+
+Each handler receives a single `$output` parameter containing the message string.
+
+## Override All Logging
+
+To replace the entire routing logic, override `$config.outputHandler` (singular). This script block receives both the message and its type, giving you full control:
+
+```powershell
+# psake-config.ps1
+
+$config.outputHandler = {
+    Param($output, $type)
+    # Route everything through your custom logger
+    Write-MyBuildLog -Message $output -Level $type
+}
+```
+
+When you override `outputHandler`, the individual `outputHandlers` entries are bypassed entirely.
+
+## Example: Log to a File
+
+```powershell
+# psake-config.ps1
+
+$config.outputHandler = {
+    Param($output, $type)
+    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
+    $line = "[$timestamp] [$type] $output"
+    Add-Content -Path "build.log" -Value $line
+    # Still write to console
+    Write-Host $line
+}
+```

docs/tutorial-advanced/logging-errors.md

@@ -1,12 +1,10 @@
 # Logging Errors
 
-The latest version of **psake** no longer provides a way to log errors to a
-file. Most builds are executed by a continuous integration server which already
-logs all console output so it's redundant to provide that same functionality in
-psake. If an error does occur detailed error information is emitted to the
-console so that it will get saved by whatever CI server is running psake.
+By default, psake does not log errors to a file. When an error occurs, detailed error information is emitted to the console. Most CI servers capture all console output, so this is usually sufficient.
 
-Here is an example of an error from a psake build script:
+If you need to route errors to a file or custom logger, you can override psake's error output handler. See [Custom Logging](./custom-logging.md) for details.
+
+Here is an example of the default error output from a psake build script:
 
 ```powershell
 ----------------------------------------------------------------------

docs/tutorial-advanced/psake-config.md

@@ -0,0 +1,89 @@
+# psake Configuration File
+
+psake loads a `psake-config.ps1` file at the start of every build to set default values for your build environment. You can use this file to change psake's default build file name, framework version, task name format, output handlers, and more.
+
+:::note
+Most projects do not need a `psake-config.ps1` file. psake's built-in defaults work well for the majority of use cases. Only create one if you need to change a specific default.
+:::
+
+## How psake Finds the Config File
+
+psake searches for `psake-config.ps1` in two locations, in order:
+
+1. **The build script's directory** — the folder containing the build file passed to `Invoke-psake`
+2. **The psake module directory** — the folder where `psake.psm1` is installed
+
+The first file found wins. If neither location contains a config file, psake uses its built-in defaults.
+
+This means you can place a `psake-config.ps1` next to your `psakefile.ps1` to customize settings per-project, or place one alongside the psake module for machine-wide defaults.
+
+## Partial Overrides
+
+Your config file does not need to set every property. psake initializes all properties to their defaults before loading your config file, so any property you omit keeps its default value. You only need to set the properties you want to change.
+
+## Configuration Properties
+
+Inside `psake-config.ps1`, you set properties on the `$config` variable. Here is every available property:
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `buildFileName` | `string` | `"psakefile.ps1"` | Default build file name when none is specified |
+| `legacyBuildFileName` | `string` | `"default.ps1"` | Fallback build file name (legacy support) |
+| `framework` | `string` | `"4.0"` | .NET Framework version to target |
+| `taskNameFormat` | `string` or `scriptblock` | `"Executing {0}"` | Format string or scriptblock for task name display |
+| `verboseError` | `bool` | `$false` | Show detailed error information |
+| `coloredOutput` | `bool` | `$true` | Enable colored console output |
+| `modules` | `string[]` | `$null` | Module paths to auto-load before build execution |
+| `moduleScope` | `string` | — | Scope for loaded modules |
+| `outputHandler` | `scriptblock` | *(routes to outputHandlers)* | Master handler that receives all output |
+| `outputHandlers` | `hashtable` | *(see below)* | Per-type output handlers |
+
+## Minimal Example
+
+```powershell title="psake-config.ps1"
+# Use a different default build file name
+$config.buildFileName = "build.ps1"
+
+# Target .NET 4.8
+$config.framework = "4.8"
+
+# Show detailed errors
+$config.verboseError = $true
+```
+
+## Task Name Formatting
+
+`taskNameFormat` accepts either a format string or a scriptblock:
+
+```powershell title="psake-config.ps1"
+# Format string — {0} is replaced with the task name
+$config.taskNameFormat = "Executing {0}"
+
+# Scriptblock — receives the task name as a parameter
+$config.taskNameFormat = {
+    param($taskName)
+    "Executing $taskName at $(Get-Date)"
+}
+```
+
+## Auto-Loading Modules
+
+Use `$config.modules` to load PowerShell modules before any tasks run:
+
+```powershell title="psake-config.ps1"
+# Load all modules from a folder
+$config.modules = @(".\modules\*.psm1")
+
+# Load specific modules
+$config.modules = @(".\modules\*.psm1", ".\my_module.psm1")
+```
+
+## Output Handlers
+
+psake routes all internal messages through configurable output handlers. For a full guide on customizing logging, see [Custom Logging](./custom-logging.md).
+
+## See Also
+
+- [Custom Logging](./custom-logging.md) — Override psake's output handlers
+- [Configuration Reference](../reference/configuration-reference) — Full reference for `Invoke-psake` parameters and build script settings
+- [Structure of a psake Build Script](./structure-of-a-psake-build-script.md) — How build scripts are organized

sidebars.ts

@@ -41,6 +41,8 @@ const sidebars: SidebarsConfig = {
         'tutorial-advanced/access-functions-in-another-file',
         'tutorial-advanced/build-script-resilience',
         'tutorial-advanced/debug-script',
+        'tutorial-advanced/custom-logging',
+        'tutorial-advanced/psake-config',
         'tutorial-advanced/logging-errors',
         'tutorial-advanced/outputs-and-artifacts',
         'tutorial-advanced/print-psake-task-name',