Remove outdated Configuration API and Extensibility Points reference articles. Add new "How-To" guides on escaping markup and writing exceptions, along with accompanying code examples. Adjust navigation order for improved usability.

Author: phil-scott-78

Spectre.Docs.Examples/SpectreConsole/HowTo/EscapingMarkupHowTo.cs

@@ -0,0 +1,64 @@
+using Spectre.Console;
+
+namespace Spectre.Docs.Examples.SpectreConsole.HowTo;
+
+internal static class EscapingMarkupHowTo
+{
+    /// <summary>
+    /// Use Markup.Escape() to safely display user-provided strings.
+    /// </summary>
+    public static void EscapeUserInput()
+    {
+        // User input that contains brackets
+        var userInput = "Use [brackets] for indexing";
+        var escaped = Markup.Escape(userInput);
+
+        // Safe to use in markup string
+        AnsiConsole.MarkupLine($"[blue]Input:[/] {escaped}");
+
+        // Common patterns that need escaping
+        var configKey = "settings[debug]";
+        var arrayRef = "items[0]";
+
+        AnsiConsole.MarkupLine($"[green]Config:[/] {Markup.Escape(configKey)}");
+        AnsiConsole.MarkupLine($"[green]Array:[/] {Markup.Escape(arrayRef)}");
+    }
+
+    /// <summary>
+    /// Use MarkupLineInterpolated() to automatically escape interpolated values.
+    /// </summary>
+    public static void UseSafeInterpolation()
+    {
+        // Values that contain brackets are escaped automatically
+        var fileName = "config[backup].json";
+        var userName = "admin[test]";
+        var version = "v2.0[beta]";
+
+        // No manual escaping needed
+        AnsiConsole.MarkupLineInterpolated($"[blue]File:[/] {fileName}");
+        AnsiConsole.MarkupLineInterpolated($"[green]User:[/] {userName}");
+        AnsiConsole.MarkupLineInterpolated($"[yellow]Version:[/] {version}");
+
+        // Works with multiple interpolated values
+        AnsiConsole.MarkupLineInterpolated(
+            $"[dim]Loaded[/] {fileName} [dim]for user[/] {userName}");
+    }
+
+
+    /// <summary>
+    /// Use Markup.Remove() to strip formatting for logging or file output.
+    /// </summary>
+    public static void StripMarkupForLogging()
+    {
+        var styled = "[bold red]Error:[/] Connection to [blue]database[/] failed";
+
+        // Remove all markup tags for plain text
+        var plain = Markup.Remove(styled);
+
+        AnsiConsole.MarkupLine("[dim]Styled output:[/]");
+        AnsiConsole.MarkupLine(styled);
+
+        AnsiConsole.MarkupLine("[dim]Plain text for logs:[/]");
+        AnsiConsole.WriteLine(plain);
+    }
+}

Spectre.Docs.Examples/SpectreConsole/HowTo/WritingExceptionsHowTo.cs

@@ -0,0 +1,99 @@
+using Spectre.Console;
+
+namespace Spectre.Docs.Examples.SpectreConsole.HowTo;
+
+internal static class WritingExceptionsHowTo
+{
+    /// <summary>
+    /// Write an exception to the console with default formatting.
+    /// </summary>
+    public static void WriteBasicException()
+    {
+        try
+        {
+            ProcessUserData(null!);
+        }
+        catch (Exception ex)
+        {
+            AnsiConsole.WriteException(ex);
+        }
+    }
+
+    /// <summary>
+    /// Shorten file paths for cleaner stack traces.
+    /// </summary>
+    public static void ShortenFilePaths()
+    {
+        try
+        {
+            ProcessUserData(null!);
+        }
+        catch (Exception ex)
+        {
+            AnsiConsole.WriteException(ex, ExceptionFormats.ShortenPaths);
+        }
+    }
+
+    /// <summary>
+    /// Shorten everything and add clickable links to source files.
+    /// </summary>
+    public static void ShortenEverythingWithLinks()
+    {
+        try
+        {
+            ProcessUserData(null!);
+        }
+        catch (Exception ex)
+        {
+            AnsiConsole.WriteException(ex,
+                ExceptionFormats.ShortenEverything | ExceptionFormats.ShowLinks);
+        }
+    }
+
+    /// <summary>
+    /// Customize exception colors using ExceptionSettings.
+    /// </summary>
+    public static void CustomizeColors()
+    {
+        try
+        {
+            ProcessUserData(null!);
+        }
+        catch (Exception ex)
+        {
+            AnsiConsole.WriteException(ex, new ExceptionSettings
+            {
+                Format = ExceptionFormats.ShortenEverything,
+                Style = new ExceptionStyle
+                {
+                    Exception = new Style(Color.Grey),
+                    Message = new Style(Color.White),
+                    Method = new Style(Color.Red),
+                    Path = new Style(Color.Yellow),
+                    LineNumber = new Style(Color.Blue),
+                }
+            });
+        }
+    }
+
+    // Helper to generate a realistic nested exception
+    private static void ProcessUserData(string data)
+    {
+        try
+        {
+            ValidateInput(data);
+        }
+        catch (Exception ex)
+        {
+            throw new InvalidOperationException("Failed to process user data", ex);
+        }
+    }
+
+    private static void ValidateInput(string data)
+    {
+        if (data == null)
+        {
+            throw new ArgumentNullException(nameof(data), "Input cannot be null");
+        }
+    }
+}

Spectre.Docs/Content/cli/how--to/async-commands-and-cancellation.md

@@ -2,7 +2,7 @@
 title: "Async Commands and Cancellation"
 description: "How to create asynchronous commands and handle cancellation in Spectre.Console.Cli"
 uid: "cli-async-commands"
-order: 2025
+order: 2080
 ---
 
 When your command performs I/O-bound operations like HTTP requests, database queries, or file operations, use `AsyncCommand<TSettings>` instead of `Command<TSettings>`. This lets you use `async/await` and enables graceful shutdown when users press Ctrl+C.
@@ -26,4 +26,4 @@ T:Spectre.Docs.Cli.Examples.DemoApps.AsyncCommandsAndCancellation.FetchCommand
 ## See Also
 
 - [Handling Errors and Exit Codes](/cli/how--to/handling-errors-and-exit-codes) - Custom exception handling
-- [Dependency Injection in CLI Commands](/cli/how--to/dependency-injection-in-cli-commands) - Inject services like HttpClient
+- [Dependency Injection in CLI Apps](/cli/tutorials/dependency-injection-in-cli-apps) - Inject services like HttpClient

Spectre.Docs/Content/cli/how--to/configuring-commandapp-and-commands.md

@@ -2,7 +2,7 @@
 title: "Configuring CommandApp and Commands"
 description: "How to register commands with the CommandApp and configure global settings"
 uid: "cli-app-configuration"
-order: 2030
+order: 2090
 ---
 
 When building a CLI with multiple commands, use `CommandApp.Configure` to register commands, set up aliases, and customize how your application appears in help output.

Spectre.Docs/Content/cli/how--to/customizing-help-text-and-usage.md

@@ -2,7 +2,7 @@
 title: "Customizing Help Text and Usage"
 description: "How to tailor the automatically generated help output of Spectre.Console.Cli"
 uid: "cli-help-customization"
-order: 2040
+order: 2100
 ---
 
 Spectre.Console.Cli generates help text automatically from your commands and settings. When the defaults don't match your needs—whether for branding, accessibility, or clarity—you can customize the application name, add usage examples, adjust styling, or disable styling entirely for plain text output.
@@ -60,5 +60,4 @@ The built-in `HelpProvider` class can also be extended if you only need to overr
 
 ## See Also
 
-- [Hiding Commands and Options](/cli/how--to/hiding-commands-and-options) - Keep commands functional but hidden from help
-- [CommandApp Configuration](/cli/reference/commandapp-reference) - Full configuration options
+- [Hiding Commands and Options](/cli/how--to/hiding-commands-and-options) - Keep commands functional but hidden from help

Spectre.Docs/Content/cli/how--to/defining-commands-and-arguments.md

@@ -2,7 +2,7 @@
 title: "Defining Commands and Arguments"
 description: "How to declare command-line parameters (arguments and options) using Spectre.Console.Cli's attributes and settings classes"
 uid: "cli-commands-arguments"
-order: 2010
+order: 2050
 ---
 
 Every command in Spectre.Console.Cli receives its input through a `CommandSettings` class. Decorate properties with `[CommandArgument]` for positional parameters and `[CommandOption]` for named flags and options. The framework handles parsing, validation, and help generation automatically.

Spectre.Docs/Content/cli/how--to/handling-errors-and-exit-codes.md

@@ -2,7 +2,7 @@
 title: "Handling Errors and Exit Codes"
 description: "How Spectre.Console.Cli deals with exceptions and how to customize error handling"
 uid: "cli-error-handling"
-order: 2050
+order: 2070
 ---
 
 By default, Spectre.Console.Cli catches exceptions, displays a user-friendly message, and returns exit code `-1`. When you need more control—different exit codes for different error types, custom formatting, or integration with logging—you have two options: `SetExceptionHandler` for centralized handling within the framework, or `PropagateExceptions` for full manual control with try-catch blocks.
@@ -32,5 +32,4 @@ This approach requires more code but gives you complete flexibility. You can cat
 
 ## See Also
 
-- [Async Commands and Cancellation](/cli/how--to/async-commands-and-cancellation) - Handle cancellation gracefully
-- [CommandApp Configuration](/cli/reference/commandapp-reference) - Full configuration options
+- [Async Commands and Cancellation](/cli/how--to/async-commands-and-cancellation) - Handle cancellation gracefully

Spectre.Docs/Content/cli/how--to/hiding-commands-and-options.md

@@ -2,7 +2,7 @@
 title: "Hiding Commands and Options"
 description: "How to hide commands and options from help output while keeping them functional"
 uid: "cli-hidden-commands"
-order: 2045
+order: 2130
 ---
 
 Sometimes you need commands or options that work but shouldn't appear in help output—internal debugging tools, deprecated features you're phasing out, or advanced options that would overwhelm typical users. Hidden items remain fully functional; users who know about them can still use them.

Spectre.Docs/Content/cli/how--to/intercepting-command-execution.md

@@ -2,7 +2,7 @@
 title: "Intercepting Command Execution"
 description: "How to use command interceptors to run logic before or after any command executes"
 uid: "cli-command-interception"
-order: 2080
+order: 2140
 ---
 
 When you need cross-cutting concerns like logging, timing, or authentication across all commands without duplicating code, implement a command interceptor. The interceptor runs before and after every command, keeping individual commands focused on their core logic.
@@ -35,5 +35,5 @@ The `InterceptResult` method receives the exit code by reference (`ref int resul
 
 ## See Also
 
-- [Dependency Injection in CLI Commands](/cli/how--to/dependency-injection-in-cli-commands) - Inject services into interceptors
+- [Dependency Injection in CLI Apps](/cli/tutorials/dependency-injection-in-cli-apps) - Inject services into interceptors
 - [Handling Errors and Exit Codes](/cli/how--to/handling-errors-and-exit-codes) - Custom error handling

Spectre.Docs/Content/cli/how--to/making-options-required.md

@@ -2,7 +2,7 @@
 title: "Making Options Required"
 description: "How to make command-line options required instead of optional in Spectre.Console.Cli"
 uid: "cli-required-options"
-order: 2015
+order: 2060
 ---
 
 By design, options (flags like `--name` or `-n`) are optional—that's why they're called "options." However, there are cases where you want a named option that users must provide, such as specifying a target environment or API key.