Fix exception formatting for generic methods (#639)

The generic parameters were double escaped and would display as `[[T0,T1,TRet]]` instead of `[T0,T1,TRet]`. This is because the `builder.AppendWithStyle` method already escapes its value so the caller must not escape the passed value.

.github/workflows/ci.yaml

@@ -18,10 +18,10 @@ jobs:
     - name: Checkout
       uses: actions/checkout@master
 
-    - name: Setup dotnet
+    - name: Setup dotnet 6.0.100
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: 5.0.202
+        dotnet-version: 6.0.100
 
     - name: Setup Node.js
       uses: actions/setup-node@v2
@@ -79,16 +79,21 @@ jobs:
         with:
           dotnet-version: 3.1.402
 
-      - name: Setup dotnet 5.0.100
+      - name: Setup dotnet 5.0.301
         uses: actions/setup-dotnet@v1
         with:
-          dotnet-version: 5.0.202
+          dotnet-version: 5.0.301
+
+      - name: Setup dotnet 6.0.100
+        uses: actions/setup-dotnet@v1
+        with:
+          dotnet-version: 6.0.100
 
       - name: Integration Tests
         shell: bash
         run: |
           dotnet tool restore
-          dotnet example --all
+          dotnet example --all --skip live --skip livetable --skip prompt
 
       - name: Build
         shell: bash

.github/workflows/docs.yaml

@@ -5,6 +5,9 @@ on:
         paths:
         - 'docs/**'
         - 'src/**'
+        - 'test/**'
+        - 'examples/**'
+        - '.github/**'
 
 jobs:
 
@@ -21,10 +24,10 @@ jobs:
       with:
         fetch-depth: 0
 
-    - name: Setup dotnet
+    - name: Setup dotnet 6.0.100
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: 5.0.202
+        dotnet-version: 6.0.100
 
     - name: Setup Node.js
       uses: actions/setup-node@v2

.github/workflows/publish.yaml

@@ -6,8 +6,6 @@ on:
       - '*'
     branches:
       - main
-    paths:
-      - 'src/**'
 
 env:
   DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true
@@ -26,10 +24,10 @@ jobs:
     - name: Checkout
       uses: actions/checkout@master
 
-    - name: Setup dotnet
+    - name: Setup dotnet 6.0.100
       uses: actions/setup-dotnet@v1
       with:
-        dotnet-version: 5.0.202
+        dotnet-version: 6.0.100
 
     - name: Build
       shell: bash
@@ -69,10 +67,15 @@ jobs:
         with:
           dotnet-version: 3.1.402
 
-      - name: Setup dotnet 5.0.100
+      - name: Setup dotnet 5.0.301
         uses: actions/setup-dotnet@v1
         with:
-          dotnet-version: 5.0.202
+          dotnet-version: 5.0.301
+
+      - name: Setup dotnet 6.0.100
+        uses: actions/setup-dotnet@v1
+        with:
+          dotnet-version: 6.0.100
 
       - name: Build
         shell: bash
@@ -100,10 +103,16 @@ jobs:
         with:
           dotnet-version: 3.1.402
 
-      - name: Setup dotnet 5.0.100
+      - name: Setup dotnet 5.0.301
         uses: actions/setup-dotnet@v1
         with:
-          dotnet-version: 5.0.202
+          dotnet-version: 5.0.301
+
+      - name: Setup dotnet 6.0
+        uses: actions/setup-dotnet@v1
+        with:
+          dotnet-version: 6.0.x
+          include-prerelease: true
 
       - name: Publish
         shell: bash

build.cake

@@ -4,10 +4,41 @@ var configuration = Argument("configuration", "Release");
 ////////////////////////////////////////////////////////////////
 // Tasks
 
-Task("Build")
+Task("Clean")
     .Does(context =>
 {
-    DotNetCoreBuild("./src/Spectre.Console.sln", new DotNetCoreBuildSettings {
+    context.CleanDirectory("./.artifacts");
+});
+
+Task("Build")
+    .IsDependentOn("Clean")
+    .Does(context => 
+{
+    DotNetBuild("./src/Spectre.Console.sln", new DotNetBuildSettings {
+        Configuration = configuration,
+        NoIncremental = context.HasArgument("rebuild"),
+        MSBuildSettings = new DotNetCoreMSBuildSettings()
+            .TreatAllWarningsAs(MSBuildTreatAllWarningsAs.Error)
+    });
+});
+
+Task("Build-Analyzer")
+    .IsDependentOn("Build")
+    .Does(context => 
+{
+    DotNetBuild("./src/Spectre.Console.Analyzer.sln", new DotNetBuildSettings {
+        Configuration = configuration,
+        NoIncremental = context.HasArgument("rebuild"),
+        MSBuildSettings = new DotNetCoreMSBuildSettings()
+            .TreatAllWarningsAs(MSBuildTreatAllWarningsAs.Error)
+    });
+});
+
+Task("Build-Examples")
+    .IsDependentOn("Build")
+    .Does(context => 
+{
+    DotNetBuild("./examples/Examples.sln", new DotNetBuildSettings {
         Configuration = configuration,
         NoIncremental = context.HasArgument("rebuild"),
         MSBuildSettings = new DotNetCoreMSBuildSettings()
@@ -17,9 +48,17 @@ Task("Build")
 
 Task("Test")
     .IsDependentOn("Build")
+    .IsDependentOn("Build-Analyzer")
+    .IsDependentOn("Build-Examples")
     .Does(context => 
 {
-    DotNetCoreTest("./src/Spectre.Console.Tests/Spectre.Console.Tests.csproj", new DotNetCoreTestSettings {
+    DotNetTest("./test/Spectre.Console.Tests/Spectre.Console.Tests.csproj", new DotNetTestSettings {
+        Configuration = configuration,
+        NoRestore = true,
+        NoBuild = true,
+    });
+
+    DotNetTest("./test/Spectre.Console.Analyzer.Tests/Spectre.Console.Analyzer.Tests.csproj", new DotNetTestSettings {
         Configuration = configuration,
         NoRestore = true,
         NoBuild = true,
@@ -30,9 +69,16 @@ Task("Package")
     .IsDependentOn("Test")
     .Does(context => 
 {
-    context.CleanDirectory("./.artifacts");
+    context.DotNetPack($"./src/Spectre.Console.sln", new DotNetPackSettings {
+        Configuration = configuration,
+        NoRestore = true,
+        NoBuild = true,
+        OutputDirectory = "./.artifacts",
+        MSBuildSettings = new DotNetCoreMSBuildSettings()
+            .TreatAllWarningsAs(MSBuildTreatAllWarningsAs.Error)
+    });
 
-    context.DotNetCorePack($"./src/Spectre.Console.sln", new DotNetCorePackSettings {
+    context.DotNetPack($"./src/Spectre.Console.Analyzer.sln", new DotNetPackSettings {
         Configuration = configuration,
         NoRestore = true,
         NoBuild = true,
@@ -88,7 +134,7 @@ Task("Publish-NuGet")
     foreach(var file in context.GetFiles("./.artifacts/*.nupkg")) 
     {
         context.Information("Publishing {0}...", file.GetFilename().FullPath);
-        DotNetCoreNuGetPush(file.FullPath, new DotNetCoreNuGetPushSettings
+        DotNetNuGetPush(file.FullPath, new DotNetNuGetPushSettings
         {
             Source = "https://api.nuget.org/v3/index.json",
             ApiKey = apiKey,

docs/.gitignore

@@ -7,6 +7,7 @@
 [Tt]ools/
 ![Tt]ools/packages.config
 [Oo]utput/
+[Cc]ache/
 ![Ii]nput/
 nuget.exe
 *.com

docs/Docs.csproj

@@ -1,10 +1,11 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk.Web">
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <RunWorkingDirectory>$(MSBuildProjectDirectory)</RunWorkingDirectory>
     <DefaultItemExcludes>$(DefaultItemExcludes);output\**;.gitignore</DefaultItemExcludes>
+    <NoWarn>MVC1000</NoWarn>
     <MinVerSkip Condition="'$(Configuration)' == 'Debug'">true</MinVerSkip>
   </PropertyGroup>
 
@@ -31,7 +32,9 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Statiq.Web" Version="1.0.0-beta.27" />
+    <PackageReference Include="Microsoft.Playwright" Version="1.13.0-next-1" />
+
+    <PackageReference Include="Statiq.Web" Version="1.0.0-beta.34" />
     <PackageReference Include="MinVer" PrivateAssets="All" Version="2.3.1" />
   </ItemGroup>
 

docs/Program.cs

@@ -22,7 +22,7 @@ namespace Docs
                 .AddShortcode("Alert", typeof(AlertShortcode))
                 .AddShortcode("AsciiCast", typeof(AsciiCastShortcode))
                 .AddPipelines()
-                .AddProcess(ProcessTiming.Initialization, _ => new ProcessLauncher("npm", "install")
+                .AddProcess(ProcessTiming.Initialization, _ => new ProcessLauncher("npm", "install", "--audit", "false", "--fund", "false")
                 {
                     LogErrors = false
                 })

docs/global.json

@@ -0,0 +1,6 @@
+{
+  "sdk": {
+    "version": "2.2.200",
+    "rollForward": "latestMajor"
+  }
+}

docs/input/_layout.cshtml

@@ -14,11 +14,21 @@
         <link rel="icon" type="image/png" sizes="16x16" href="@Context.GetLink("/assets/favicons/favicon-16x16.png")">
 
         @{
-            string title = @Document.ContainsKey(Keys.Title) ? $"Spectre.Console - {Document.GetString(Keys.Title)}" : "Spectre.Console";
+            string title = Document.ContainsKey(Keys.Title) ? $"Spectre.Console - {Document.GetString(Keys.Title)}" : "Spectre.Console";
-            string description = @Document.ContainsKey(Constants.Description) ? Document.GetString(Constants.Description) : "Spectre.Console is a .NET Standard 2.0 library that makes it easier to create beautiful console applications";
+            string description = Document.ContainsKey(Constants.Description) ? Document.GetString(Constants.Description) : "Spectre.Console is a .NET Standard 2.0 library that makes it easier to create beautiful console applications";
+            var card = Outputs.FirstOrDefault(i => i.GetString("DocId") == Model.Id.ToString());
+            var urlBase = $"https://{Document.GetString(Keys.Host)}/";
         }
         <title>@title</title>
         <meta name="description" content="@description" />
+
+        @if(card != null){
+            <meta name="twitter:card" content="summary_large_image" />
+            <meta name="og:title" content="@title" />
+            <meta name="og:description" content="@description" />
+            <meta name="og:image" content="@(urlBase + card.Destination)" />
+        }
+
     </head>
     <body class="antialiased text-gray-600 min-h-full flex flex-col  bg-gray-50">
         <header class="flex-none text-sm font-medium bg-gradient-to-b from-gray-200 to-gray-100 ring-1 ring-gray-900 ring-opacity-5 shadow py-2 md:py-4">
@@ -66,7 +76,7 @@
                             }
                     </div>
 
-                    @foreach (IDocument document in OutputPages.GetChildrenOf(root).OnlyVisible())
+                    @foreach (IDocument document in OutputPages.GetChildrenOf(root).OrderBy(i => i.GetInt("Order")).OnlyVisible())
                     {
                         if(string.IsNullOrWhiteSpace(document.GetTitle()))
                         {
@@ -100,7 +110,10 @@
                 }
                 </nav>
                 <article class="flex-1 min-w-0">
-                    <h1 class="text-gray-800 text-4xl mb-4 font-extrabold">@(Document.GetString(Keys.Title) ?? Document.GetTitle())</h1>
+                    <header class="text-gray-800 mb-4">
+                        <h1 class="text-4xl font-extrabold">@(Document.GetString(Keys.Title) ?? Document.GetTitle())</h1>
+                        @RenderSection("subheading", required: false)
+                    </header>
                     <div class="prose max-w-none prose-sm lg:prose lg:max-w-none 2xl:prose-xl 2xl:max-w-none text-gray-700 font-light">
                         @RenderBody()
                     </div>

docs/input/_posts.cshtml

@@ -1,42 +0,0 @@
-<div>
-    @foreach (IDocument post in Document.GetChildren())
-    {
-        IDocument topicDocument = Outputs[nameof(Archives)][$"blog/topics/{post.GetString("topic")}/index.html"];
-        string excerpt = post.GetString(Statiq.Html.HtmlKeys.Excerpt);
-        <div>
-            <div class="p-3 mb-2 bg-light page-box">
-                <h5><a href="@Context.GetLink(post)">@post.GetString("Title")</a></h5>
-                <div class="small text-black-50">
-                    @post.GetDateTime("Published").ToLongDateString() in
-                    <a href="@(topicDocument.GetLink())"><span class="badge badge-light">@topicDocument.GetTitle()</span></a>
-                </div>
-                @if (!string.IsNullOrEmpty(excerpt))
-                {
-                    @Html.Raw(excerpt)
-                    <p class="small"><a href="@Context.GetLink(post)">Read more...</a></p>
-                }
-            </div>
-        </div>
-    }
-    @{
-        IDocument older = Document.GetDocument(Keys.Next);
-        IDocument newer = Document.GetDocument(Keys.Previous);
-    }
-    @if (older != null || newer != null)
-    {
-        <div class="d-flex flex-row justify-content-between">
-            <div>
-                @if (older != null)
-                {
-                    <a class="btn btn-primary" href="@Context.GetLink(older)" role="button">Older</a>
-                }
-            </div>
-            <div>
-                @if (newer != null)
-                {
-                    <a class="btn btn-primary" href="@Context.GetLink(newer)" role="button">Newer</a>
-                }
-            </div>
-        </div>
-    }
-</div>

docs/input/analyzer/rules/RULE_TEMPLATE.md

@@ -0,0 +1,38 @@
+---
+Title: SpectreXxxx
+Description: Rule title
+Category: Usage
+Severity: Hidden, Info, Warning, or Error
+Excluded: true
+---
+
+## Cause
+
+A concise-as-possible description of when this rule is violated. If there's a lot to explain, begin with "A violation of this rule occurs when..."
+
+## Reason for rule
+
+Explain why the user should care about the violation.
+
+## How to fix violations
+
+To fix a violation of this rule, [describe how to fix a violation].
+
+## Examples
+
+### Violates
+
+Example(s) of code that violates the rule.
+
+### Does not violate
+
+Example(s) of code that does not violate the rule.
+
+## How to suppress violations
+
+**If the severity of your analyzer isn't _Warning_, delete this section.**
+
+```csharp
+#pragma warning disable Spectre1000 // <Rule name>
+#pragma warning restore Spectre1000 // <Rule name>
+```

docs/input/analyzer/rules/Spectre1021.md

@@ -0,0 +1,56 @@
+---
+Title: Spectre1021
+Description: Avoid prompting for input while a current renderable is running.
+Category: Usage
+Severity: Warning
+---
+
+## Cause
+
+A violation of this rule occurs when an AnsiConsole prompt is called within the context of an executing renderable e.g. `Progress`, `Status` and `Live`. Concurrent LiveRenderable are not supported and will cause issues when running simultaneously.
+
+## Reason for rule
+
+When LiveRenderable such as `Progress`, `Status` or `Live` are running they expect to be running exclusively. They rely on ANSI sequences to draw and keep the console experience consistent. Prompts also rely on ANSI sequences for their drawing. Simultaneous running can result in corrupt output.
+
+## How to fix violations
+
+Redesign logic to allow one LiveRenderable to complete before using a prompt or prompt before starting the operation. 
+
+## Examples
+
+### Violates
+
+```csharp
+AnsiConsole.Progress().Start(ctx =>
+{
+    // code to update progress bar
+    var answer = AnsiConsole.Confirm("Continue?");
+});
+```
+
+### Does not violate
+
+```csharp
+AnsiConsole.Progress().Start(ctx =>
+{
+    // code to update progress bar
+
+    // persist state to restart progress after asking question   
+});
+
+var answer = AnsiConsole.Confirm("Continue?");
+
+AnsiConsole.Progress().Start(ctx =>
+{
+    // apply persisted state
+    // code to update progress bar
+```
+
+## How to suppress violations
+
+```csharp
+#pragma warning disable Spectre1021 // <Rule name>
+
+#pragma warning restore Spectre1021 // <Rule name>
+```

docs/input/analyzer/rules/_ViewStart.cshtml

@@ -0,0 +1,3 @@
+@{
+    Layout = @"_layout.cshtml";
+}

docs/input/analyzer/rules/_layout.cshtml

@@ -0,0 +1,10 @@
+@inherits StatiqRazorPage<IDocument>
+
+@{
+    Layout = @"/_layout.cshtml";
+}
+
+
+<p>@Document.GetString("Description")</p>
+
+@RenderBody()

docs/input/analyzer/rules/index.cshtml

@@ -0,0 +1,31 @@
+Title: Roslyn Analyzers
+Order: 20
+---
+
+<code>Spectre.Console.Analyzer</code> provides analyzers for common mistakes when using Spectre.Console. It can be installed via nuget
+
+<pre><code>nuget install Spectre.Console.Analyzer</code></pre>
+
+<h2>Supported Analyzers</h2>
+
+<table>
+    <thead>
+        <tr>
+            <th>Analyzer</th>
+            <th>Description</th>
+            <th>Category</th>
+            <th>Severity</th>
+        </tr>
+    </thead>
+    <tbody>
+    @foreach (IDocument child in OutputPages.GetChildrenOf(Document))
+    {
+        <tr>
+            <td>@Html.DocumentLink(child)</td>
+            <td>@child.GetString("Description")</td>
+            <td>@child.GetString("Category") </td>
+            <td>@child.GetString("Severity") </td>
+        </tr>
+    }
+    </tbody>
+</table>

docs/input/analyzer/rules/spectre1000.md

@@ -0,0 +1,27 @@
+---
+Title: Spectre1000
+Description: Use AnsiConsole instead of System.Console
+Category: Usage
+Severity: Warning
+---
+
+## Cause
+
+A violation of this rule occurs when `System.Console` is used for common methods exposed by Spectre.Console.
+
+## Reason for rule
+
+Methods implemented in Spectre.Console should be used over direct access to `System.Console` to allow for enhancements and
+features to be enabled.
+
+## How to fix violations
+
+To fix a violation of this rule, change from `System.Console` to `Spectre.Console.AnsiConsole`.
+
+## How to suppress violations
+
+```csharp
+#pragma warning disable Spectre1000 // Use AnsiConsole instead of System.Console
+
+#pragma warning restore Spectre1000 // Use AnsiConsole instead of System.Console
+```

docs/input/analyzer/rules/spectre1010.md

@@ -0,0 +1,63 @@
+---
+Title: Spectre1010
+Description: Favor the use of the instance of AnsiConsole over the static helper
+Category: Usage
+Severity: Info
+---
+
+## Cause
+
+A violation of this rule occurs when the static helper `AnsiConsole` is used when a field or method parameter of type
+`IAnsiConsole` is available.
+
+## Reason for rule
+
+Use of `IAnsiConsole` improves testability of the code, and also allows upstream callers the ability to customize the console
+capabilities and features. When a field variable or parameter is available it should be used to ensure the code takes advantage
+of that configuration.
+
+## How to fix violations
+
+To fix a violation of this rule, change from `AnsiConsole` to the name of the local instance.
+
+## Examples
+
+### Violates
+
+```csharp
+class Example
+{
+    private IAnsiConsole _ansiConsole;
+
+    public Example(IAnsiConsole ansiConsole) 
+    {
+        _ansiConsole = ansiConsole;
+    }
+
+    public Run()
+    {
+        AnsiConsole.WriteLine("Running...");
+    }
+
+}
+```
+
+### Does not violate
+
+```csharp
+class Example
+{
+    private IAnsiConsole _ansiConsole;
+
+    public Example(IAnsiConsole ansiConsole) 
+    {
+        _ansiConsole = ansiConsole;
+    }
+
+    public Run()
+    {
+        _ansiConsole.WriteLine("Running...");
+    }
+
+}
+```

docs/input/analyzer/rules/spectre1020.md

@@ -0,0 +1,46 @@
+---
+Title: Spectre1020
+Description: Avoid calling other live renderables while a current renderable is running.
+Category: Usage
+Severity: Warning
+---
+
+## Cause
+
+A violation of this rule occurs when a child LiveRenderable i.e. `Progress`, `Status` and `Live` are called within the context of an executing renderable. Concurrent LiveRenderable are not supported and will cause issues when running simultaneously.
+
+## Reason for rule
+
+When LiveRenderable such as `Progress`, `Status` or `Live` are running they expect to be running exclusively. They rely on ANSI sequences to draw and keep the console experience consistent. With simultaneous calls both renderables compete with the console causing concurrent writes corrupting the output.
+
+## How to fix violations
+
+Redesign logic to allow one LiveRenderable to complete before starting a second renderable. 
+
+## Examples
+
+### Violates
+
+```csharp
+AnsiConsole.Progress().Start(ctx => {
+    AnsiConsole.Status().Start("Running status too...", statusCtx => {});
+});
+```
+
+### Does not violate
+
+```csharp
+AnsiConsole.Progress().Start(ctx => {
+    // run progress and complete tasks
+});
+
+AnsiConsole.Status().Start("Running status afterwards...", statusCtx => {});
+```
+
+## How to suppress violations
+
+```csharp
+#pragma warning disable Spectre1020 // <Rule name>
+
+#pragma warning restore Spectre1020 // <Rule name>
+```

docs/input/appendix/borders.md

@@ -1,8 +1,14 @@
 Title: Borders
 Order: 2
+Description: "*Spectre.Console* makes it easy to create tables and panels with a variety of different styles of borders."
+Highlights:
+    - Rounded
+    - Square
+    - Heavy
+    - And more...
 ---
 
-There is different built-in borders you can use for tables and panels.
+There are different built-in borders you can use for tables and panels.
 
 ## Table borders
 

docs/input/appendix/colors.md

@@ -1,5 +1,9 @@
 Title: Colors
 Order: 0
+Description: "*Spectre.Console* allows easy rendering of the standard ANSI colors of your terminal, and also supports rendering up to 24-bit colors depending on the capabilities of your terminal."
+Highlights:
+    - Predefined common colors
+    - Easy syntax for inline styling
 ---
 
 The following is a list of the standard 8-bit colors supported in terminals.

docs/input/appendix/emojis.md

@@ -1,5 +1,9 @@
 Title: Emojis
 Order: 3
+Description: "For terminals that support Emojis, *Spectre.Console* supports a simple syntax for rendering emojis."
+Highlights:
+    - ":rocket: becomes 🚀"
+    - ":waning_gibbous_moon: becomes 🌖"
 ---
 
 Please note that what emojis that can be used is completely up to 

docs/input/appendix/spinners.md

@@ -1,5 +1,9 @@
 Title: Spinners
 Order: 4
+Description: "*Spectre.Console* supports over 80 different types of spinners, and allows new ones to be defined. They are used automatically with the controls"
+Highlights:
+    - Status display
+    - Progress display
 ---
 
 For all available spinners, see https://jsfiddle.net/sindresorhus/2eLtsbey/embedded/result/
@@ -21,7 +25,7 @@ AnsiConsole.Status()
 To implement your own spinner, all you have to do is 
 inherit from the `Spinner` base class.
 
-In the example below, the spinner will alterate between
+In the example below, the spinner will alternate between
 the characters `A`, `B` and `C` every 100 ms.
 
 ```csharp

docs/input/appendix/styles.md

@@ -1,5 +1,10 @@
 Title: Styles
 Order: 1
+Description: "*Spectre.Console* makes it easy to write text with different styles beyond colors. Depending on your terminal, it can make it easy to use styles such as"
+Highlights:
+    - Bold, Italic, Underline, strikethrough
+    - Dim, Invert
+    - Conceal, slowblink, rapidblink
 ---
 
 Note that what styles that can be used is defined by the system or your terminal software, and may not appear as they should.

docs/input/blog/_category.yaml

@@ -0,0 +1,15 @@
+ArchiveSources: => $"blog/posts/**/*"
+ArchiveKey: Category
+ArchiveKeyComparer: => StringComparer.OrdinalIgnoreCase.ToConvertingEqualityComparer()
+ArchiveDestination: >
+  => GetInt("Index") <= 1 ? $"blog/{NormalizedPath.OptimizeFileName(GetString("GroupKey"))}/index.html" : $"blog/{NormalizedPath.OptimizeFileName(GetString("GroupKey"))}/{GetInt("Index")}.html"
+ArchivePageSize: => 5
+ArchiveOrderKey: published
+ArchiveOrderDescending: true
+Title: Categories
+ArchiveTitle: => GetString("GroupKey")
+# we only show if we have a group key which means we are a category and not the index and also
+# if we are the first page
+Hidden: >
+  => doc.GetString("GroupKey") != null && doc.GetInt("Index") <= 1 ? false : true
+Order: 250

docs/input/blog/_directory.yaml

@@ -0,0 +1,2 @@
+Hidden: true
+Order: 1000

docs/input/blog/_index.yaml

@@ -0,0 +1,10 @@
+Title: Recent Blog Posts
+ArchiveSources: => $"blog/posts/**/*"
+ArchiveDestination: >
+  => GetInt("Index") <= 1 ? $"blog/index.html" : $"blog/{GetInt("Index")}.html"
+ArchivePageSize: => 5
+ArchiveOrderKey: Published
+ArchiveOrderDescending: true
+Hidden: >
+  =>  doc.GetInt("Index") == 1 ? false : true
+Order: 25

docs/input/blog/_nextprevious.cshtml

@@ -0,0 +1,27 @@
+
+@inherits StatiqRazorPage<IDocument>
+@model IDocument
+
+@{
+    var older = Model.GetDocument(Keys.Next);
+    var newer = Model.GetDocument(Keys.Previous);
+}
+
+
+@if (older != null || newer != null)
+{
+    <div class="flex flex-row justify-content-between">
+        <div>
+            @if (older != null)
+            {
+                <a class="py-0.5 px-1 mr-4 text-blue-900 bg-grey-50 border border-blue-200 hover:bg-grey-100 hover:text-blue-800 hover:border-blue-300 rounded transition-colors" href="@Context.GetLink(older)" role="button">Older</a>
+            }
+        </div>
+        <div>
+            @if (newer != null)
+            {
+                <a class="py-0.5 px-1 mr-4 text-blue-900 bg-grey-50 border border-blue-200 hover:bg-grey-100 hover:text-blue-800 hover:border-blue-300 rounded transition-colors" href="@Context.GetLink(newer)" role="button">Newer</a>
+            }
+        </div>
+    </div>
+}

docs/input/blog/_posts.cshtml

@@ -0,0 +1,33 @@
+@inherits StatiqRazorPage<IEnumerable<IDocument>>
+@foreach (var post in Model)
+{
+    <div>
+        <h3 class="mb-0"><a href="@Context.GetLink(post)">@post.GetString("Title")</a></h3>
+        @{
+            var author = post.GetString("Author");
+            var published = post.GetDateTime("Published");
+            var category = post.GetString("Category");
+        }
+        <div class="mt-2 font-light text-xs md:text-sm">
+            <span>Posted </span>
+            @if (published != default(DateTime)) {
+                <span>@published.ToLongDateString() </span>
+            }
+            @if (author != null) {
+                <span>by @author </span>
+            }
+            @if (category != null) {
+                var categoryUrl = @Context.GetLink($"blog/{NormalizedPath.OptimizeFileName(category)}/index.html");
+                <span>
+                    to <a class="text-blue-800 underline" href="@categoryUrl">
+                        @category
+                    </a>
+                </span>
+            }
+
+        </div>
+        <article>
+            @Html.Raw(@post.GetString("Excerpt"))
+        </article>
+    </div>
+}

docs/input/blog/category.cshtml

@@ -0,0 +1,14 @@
+@inherits StatiqRazorPage<IDocument>
+@if (Document.ContainsKey(Keys.GroupKey))
+{
+  @Html.Partial("_posts.cshtml", Document.GetChildren())
+  @Html.Partial("_nextprevious.cshtml", Document)
+}
+else
+{
+    @foreach (var tag in Document.GetChildren().OrderByDescending(x => x.GetChildren().Count()))
+    {
+        var postCount = tag.GetChildren().Count().ToString();
+        <a role="button" href="@Context.GetLink(tag)" class="badge badge-light"> @tag.GetTitle() (@postCount)</a>
+    }
+}

docs/input/blog/index.cshtml

@@ -0,0 +1,3 @@
+@inherits StatiqRazorPage<IDocument>
+@Html.Partial("_posts.cshtml", Document.GetChildren())
+@Html.Partial("_nextprevious.cshtml", Document)

docs/input/blog/posts/2021-07-11-hello-world.md

@@ -0,0 +1,9 @@
+Title: Hello, World
+Description: To help track new releases, updates and planning for Spectre.Console, we've added a new blog to the documentation.
+Published: 20210711
+Category: News
+---
+
+To help track new releases, updates and planning for Spectre.Console, we've added a new blog to the documentation.
+
+Stay tuned for upcoming information related to the 0.41 release!

docs/input/blog/posts/2021-07-19-spectre-console-0.41-released.md

@@ -0,0 +1,24 @@
+Title: Spectre.Console 0.41 released!
+Description: In this release we (mostly Phil) have been focusing on getting the new fancy Roslyn Analyzers out the door...<br /><br /><br /><br /><br />[More]
+Published: 20210719
+Category: Release Notes
+Excluded: false
+---
+
+In this release, we (mostly [Phil](https://twitter.com/philco78)) have been focusing on getting the new fancy Roslyn Analyzers out the door.
+If you want to try them out, add a reference to [Spectre.Console.Analyzer](https://www.nuget.org/packages/spectre.console.analyzer) in your project, and you should get some best practice tips in your favorite IDE!
+
+It's summer in the northern hemisphere, so it will probably be a couple of weeks until the next release.
+
+## Features
+
+* [#417 - Support cancellation in prompts](https://github.com/spectreconsole/spectre.console/issues/417)
+* [#324 - Remove AsciiTreeGuide as default tree guide](https://github.com/spectreconsole/spectre.console/issues/324)
+* [#413 - Support custom characters at the end of a TextPrompt](https://github.com/spectreconsole/spectre.console/issues/413)
+* [#447 - Alternative to the obsolete 'Select' function for selecting default items in SelectionPrompt](https://github.com/spectreconsole/spectre.console/issues/447)
+* [#460 - Default values for Ask()](https://github.com/spectreconsole/spectre.console/issues/460)
+
+## Bugs
+
+* [#480 - IAnsiConsole.Confirm extension is missing default value parameter](https://github.com/spectreconsole/spectre.console/issues/480)
+* [#442 - Allow dynamic Figlet hardblank](https://github.com/spectreconsole/spectre.console/pull/442)

docs/input/blog/posts/BLOG_TEMPLATE.md

@@ -0,0 +1,19 @@
+Title: Short title, less than 50 characters
+Description: Longer description, with optional *bold* and **italic** characters. Shouldn't be TOO long but can span multiple lines.
+Published: 20210710
+Category: Release Notes | News | or whatever
+Excluded: true
+---
+
+Intro paragraph, maybe even just the description. No need for a title that's included automatically.
+
+## Use second level headers
+
+Main title will be set with h1
+
+## Tasks
+
+1. Set title and description
+2. Set proper publish date
+3. Set proper category
+4. Remove excluded attribute.

docs/input/blog/posts/_ViewStart.cshtml

@@ -0,0 +1,3 @@
+@{
+    Layout = @$"_layout.cshtml";
+}

docs/input/blog/posts/_layout.cshtml

@@ -0,0 +1,34 @@
+@{
+    Layout = @"../../_layout.cshtml";
+}
+@inherits StatiqRazorPage<IDocument>
+
+@{
+    var author = Model.GetString("Author");
+    var published = Model.GetDateTime("Published");
+    var category = Model.GetString("Category");
+}
+
+@section subheading{
+<div class="mt-2 font-light text-xs md:text-sm">
+    <span>Posted </span>
+    @if (published != default(DateTime)) {
+        <span>@published.ToLongDateString() </span>
+    }
+    @if (author != null) {
+        <span>by @author </span>
+    }
+    @if (category != null) {
+        <span>
+            to <a class="text-blue-800 underline" href="@Context.GetLink($"blog/{NormalizedPath.OptimizeFileName(@category)}/index.html")">
+                @category
+            </a>
+        </span>
+    }
+
+</div>
+}
+
+
+
+@RenderBody()

docs/input/cli/commandApp.md

@@ -1,5 +1,6 @@
 Title: CommandApp
 Order: 2
+Description: "**CommandApp** is the entry point for a *Spectre.Console.Cli* command line application. It is used to configure the settings and commands used for execution of the application."
 ---
 
 `CommandApp` is the entry point for a `Spectre.Console.Cli` command line application. It is used to configure the settings and commands used for execution of the application. Most `Spectre.Console.Cli` applications will need to specify a custom configuration using the `Configure` method.
@@ -19,7 +20,7 @@ app.Configure(config =>
 
 ## Multiple Commands
 
-In the previous example we have a single command that is configured. For complex command line applications, it is common for them to have multiple commands (or verbs) defined. Examples of applications like this are `git`, `dotnet` and `gh`. For example, git would have an `commit` command and along with other commits like `add` or `rebase`. Each with their own settings and validation. With `Spectre.Console.Cli` we use the `Configure` method to add these commands.
+In the previous example we have a single command that is configured. For complex command line applications, it is common for them to have multiple commands (or verbs) defined. Examples of applications like this are `git`, `dotnet` and `gh`. For example, git would have a `commit` command and along with other commits like `add` or `rebase`. Each with their own settings and validation. With `Spectre.Console.Cli` we use the `Configure` method to add these commands.
 
 For example, to add three different commands to the application:
 
@@ -33,7 +34,7 @@ app.Configure(config =>
 });
 ```
 
-This configuration would allow users to run `app.exe add`, `app.exe commit`, or `app.exe rebase` and have the settings routed the appropriate command.
+This configuration would allow users to run `app.exe add`, `app.exe commit`, or `app.exe rebase` and have the settings routed to the appropriate command.
 
 For more complex command hierarchical configurations, they can also be composed via inheritance and branching. See [Composing Commands](./composing).
 
@@ -73,9 +74,12 @@ return app.Run(args);
 
 `TypeRegistrar` is a custom class that must be created by the user. This [example using `Microsoft.Extensions.DependencyInjection` as the container](https://github.com/spectreconsole/spectre.console/tree/main/examples/Cli/Injection) provides an example `TypeRegistrar` and `TypeResolver` that can be added to your application with small adjustments for your DI container.
 
+Hint: If you do write your own implementation of `TypeRegistrar` and `TypeResolver` and you have some form of unit tests in place for your project,
+there is a utility `TypeRegistrarBaseTests` available that can be used to ensure your implementations adhere to the required implementation. Simply call `TypeRegistrarBaseTests.RunAllTests()` and expect no `TypeRegistrarBaseTests.TestFailedException` to be thrown.
+
 ## Interception
 
-`CommandApp` also provides a `SetInterceptor` configuration. An interceptor is ran before all commands are executed. This is typically used for configuring logging or other infrastructure concerns.
+`CommandApp` also provides a `SetInterceptor` configuration. An interceptor is run before all commands are executed. This is typically used for configuring logging or other infrastructure concerns.
 
 All interceptors must implement `ICommandInterceptor`. Upon execution of a command, an instance of your interceptor will be called with the parsed settings. This provides an opportunity for configuring any infrastructure or modifying the settings.
 

docs/input/cli/commands.md

@@ -1,5 +1,6 @@
 Title: Creating Commands
 Order: 6
+Description: "How to create commands for *Spectre.Console.Cli*"
 ---
 
 Commands in `Spectre.Console.Cli` are defined by creating a class that inherits from either `Spectre.Console.Cli.Command<TSettings>` or `Spectre.Console.Cli.AsyncCommand<TSettings>`. `Command<TSettings>` must implement an `Execute` method that returns an int where as `AsyncCommand<TSettings>` must implement `ExecuteAsync`  returning `Task<int>`.
@@ -7,7 +8,7 @@ Commands in `Spectre.Console.Cli` are defined by creating a class that inherits
 ```csharp
 public class HelloCommand : Command<HelloCommand.Settings>
 {
-    public class Settings : LogCommandSettings
+    public class Settings : CommandSettings
     {
         [CommandArgument(0, "[Name]")]
         public string Name { get; set; }
@@ -24,7 +25,7 @@ public class HelloCommand : Command<HelloCommand.Settings>
 
 ## Configuring
 
-Commands are configured via the [`CommandApp`](commandApp)'s `Configure` method.
+Commands are configured via the [`CommandApp`](commandapp)'s `Configure` method.
 
 ```csharp
 var app = new CommandApp();
@@ -44,7 +45,7 @@ app.Configure(config =>
 
 ## Dependency Injection
 
-Constructor injection is supported on commands. See the [`CommandApp`](commandApp) documentation for further information on configuring `Spectre.Console` for your container.
+Constructor injection is supported on commands. See the [`CommandApp`](commandapp) documentation for further information on configuring `Spectre.Console` for your container.
 
 ## Validation
 

docs/input/cli/composing.md

@@ -1,6 +1,8 @@
 Title: Composing Commands
 RedirectFrom: introduction
 Order: 8
+Description: "The underlying philosophy behind *Spectre.Console.Cli* is to rely on the .NET type system to
+declare the commands, but tie everything together via composition."
 ---
 
 The underlying philosophy behind `Spectre.Console.Cli` is to rely on the .NET type system to
@@ -109,7 +111,7 @@ Now you might wonder, why do things like this? Well, for starters the different
 of the application are separated, while still having the option to share things like options,
 flags and arguments between them.
 
-This make the resulting code very clean and easy to navigate, not to mention to unit test.
+This makes the resulting code very clean and easy to navigate, not to mention to unit test.
 And most importantly at all, the type system guides me to do the right thing. I can't configure 
 commands in non-compatible ways, and if I want to add a new top-level `add-package` command 
 (or move the command completely), it's just a single line to change. This makes it easy to 

docs/input/cli/exceptions.md

@@ -0,0 +1,116 @@
+Title: Exceptions
+Order: 12
+Description: "Handling exceptions in *Spectre.Console.Cli*"
+---
+
+Exceptions happen. 
+
+`Spectre.Console.Cli` handles exceptions, writes a user friendly message to the console and sets the exitCode
+of the application to `-1`.
+While this might be enough for the needs of most applications, there are some options to customize this behavior.
+
+## Propagating exceptions
+
+The most basic way is to set `PropagateExceptions()` during configuration and handle everything.
+While this option grants the most freedom, it also requires the most work: Setting `PropagateExceptions`
+means that `Spectre.Console.Cli` effectively re-throws exceptions.
+This means that `app.Run()` should be wrapped in a `try`-`catch`-block which has to handle the exception
+(i.e. outputting something useful) and also provide the exitCode (or `return` value) for the application.
+
+```csharp
+using Spectre.Console.Cli;
+
+namespace MyApp
+{
+    public static class Program
+    {
+        public static int Main(string[] args)
+        {
+            var app = new CommandApp<FileSizeCommand>();
+
+            app.Configure(config =>
+            {
+                config.PropagateExceptions();
+            });
+
+            try
+            {
+                return app.Run(args);
+            }
+            catch (Exception ex)
+            {
+                AnsiConsole.WriteException(ex, ExceptionFormats.ShortenEverything);
+                return -99;
+            }
+        }
+    }
+}
+```
+
+## Using a custom ExceptionHandler
+
+Using the `SetErrorHandler()` during configuration it is possible to handle exceptions in a defined way.
+This method comes in two flavours: One that uses the default exitCode (or `return` value) of `-1` and one
+where the exitCode needs to be supplied.
+
+### Using `SetErrorHandler(Func<Exception, int> handler)`
+
+Using this method exceptions can be handled in a custom way. The return value of the handler is used as
+the exitCode for the application.
+
+```csharp
+using Spectre.Console.Cli;
+
+namespace MyApp
+{
+    public static class Program
+    {
+        public static int Main(string[] args)
+        {
+            var app = new CommandApp<FileSizeCommand>();
+
+            app.Configure(config =>
+            {
+                config.SetExceptionHandler(ex =>
+                {
+                    AnsiConsole.WriteException(ex, ExceptionFormats.ShortenEverything);
+                    return -99;
+                });
+            });
+
+            return app.Run(args);
+        }
+    }
+}
+```
+
+### Using `SetErrorHandler(Action<Exception> handler)`
+
+Using this method exceptions can be handled in a custom way, much the same as with the `SetErrorHandler(Func<Exception, int> handler)`.
+Using the `Action` as the handler however, it is not possible (or required) to supply a return value.
+The exitCode for the application will be `-1`.
+
+```csharp
+using Spectre.Console.Cli;
+
+namespace MyApp
+{
+    public static class Program
+    {
+        public static int Main(string[] args)
+        {
+            var app = new CommandApp<FileSizeCommand>();
+
+            app.Configure(config =>
+            {
+                config.SetExceptionHandler(ex =>
+                {
+                    AnsiConsole.WriteException(ex, ExceptionFormats.ShortenEverything);
+                });
+            });
+
+            return app.Run(args);
+        }
+    }
+}
+```

docs/input/cli/getting-started.md

@@ -1,5 +1,6 @@
 Title: Getting Started
 Order: 1
+Description: "How to get started using *Spectre.Console.Cli* to write a modern console application that follows industry conventions for command line parsing."
 ---
 
 `Spectre.Console.Cli` is a modern library for parsing command line arguments. While it's extremely
@@ -49,8 +50,7 @@ internal sealed class FileSizeCommand : Command<FileSizeCommand.Settings>
         var totalFileSize = files
             .Sum(fileInfo => fileInfo.Length);
 
-        AnsiConsole.MarkupLine(
+        AnsiConsole.MarkupLine($"Total file size for [green]{searchPattern}[/] files in [green]{searchPath}[/]: [blue]{totalFileSize:N0}[/] bytes");
-            $"Total file size for [green]{searchPattern}[/] files in [green]{searchPath}[/]: [blue]{totalFileSize:N0}[/] bytes");  $"Total file size for [green]{searchPattern}[/] files in [green]{searchPath}[/]: [blue]{totalFileSize:N0}[/] bytes");
 
         return 0;
     }
@@ -61,13 +61,13 @@ In our `Main()` method, an instance of `Spectre.Console.Cli`'s  `CommandApp` is
 
 This command will have three parameters.
 
-* The main parameter for the command will be the path. This is to be passed in as the first argument without needing to specify any command line flags. To configure that setting, use the `CommandArgument` attribute. The `[searchPath]` parameters of `CommandArgument` drives not only how the built in help display will render the help text, but the square brackets tells `Spectre.Console.Cli` that this argument is optional through convention.
+* The main parameter for the command will be the path. This is to be passed in as the first argument without needing to specify any command line flags. To configure that setting, use the `CommandArgument` attribute. The `[searchPath]` parameter of `CommandArgument` drives not only how the built in help display will render the help text, but the square brackets tells `Spectre.Console.Cli` that this argument is optional through convention.
-* The second will be specified as a parameter option. The `CommandOption` attribute is used to specify this action along with the option command line flag. In the case of `SearchPattern` both `-p` and `--path` are valid.
+* The second will be specified as a parameter option. The `CommandOption` attribute is used to specify this action along with the option command line flag. In the case of `SearchPattern` both `-p` and `--pattern` are valid.
 * The third will also be a parameter option. Here `DefaultValue` is used to indicate the default value will be `true`. For boolean parameters these will be interpreted as flags which means the user can just specify `--hidden` rather than `-hidden true`.
 
 When `args` is passed into the `CommandApp`'s run method, `Spectre.Console.Cli` will parse those arguments and populate an instance of your settings. Upon success, it will then pass those settings into an instance of the specified command's `Execute` method.
 
-With this in place, we can the following commands will all work
+With this in place, the following commands will all work
 
 ```text
 app.exe
@@ -78,6 +78,6 @@ app.exe c:\windows --hidden --pattern *.dll
 
 Much more is possible. You can have multiple commands per application, settings can be customized and extended and the default behavior of the `CommandApp` can be extended and customized.
 
-* See [CommandApp](./commandApp) for customizing how Spectre.Console.Cli builds the settings.
+* See [CommandApp](./commandapp) for customizing how Spectre.Console.Cli builds the settings.
 * See [Create Commands](./commands) for information about different command types and their configurations.
 * See [Specifying Settings](./settings) for information about defining the settings.

docs/input/cli/index.cshtml

@@ -1,5 +1,6 @@
 Title: Spectre.Console.Cli
-Order: 10
+Order: 80
+Description: "The command line interface for the *Spectre.Console* project."
 ---
 
 <p>Spectre.Console.Cli is a modern library for parsing command line arguments. While it's extremely opinionated in what it does, it tries to follow established industry conventions, and draws its inspiration from applications you use everyday.</p>

docs/input/cli/introduction.md

@@ -1,5 +1,8 @@
 Title: Introduction
 Order: 1
+Description: "*Spectre.Console.Cli* is a modern library for parsing command line arguments. While it's extremely
+opinionated in what it does, it tries to follow established industry conventions, and draws
+its inspiration from applications you use everyday."
 ---
 
 `Spectre.Console.Cli` is a modern library for parsing command line arguments. While it's extremely
@@ -114,7 +117,7 @@ Now you might wonder, why do things like this? Well, for starters the different
 of the application are separated, while still having the option to share things like options,
 flags and arguments between them.
 
-This make the resulting code very clean and easy to navigate, not to mention to unit test.
+This makes the resulting code very clean and easy to navigate, not to mention to unit test.
 And most importantly at all, the type system guides me to do the right thing. I can't configure 
 commands in non-compatible ways, and if I want to add a new top-level `add-package` command 
 (or move the command completely), it's just a single line to change. This makes it easy to 

docs/input/cli/migration.md

@@ -1,5 +1,6 @@
 Title: Migrate from Spectre.Cli
 Order: 10
+Description: "Migrating from *Spectre.Cli* to *Spectre.Console.Cli*"
 ---
 
 The functionality in `Spectre.Cli` has been moved into the `Spectre.Console`
@@ -25,7 +26,7 @@ Add the [Spectre.Console](https://www.nuget.org/packages/spectre.console) NuGet
 ## 3. Change using statements
 
 Change all using statements from `Spectre.Cli` 
-to `Spectre.Console.CLi`.
+to `Spectre.Console.Cli`.
 
 ```diff
 - using Spectre.Cli;

docs/input/cli/settings.md

@@ -1,5 +1,6 @@
 Title: Specifying Settings
 Order: 5
+Description: "How to define command line argument settings for your *Spectre.Console.Cli* Commands"
 ---
 
 Settings for `Spectre.Console.Cli` commands are defined via classes that inherit from `CommandSettings`. Attributes are used to indicate how the parser interprets the command line arguments and create a runtime instance of the settings to be used.
@@ -21,7 +22,7 @@ This setting file tells `Spectre.Console.Cli` that our command has two parameter
 
 ## CommandArgument
 
-Arguments have a position and a name. The name is not only used for generating help, but it's formatting is used to determine whether or not the argument is optional. The name must either be surrounded by square brackets (e.g. `[name]`) or angle brackets (e.g. `<name>`). Angle brackets denote required whereas square brackets denote optional. If neither are specified an exception will be thrown.
+Arguments have a position and a name. The name is not only used for generating help, but its formatting is used to determine whether or not the argument is optional. The name must either be surrounded by square brackets (e.g. `[name]`) or angle brackets (e.g. `<name>`). Angle brackets denote required whereas square brackets denote optional. If neither are specified an exception will be thrown.
 
 The position is used for scenarios where there could be more than one argument.
 

docs/input/exceptions.md

@@ -1,5 +1,9 @@
 Title: Exceptions
-Order: 3
+Order: 40
+Description: "Exceptions aren't always readable when viewed in the terminal. You can make exception a bit more readable by using the **WriteException** method."
+Highlights:
+    - Color coded output.
+    - Shorten long identifiers and paths.
 ---
 
 Exceptions aren't always readable when viewed in the terminal.  

docs/input/index.md

@@ -1,4 +1,5 @@
 Title: Welcome
+Description: Spectre.Console is a .NET Standard 2.0 library that makes it easier to create beautiful console applications.
 Order: 0
 ---
 

docs/input/live/index.cshtml

@@ -1,5 +1,6 @@
 Title: Live
-Order: 4
+Order: 50
+Description: Live displays continue to redraw their contents until an action is complete.
 ---
 
 Live displays continue to redraw their contents until an action is complete.

docs/input/live/live-display.md

@@ -1,5 +1,9 @@
 Title: Live Display
 Order: 0
+Description: "*Spectre.Console* can update arbitrary widgets in-place."
+Highlights:
+    - Update tables or graphs with new updates.
+    - Create a custom progress bar that extends the existing control.
 ---
 
 Spectre.Console can update arbitrary widgets in-place.

docs/input/live/progress.md

@@ -1,6 +1,11 @@
 Title: Progress
 Order: 5
 RedirectFrom: progress
+Description: "*Spectre.Console* can display information about long running tasks in the console using progress bars."
+Highlights:
+    - Custom styling of progress bars.
+    - Multiple predefined columns such as Throughput, Estimated Time Remaining, and more.
+    - Fallback for non-interactive consoles such as CI runners.
 ---
 
 Spectre.Console can display information about long running tasks in the console. 

docs/input/live/status.md

@@ -1,6 +1,10 @@
 Title: Status
 Order: 10
 RedirectFrom: status
+Description: "*Spectre.Console* can display information about long running tasks in the console with the Status control."
+Highlights: 
+    - Custom spinner control for running tasks.
+    - Fallback for non-interactive consoles such as CI runners.
 ---
 
 Spectre.Console can display information about long running tasks in the console. 

docs/input/markup.md

@@ -1,5 +1,10 @@
 Title: Markup
-Order: 2
+Order: 30
+Description: The Markup class allows you to output rich text to the console.
+Highlights:
+ - Easily add *color*.
+ - Add hyperlinks to for supported terminals.
+ - Emoji 🚀 parsing.
 ---
 
 The `Markup` class allows you to output rich text to the console.
@@ -10,7 +15,7 @@ Console markup uses a syntax inspired by bbcode. If you write the style (see [St
 in square brackets, e.g. `[bold red]`, that style will apply until it is closed with a `[/]`.
 
 ```csharp
-AnsiConsole.Render(new Markup("[bold yellow]Hello[/] [red]World![/]"));
+AnsiConsole.Write(new Markup("[bold yellow]Hello[/] [red]World![/]"));
 ```
 
 The `Markup` class implements `IRenderable` which means that you 
@@ -21,7 +26,7 @@ rendering of `IRenderable` also have overloads for rendering rich text.
 var table = new Table();
 table.AddColumn(new TableColumn(new Markup("[yellow]Foo[/]")));
 table.AddColumn(new TableColumn("[blue]Bar[/]"));
-AnsiConsole.Render(table);
+AnsiConsole.Write(table);
 ```
 
 ## Convenience methods
@@ -76,7 +81,7 @@ For a list of emoji, see the [Emojis](xref:emojis) appendix section.
 
 ## Colors
 
-In the examples above, all colors was referenced by their name,
+In the examples above, all colors were referenced by their name,
 but you can also use the hex or rgb representation for colors in markdown.
 
 ```csharp

docs/input/prompts/index.cshtml

@@ -1,5 +1,6 @@
 Title: Prompts
-Order: 5
+Order: 60
+Description: "*Spectre.Console* has multiple controls to assist in user input."
 ---
 
 <ul>

docs/input/prompts/multiselection.md

@@ -1,5 +1,10 @@
 Title: Multi Selection
 Order: 3
+Description: "The **MultiSelectionPrompt** can be used when you want the user to select one or many items from a provided list."
+Highlights:
+    - Display multiple items for a user to scroll and choose from.
+    - Custom page sizes.
+    - Provide groups of selectable items.
 ---
 
 The `MultiSelectionPrompt` can be used when you want the user to select
@@ -24,9 +29,8 @@ var fruits = AnsiConsole.Prompt(
         .InstructionsText(
             "[grey](Press [blue]<space>[/] to toggle a fruit, " + 
             "[green]<enter>[/] to accept)[/]")
-        .AddChoice("Apple")
         .AddChoices(new[] {
-            "Apricot", "Avocado", 
+            "Apple", "Apricot", "Avocado", 
             "Banana", "Blackcurrant", "Blueberry",
             "Cherry", "Cloudberry", "Cocunut",
         }));

docs/input/prompts/selection.md

@@ -1,5 +1,6 @@
 Title: Selection
 Order: 1
+Description: "The **SelectionPrompt** can be used when you want the user to select a single item from a provided list."
 ---
 
 The `SelectionPrompt` can be used when you want the user to select
@@ -21,9 +22,8 @@ var fruit = AnsiConsole.Prompt(
         .Title("What's your [green]favorite fruit[/]?")
         .PageSize(10)
         .MoreChoicesText("[grey](Move up and down to reveal more fruits)[/]")
-        .AddChoice("Apple")
         .AddChoices(new[] {
-            "Apricot", "Avocado", 
+            "Apple", "Apricot", "Avocado", 
             "Banana", "Blackcurrant", "Blueberry",
             "Cherry", "Cloudberry", "Cocunut",
         }));

docs/input/prompts/text.md

@@ -1,6 +1,12 @@
 Title: Text prompt
 Order: 0
 RedirectFrom: prompt
+Description: "*Spectre.Console* has multiple input functions for helping receive strongly typed input from a user."
+Highlights:
+    - Confirmation.
+    - Strongly typed input.
+    - Input restricted to specific items.
+    - Secrets such as passwords or keys.
 ---
 
 Sometimes you want to get some input from the user, and for this

docs/input/quick-start.md

@@ -1,5 +1,6 @@
 Title: Quick Start
-Order: 1
+Order: 20
+Description: Getting started with *Spectre.Console*
 ---
 
 The fastest way of getting started using Spectre.Console is

docs/input/sponsors.md

@@ -1,5 +1,6 @@
 Title: Sponsors
-Order: 0
+Order: 10
+Description: The longevity of *Spectre.Console* is thanks to the support of our sponsors.
 ---
 
 The following people are [sponsoring](https://github.com/sponsors/patriksvensson)
@@ -8,7 +9,7 @@ Spectre.Console to show their support and to ensure the longevity of the project
 * [Rodney Littles II](https://github.com/RLittlesII)
 * [Martin Björkström](https://github.com/bjorkstromm)
 * [Dave Glick](https://github.com/daveaglick)
-* [Kim Gunanrsson](https://github.com/kimgunnarsson)
+* [Kim Gunnarsson](https://github.com/kimgunnarsson)
 * [Andrew McClenaghan](https://github.com/andymac4182)
 * [C. Augusto Proiete](https://github.com/augustoproiete)
 * [Viktor Elofsson](https://github.com/vktr)

docs/input/widgets/barchart.md

@@ -1,5 +1,10 @@
 Title: Bar Chart
 Order: 20
+Description: "Use **BarChart** to render bar charts to the console."
+Highlights:
+    - Custom colors
+    - Labels
+    - Use your own data with a converter.
 ---
 
 Use `BarChart` to render bar charts to the console.
@@ -12,7 +17,7 @@ Use `BarChart` to render bar charts to the console.
 ### Basic usage
 
 ```csharp
-AnsiConsole.Render(new BarChart()
+AnsiConsole.Write(new BarChart()
     .Width(60)
     .Label("[green bold underline]Number of fruits[/]")
     .CenterLabel()
@@ -33,7 +38,7 @@ var items = new List<(string Label, double Value)>
 };
 
 // Render bar chart
-AnsiConsole.Render(new BarChart()
+AnsiConsole.Write(new BarChart()
     .Width(60)
     .Label("[green bold underline]Number of fruits[/]")
     .CenterLabel()
@@ -67,7 +72,7 @@ var items = new List<Fruit>
 };
 
 // Render bar chart
-AnsiConsole.Render(new BarChart()
+AnsiConsole.Write(new BarChart()
     .Width(60)
     .Label("[green bold underline]Number of fruits[/]")
     .CenterLabel()

docs/input/widgets/calendar.md

@@ -1,6 +1,11 @@
 Title: Calendar
 Order: 40
 RedirectFrom: calendar
+Description: "The **Calendar** is used to render a calendar to the terminal."
+Highlights:
+    - Include highlighted events.
+    - Culture aware.
+    - Custom headers.
 ---
 
 The `Calendar` is used to render a calendar to the terminal.
@@ -11,7 +16,7 @@ To render a calendar, create a `Calendar` instance with a target date.
 
 ```csharp
 var calendar = new Calendar(2020,10);
-AnsiConsole.Render(calendar);
+AnsiConsole.Write(calendar);
 ```
 
 <?# AsciiCast cast="calendar" /?>
@@ -22,8 +27,8 @@ You can set the calendar's culture to show localized weekdays.
 
 ```csharp
 var calendar = new Calendar(2020,10);
-calendar.Culture("ja-JP");
+calendar.Culture("sv-SE");
-AnsiConsole.Render(calendar);
+AnsiConsole.Write(calendar);
 ```
 
 <?# AsciiCast cast="calendar-culture" /?>
@@ -35,7 +40,7 @@ You can hide the calendar header.
 ```csharp
 var calendar = new Calendar(2020,10);
 calendar.HideHeader();
-AnsiConsole.Render(calendar);
+AnsiConsole.Write(calendar);
 ```
 
 You can set the header style of the calendar.
@@ -43,7 +48,7 @@ You can set the header style of the calendar.
 ```csharp
 var calendar = new Calendar(2020, 10);
 calendar.HeaderStyle(Style.Parse("blue bold"));
-AnsiConsole.Render(calendar);
+AnsiConsole.Write(calendar);
 ```
 
 <?# AsciiCast cast="calendar-header" /?>

docs/input/widgets/canvas-image.md

@@ -1,5 +1,6 @@
 Title: Canvas Image
 Order: 70
+Description: "Use *ImageSharp* to parse images and render them as Ascii art to the console."
 ---
 
 To add [ImageSharp](https://github.com/SixLabors/ImageSharp) superpowers to 
@@ -25,7 +26,7 @@ var image = new CanvasImage("cake.png");
 image.MaxWidth(16);
 
 // Render the image to the console
-AnsiConsole.Render(image);
+AnsiConsole.Write(image);
 ```
 
 ## Result
@@ -35,7 +36,7 @@ AnsiConsole.Render(image);
 ## Manipulating images
 
 You can take full advantage of [ImageSharp](https://github.com/SixLabors/ImageSharp)
-and manipulate images directly via it's [Processing API](https://docs.sixlabors.com/api/ImageSharp/SixLabors.ImageSharp.Processing.html).
+and manipulate images directly via its [Processing API](https://docs.sixlabors.com/api/ImageSharp/SixLabors.ImageSharp.Processing.html).
 
 ```csharp
 // Load an image
@@ -49,7 +50,7 @@ image.BilinearResampler();
 image.Mutate(ctx => ctx.Grayscale().Rotate(-45).EntropyCrop());
 
 // Render the image to the console
-AnsiConsole.Render(image);
+AnsiConsole.Write(image);
 ```
 
 ## Result

docs/input/widgets/canvas.md

@@ -1,5 +1,6 @@
 Title: Canvas
 Order: 60
+Description: "**Canvas** is a widget that allows you to render arbitrary pixels to the console."
 ---
 
 `Canvas` is a widget that allows you to render arbitrary "pixels" 
@@ -27,7 +28,7 @@ for(var i = 0; i < canvas.Width; i++)
 }
 
 // Render the canvas
-AnsiConsole.Render(canvas);
+AnsiConsole.Write(canvas);
 ```
 
 ## Result

docs/input/widgets/figlet.md

@@ -1,6 +1,7 @@
 Title: Figlet
 Order: 50
 RedirectFrom: figlet
+Description: "*Spectre.Console* can render FIGlet text by using the **FigletText** class."
 ---
 
 Spectre.Console can render [FIGlet](http://www.figlet.org/) text by using the `FigletText` class.
@@ -8,7 +9,7 @@ Spectre.Console can render [FIGlet](http://www.figlet.org/) text by using the `F
 ## Default font
 
 ```csharp
-AnsiConsole.Render(
+AnsiConsole.Write(
     new FigletText("Hello")
         .LeftAligned()
         .Color(Color.Red));
@@ -22,7 +23,7 @@ AnsiConsole.Render(
 ```csharp
 var font = FigletFont.Load("starwars.flf");
 
-AnsiConsole.Render(
+AnsiConsole.Write(
     new FigletText(font, "Hello")
         .LeftAligned()
         .Color(Color.Red));

docs/input/widgets/index.cshtml

@@ -1,5 +1,6 @@
 Title: Widgets
-Order: 9
+Order: 70
+Description: "*Spectre.Console* supports many built-in widgets to help render beautiful output."
 ---
 
 <ul>

docs/input/widgets/rule.md

@@ -1,6 +1,11 @@
 Title: Rule
 Order: 30
 RedirectFrom: rule
+Description: "The **Rule** class is used to render a horizontal rule (line) to the terminal."
+Highlights:
+    - Custom colors for line and title.
+    - Specify left, center or right aligned title.
+
 ---
 
 The `Rule` class is used to render a horizontal rule (line) to the terminal.
@@ -13,7 +18,7 @@ To render a rule without a title:
 
 ```csharp
 var rule = new Rule();
-AnsiConsole.Render(rule);
+AnsiConsole.Write(rule);
 ```
 
 ## Title
@@ -22,7 +27,7 @@ You can set the rule title markup text.
 
 ```csharp
 var rule = new Rule("[red]Hello[/]");
-AnsiConsole.Render(rule);
+AnsiConsole.Write(rule);
 ```
 
 ```text
@@ -36,7 +41,7 @@ You can set the rule's title alignment.
 ```csharp
 var rule = new Rule("[red]Hello[/]");
 rule.Alignment = Justify.Left;
-AnsiConsole.Render(rule);
+AnsiConsole.Write(rule);
 ```
 
 ```text
@@ -48,7 +53,7 @@ You can also specify it via an extension method:
 ```csharp
 var rule = new Rule("[red]Hello[/]");
 rule.LeftAligned();
-AnsiConsole.Render(rule);
+AnsiConsole.Write(rule);
 ```
 
 ```text
@@ -61,12 +66,12 @@ AnsiConsole.Render(rule);
 ```csharp
 var rule = new Rule("[red]Hello[/]");
 rule.Style = Style.Parse("red dim");
-AnsiConsole.Render(rule);
+AnsiConsole.Write(rule);
 ```
 You can also specify it via an extension method
 
 ```csharp
 var rule = new Rule("[red]Hello[/]");
 rule.RuleStyle("red dim");
-AnsiConsole.Render(rule);
+AnsiConsole.Write(rule);
 ```

docs/input/widgets/table.md

@@ -1,6 +1,7 @@
 Title: Table
 Order: 0
 RedirectFrom: tables
+Description: "Tables are a perfect way of displaying tabular data in a terminal. *Spectre.Console* is super smart about rendering tables and will adjust all columns to fit whatever is inside them."
 ---
 
 Tables are a perfect way of displaying tabular data in a terminal.
@@ -34,7 +35,7 @@ table.AddRow("Baz", "[green]Qux[/]");
 table.AddRow(new Markup("[blue]Corgi[/]"), new Panel("Waldo"));
 
 // Render the table to the console
-AnsiConsole.Render(table);
+AnsiConsole.Write(table);
 ```
 
 This will render the following output:

docs/input/widgets/tree.md

@@ -1,5 +1,9 @@
 Title: Tree
 Order: 10
+Description: "The **Tree** widget can be used to render hierarchical data."
+Highlights:
+    - Custom colors and styles for guidelines.
+    - Include any *Spectre.Console* widgets as child nodes.
 ---
 
 The `Tree` widget can be used to render hierarchical data.
@@ -31,7 +35,7 @@ bar.AddNode(new Calendar(2020, 12)
     .HideHeader());
 
 // Render the tree
-AnsiConsole.Render(root);
+AnsiConsole.Write(root);
 ```
 
 ## Collapsing nodes

docs/package-lock.json

@@ -138,12 +138,29 @@
         "lodash.uniq": "^4.5.0"
       }
     },
+    "@types/node": {
+      "version": "16.3.1",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-16.3.1.tgz",
+      "integrity": "sha512-N87VuQi7HEeRJkhzovao/JviiqKjDKMVKxKMfUvSKw+MbkbW8R0nA3fi/MQhhlxV2fQ+2ReM+/Nt4efdrJx3zA==",
+      "dev": true,
+      "optional": true
+    },
     "@types/parse-json": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/@types/parse-json/-/parse-json-4.0.0.tgz",
       "integrity": "sha512-//oorEZjL6sbPcKUaCdIGlIUeH26mgzimjBB77G6XRgnDl/L5wOnpyBGRe/Mmf5CVW3PwEBE1NjiMZ/ssFh4wA==",
       "dev": true
     },
+    "@types/yauzl": {
+      "version": "2.9.2",
+      "resolved": "https://registry.npmjs.org/@types/yauzl/-/yauzl-2.9.2.tgz",
+      "integrity": "sha512-8uALY5LTvSuHgloDVUvWP3pIauILm+8/0pDMokuDYIoNsOkSwd5AiHBTSEJjKTDcZr5z8UpgOWZkxBF4iJftoA==",
+      "dev": true,
+      "optional": true,
+      "requires": {
+        "@types/node": "*"
+      }
+    },
     "acorn": {
       "version": "7.4.1",
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-7.4.1.tgz",
@@ -167,6 +184,15 @@
       "integrity": "sha512-OPdCF6GsMIP+Az+aWfAAOEt2/+iVDKE7oy6lJ098aoe59oAmK76qV6Gw60SbZ8jHuG2wH058GF4pLFbYamYrVA==",
       "dev": true
     },
+    "agent-base": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-6.0.2.tgz",
+      "integrity": "sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ==",
+      "dev": true,
+      "requires": {
+        "debug": "4"
+      }
+    },
     "ansi-regex": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.0.tgz",
@@ -262,6 +288,12 @@
         "node-releases": "^1.1.71"
       }
     },
+    "buffer-crc32": {
+      "version": "0.2.13",
+      "resolved": "https://registry.npmjs.org/buffer-crc32/-/buffer-crc32-0.2.13.tgz",
+      "integrity": "sha1-DTM+PwDqxQqhRUq9MO+MKl2ackI=",
+      "dev": true
+    },
     "bytes": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.0.tgz",
@@ -438,6 +470,15 @@
       "integrity": "sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==",
       "dev": true
     },
+    "debug": {
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.2.tgz",
+      "integrity": "sha512-mOp8wKcvj7XxC78zLgw/ZA+6TSgkoE2C/ienthhRD298T7UNwAg9diBpLRxC0mOezLl4B0xV7M0cCO6P/O0Xhw==",
+      "dev": true,
+      "requires": {
+        "ms": "2.1.2"
+      }
+    },
     "defined": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/defined/-/defined-1.0.0.tgz",
@@ -494,6 +535,15 @@
       "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
       "dev": true
     },
+    "end-of-stream": {
+      "version": "1.4.4",
+      "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.4.tgz",
+      "integrity": "sha512-+uw1inIHVPQoaVuHzRyXd21icM+cnt4CzD5rW+NC1wjOUSTOs+Te7FOv7AhN7vS9x/oIyhLP5PR1H+phQAHu5Q==",
+      "dev": true,
+      "requires": {
+        "once": "^1.4.0"
+      }
+    },
     "error-ex": {
       "version": "1.3.2",
       "resolved": "https://registry.npmjs.org/error-ex/-/error-ex-1.3.2.tgz",
@@ -523,6 +573,18 @@
       "integrity": "sha1-G2HAViGQqN/2rjuyzwIAyhMLhtQ=",
       "dev": true
     },
+    "extract-zip": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/extract-zip/-/extract-zip-2.0.1.tgz",
+      "integrity": "sha512-GDhU9ntwuKyGXdZBUgTIe+vXnWj0fppUEtMDL0+idd5Sta8TGpHssn/eusA9mrPr9qNDym6SxAYZjNvCn/9RBg==",
+      "dev": true,
+      "requires": {
+        "@types/yauzl": "^2.9.1",
+        "debug": "^4.1.1",
+        "get-stream": "^5.1.0",
+        "yauzl": "^2.10.0"
+      }
+    },
     "fast-glob": {
       "version": "3.2.5",
       "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.2.5.tgz",
@@ -546,6 +608,15 @@
         "reusify": "^1.0.4"
       }
     },
+    "fd-slicer": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/fd-slicer/-/fd-slicer-1.1.0.tgz",
+      "integrity": "sha1-JcfInLH5B3+IkbvmHY85Dq4lbx4=",
+      "dev": true,
+      "requires": {
+        "pend": "~1.2.0"
+      }
+    },
     "fill-range": {
       "version": "7.0.1",
       "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.0.1.tgz",
@@ -604,6 +675,15 @@
       "integrity": "sha512-sY22aA6xchAzprjyqmSEQv4UbAAzRN0L2dQB0NlN5acTTK9Don6nhoc3eAbUnpZiCANAMfd/+40kVdKfFygohg==",
       "dev": true
     },
+    "get-stream": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-5.2.0.tgz",
+      "integrity": "sha512-nBF+F1rAZVCu/p7rjzgA+Yb4lfYXrpl7a6VmJrU8wF9I1CKvP/QwPNZHnOlwbTkY6dvtFIzFMSyQXbLoTQPRpA==",
+      "dev": true,
+      "requires": {
+        "pump": "^3.0.0"
+      }
+    },
     "glob": {
       "version": "7.1.6",
       "resolved": "https://registry.npmjs.org/glob/-/glob-7.1.6.tgz",
@@ -704,6 +784,16 @@
       "integrity": "sha512-1qYz89hW3lFDEazhjW0yVAV87lw8lVkrJocr72XmBkMKsoSVJCQx3W8BXsC7hO2qAt8BoVjYjtAcZ9perqGnNg==",
       "dev": true
     },
+    "https-proxy-agent": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-5.0.0.tgz",
+      "integrity": "sha512-EkYm5BcKUGiduxzSt3Eppko+PiNWNEpa4ySk9vTC6wDsQJW9rHSa+UhGNJoRYp7bz6Ht1eaRIa6QaJqO5rCFbA==",
+      "dev": true,
+      "requires": {
+        "agent-base": "6",
+        "debug": "4"
+      }
+    },
     "ignore": {
       "version": "5.1.8",
       "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.1.8.tgz",
@@ -825,6 +915,12 @@
       "integrity": "sha1-6PvzdNxVb/iUehDcsFctYz8s+hA=",
       "dev": true
     },
+    "jpeg-js": {
+      "version": "0.4.3",
+      "resolved": "https://registry.npmjs.org/jpeg-js/-/jpeg-js-0.4.3.tgz",
+      "integrity": "sha512-ru1HWKek8octvUHFHvE5ZzQ1yAsJmIvRdGWvSoKV52XKyuyYA437QWDttXT8eZXDSbuMpHlLzPDZUPd6idIz+Q==",
+      "dev": true
+    },
     "js-tokens": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
@@ -941,6 +1037,12 @@
         "picomatch": "^2.2.3"
       }
     },
+    "mime": {
+      "version": "2.5.2",
+      "resolved": "https://registry.npmjs.org/mime/-/mime-2.5.2.tgz",
+      "integrity": "sha512-tqkh47FzKeCPD2PUiPB6pkbMzsCasjxAfC62/Wap5qrUWcb+sFasXUC5I3gYM5iBM8v/Qpn4UK0x+j0iHyFPDg==",
+      "dev": true
+    },
     "mini-svg-data-uri": {
       "version": "1.2.3",
       "resolved": "https://registry.npmjs.org/mini-svg-data-uri/-/mini-svg-data-uri-1.2.3.tgz",
@@ -968,6 +1070,12 @@
       "integrity": "sha512-1lM+BMLGuDfsdwf3rsgBSrxJwAZHFIrQ8YR61xIqdHo0uNKI9M52wNpHSrliZATJp51On6JD0AfRxd4YGSU0lw==",
       "dev": true
     },
+    "ms": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz",
+      "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==",
+      "dev": true
+    },
     "nanoid": {
       "version": "3.1.22",
       "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.1.22.tgz",
@@ -1096,6 +1204,12 @@
       "integrity": "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==",
       "dev": true
     },
+    "pend": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/pend/-/pend-1.2.0.tgz",
+      "integrity": "sha1-elfrVQpng/kRUzH89GY9XI4AelA=",
+      "dev": true
+    },
     "picomatch": {
       "version": "2.2.3",
       "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.2.3.tgz",
@@ -1108,6 +1222,34 @@
       "integrity": "sha1-7RQaasBDqEnqWISY59yosVMw6Qw=",
       "dev": true
     },
+    "playwright": {
+      "version": "1.12.3",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.12.3.tgz",
+      "integrity": "sha512-eyhHvZV7dMAUltqjQsgJ9CjZM8dznzN1+rcfCI6W6lfQ7IlPvTFGLuKOCcI4ETbjfbxqaS5FKIkb1WDDzq2Nww==",
+      "dev": true,
+      "requires": {
+        "commander": "^6.1.0",
+        "debug": "^4.1.1",
+        "extract-zip": "^2.0.1",
+        "https-proxy-agent": "^5.0.0",
+        "jpeg-js": "^0.4.2",
+        "mime": "^2.4.6",
+        "pngjs": "^5.0.0",
+        "progress": "^2.0.3",
+        "proper-lockfile": "^4.1.1",
+        "proxy-from-env": "^1.1.0",
+        "rimraf": "^3.0.2",
+        "stack-utils": "^2.0.3",
+        "ws": "^7.4.6",
+        "yazl": "^2.5.1"
+      }
+    },
+    "pngjs": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/pngjs/-/pngjs-5.0.0.tgz",
+      "integrity": "sha512-40QW5YalBNfQo5yRYmiw7Yz6TKKVr3h6970B2YE+3fQpsWcrbj1PzJgxeJ19DRQjhMbKPIuMY8rFaXc8moolVw==",
+      "dev": true
+    },
     "postcss": {
       "version": "8.2.10",
       "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.2.10.tgz",
@@ -1285,6 +1427,39 @@
       "integrity": "sha1-t+PqQkNaTJsnWdmeDyAesZWALuE=",
       "dev": true
     },
+    "progress": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/progress/-/progress-2.0.3.tgz",
+      "integrity": "sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA==",
+      "dev": true
+    },
+    "proper-lockfile": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/proper-lockfile/-/proper-lockfile-4.1.2.tgz",
+      "integrity": "sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA==",
+      "dev": true,
+      "requires": {
+        "graceful-fs": "^4.2.4",
+        "retry": "^0.12.0",
+        "signal-exit": "^3.0.2"
+      }
+    },
+    "proxy-from-env": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-1.1.0.tgz",
+      "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==",
+      "dev": true
+    },
+    "pump": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.0.tgz",
+      "integrity": "sha512-LwZy+p3SFs1Pytd/jYct4wpv49HiYCqd9Rlc5ZVdk0V+8Yzv6jR5Blk3TRmPL1ft69TxP0IMZGJ+WPFU2BFhww==",
+      "dev": true,
+      "requires": {
+        "end-of-stream": "^1.1.0",
+        "once": "^1.3.1"
+      }
+    },
     "purgecss": {
       "version": "3.1.3",
       "resolved": "https://registry.npmjs.org/purgecss/-/purgecss-3.1.3.tgz",
@@ -1367,12 +1542,27 @@
       "integrity": "sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==",
       "dev": true
     },
+    "retry": {
+      "version": "0.12.0",
+      "resolved": "https://registry.npmjs.org/retry/-/retry-0.12.0.tgz",
+      "integrity": "sha1-G0KmJmoh8HQh0bC1S33BZ7AcATs=",
+      "dev": true
+    },
     "reusify": {
       "version": "1.0.4",
       "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.0.4.tgz",
       "integrity": "sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw==",
       "dev": true
     },
+    "rimraf": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-3.0.2.tgz",
+      "integrity": "sha512-JZkJMZkAGFFPP2YqXZXPbMlMBgsxzE8ILs4lMIX/2o0L9UBw9O/Y3o6wFw/i9YLapcUJWwqbi3kdxIPdC62TIA==",
+      "dev": true,
+      "requires": {
+        "glob": "^7.1.3"
+      }
+    },
     "run-parallel": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz",
@@ -1397,6 +1587,12 @@
       "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
       "dev": true
     },
+    "signal-exit": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.3.tgz",
+      "integrity": "sha512-VUJ49FC8U1OxwZLxIbTTrDvLnf/6TDgxZcK8wxR8zs13xpx7xbG60ndBlhNrFi2EMuFRoeDoJO7wthSLq42EjA==",
+      "dev": true
+    },
     "simple-swizzle": {
       "version": "0.2.2",
       "resolved": "https://registry.npmjs.org/simple-swizzle/-/simple-swizzle-0.2.2.tgz",
@@ -1418,6 +1614,23 @@
       "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==",
       "dev": true
     },
+    "stack-utils": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/stack-utils/-/stack-utils-2.0.3.tgz",
+      "integrity": "sha512-gL//fkxfWUsIlFL2Tl42Cl6+HFALEaB1FU76I/Fy+oZjRreP7OPMXFlGbxM7NQsI0ZpUfw76sHnv0WNYuTb7Iw==",
+      "dev": true,
+      "requires": {
+        "escape-string-regexp": "^2.0.0"
+      },
+      "dependencies": {
+        "escape-string-regexp": {
+          "version": "2.0.0",
+          "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz",
+          "integrity": "sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==",
+          "dev": true
+        }
+      }
+    },
     "string-width": {
       "version": "4.2.2",
       "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.2.tgz",
@@ -1529,6 +1742,12 @@
       "integrity": "sha1-tSQ9jz7BqjXxNkYFvA0QNuMKtp8=",
       "dev": true
     },
+    "ws": {
+      "version": "7.5.2",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-7.5.2.tgz",
+      "integrity": "sha512-lkF7AWRicoB9mAgjeKbGqVUekLnSNO4VjKVnuPHpQeOxZOErX6BPXwJk70nFslRCEEA8EVW7ZjKwXaP9N+1sKQ==",
+      "dev": true
+    },
     "xtend": {
       "version": "4.0.2",
       "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz",
@@ -1567,6 +1786,25 @@
       "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-20.2.7.tgz",
       "integrity": "sha512-FiNkvbeHzB/syOjIUxFDCnhSfzAL8R5vs40MgLFBorXACCOAEaWu0gRZl14vG8MR9AOJIZbmkjhusqBYZ3HTHw==",
       "dev": true
+    },
+    "yauzl": {
+      "version": "2.10.0",
+      "resolved": "https://registry.npmjs.org/yauzl/-/yauzl-2.10.0.tgz",
+      "integrity": "sha1-x+sXyT4RLLEIb6bY5R+wZnt5pfk=",
+      "dev": true,
+      "requires": {
+        "buffer-crc32": "~0.2.3",
+        "fd-slicer": "~1.1.0"
+      }
+    },
+    "yazl": {
+      "version": "2.5.1",
+      "resolved": "https://registry.npmjs.org/yazl/-/yazl-2.5.1.tgz",
+      "integrity": "sha512-phENi2PLiHnHb6QBVot+dJnaAZ0xosj7p3fWl+znIjBDlnMI2PsZCJZ306BPTFOaHf5qdDEI8x5qFrSOBN5vrw==",
+      "dev": true,
+      "requires": {
+        "buffer-crc32": "~0.2.3"
+      }
     }
   }
 }

docs/package.json

@@ -16,6 +16,7 @@
     "@tailwindcss/typography": "^0.4.0",
     "autoprefixer": "^10.2.5",
     "cross-env": "^7.0.3",
+    "playwright": "^1.12.3",
     "postcss": "^8.2.10",
     "postcss-cli": "^8.3.1",
     "tailwindcss": "^2.1.1"

docs/src/Pipelines/SocialCardPipeline.cs

@@ -0,0 +1,119 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.FileProviders;
+using Microsoft.Extensions.Logging;
+using Microsoft.Playwright;
+using Statiq.Common;
+using Statiq.Core;
+using Statiq.Web;
+using Statiq.Web.Modules;
+using Statiq.Web.Pipelines;
+
+namespace Docs.Pipelines
+{
+    public class SocialImages : Pipeline
+    {
+        public SocialImages()
+        {
+            Dependencies.AddRange(nameof(Inputs));
+
+            ProcessModules = new ModuleList
+            {
+                new GetPipelineDocuments(ContentType.Content),
+
+                // Filter to non-archive content
+                new FilterDocuments(Config.FromDocument(doc => !Archives.IsArchive(doc))),
+
+                // Process the content
+                new CacheDocuments
+                {
+                    new AddTitle(),
+                    new SetDestination(true),
+                    new ExecuteIf(Config.FromSetting(WebKeys.OptimizeContentFileNames, true))
+                    {
+                        new OptimizeFileName()
+                    },
+                    new GenerateSocialImage(),
+                }
+            };
+
+            OutputModules = new ModuleList { new WriteFiles() };
+        }
+    }
+
+    class GenerateSocialImage : ParallelModule
+    {
+        private IPlaywright _playwright;
+        private IBrowser _browser;
+        private WebApplication _app;
+        private IBrowserContext _context;
+
+        protected override async Task BeforeExecutionAsync(IExecutionContext context)
+        {
+            var builder = WebApplication.CreateBuilder();
+            builder.Logging.ClearProviders();
+
+            builder.Services
+                .AddRazorPages()
+                .WithRazorPagesRoot("/src/SocialCards/");
+
+            _app = builder.Build();
+            _app.MapRazorPages();
+            _app.UseStaticFiles(new StaticFileOptions
+            {
+                FileProvider = new PhysicalFileProvider(
+                    Path.Combine(builder.Environment.ContentRootPath, "src/SocialCards")),
+                RequestPath = "/static"
+            });
+
+            await _app.StartAsync().ConfigureAwait(false);
+
+            _playwright = await Playwright.CreateAsync().ConfigureAwait(false);
+            _browser = await _playwright.Chromium.LaunchAsync().ConfigureAwait(false);
+            _context = await _browser.NewContextAsync(new BrowserNewContextOptions {
+                ViewportSize = new ViewportSize { Width = 1200, Height = 618 },
+            }).ConfigureAwait(false);
+        }
+
+        protected override async Task FinallyAsync(IExecutionContext context)
+        {
+            await _context.DisposeAsync().ConfigureAwait(false);
+            await _browser.DisposeAsync().ConfigureAwait(false);
+            _playwright.Dispose();
+            await _app.DisposeAsync().ConfigureAwait(false);
+            await base.FinallyAsync(context);
+        }
+
+        protected override async Task<IEnumerable<IDocument>> ExecuteInputAsync(IDocument input, IExecutionContext context)
+        {
+            var url = _app.Urls.FirstOrDefault(u => u.StartsWith("http://"));
+            var page = await _context.NewPageAsync().ConfigureAwait(false);
+
+            var title = input.GetString("Title");
+            var description = input.GetString("Description");
+            var highlights = input.GetList<string>("Highlights") ?? Array.Empty<string>();
+
+            await page.GotoAsync($"{url}/?title={title}&desc={description}&highlights={string.Join("||", highlights)}");
+
+            // This will not just wait for the  page to load over the network, but it'll also give
+            // chrome a chance to complete rendering of the fonts while the wait timeout completes.
+            await page.WaitForLoadStateAsync(LoadState.NetworkIdle).ConfigureAwait(false);
+            var bytes = await page.ScreenshotAsync().ConfigureAwait(false);
+            await page.CloseAsync().ConfigureAwait(false);
+
+            var destination = input.Destination.InsertSuffix("-social").ChangeExtension("png");
+            var doc = context.CreateDocument(
+                input.Source,
+                destination,
+                new MetadataItems { { "DocId", input.Id }},
+                context.GetContentProvider(bytes));
+
+            return new[] { doc };
+        }
+    }
+}

docs/src/SocialCards/index.cshtml

@@ -0,0 +1,121 @@
+@page
+@using Markdig
+@model Docs.SocialCards.SocialCardModel
+
+@{
+    Layout = null;
+}
+<html>
+
+<head>
+    <link rel="preload" as="font" href="/static/CascadiaCodePL.woff2">
+    <link rel="stylesheet" href="static/styles.css" />
+</head>
+<body>
+
+  <div id="container">
+    <div id="console">
+        <div class="line"><span style="color:var(--brightBlack)">╭─</span><span style="color:var(--folder)">&#xe0b2;</span><span style="background-color:var(--folder);color:var(--black)"> ~/spectre.console</span><span style="color:var(--folder);background-color:var(--dotnet)">&#xe0b0;</span><span style="background-color:var(--blue)"> .NET 5.0 </span><span style="color:var(--dotnet);background-color:var(--git)">&#xe0b0;</span><span style="background-color:var(--git);color:var(--background)"> &#xe0a0; main </span><span style="color:var(--git)">&#xe0b4;</span></div>
+        <div class="line"><span style="color:var(--brightBlack)">╰─</span> dotnet run</div>
+        <div class="line"></div>
+        <div class="line">╭────────────────────────────────────────────────────────╮</div>
+        <div class="line">│                                                        │</div>
+        <div class="line">│                                                        │</div>
+        <div class="line">│                                                        │</div>
+        <div class="line">│                                                        │</div>
+        <div class="line">│                                                        │</div>
+        <div class="line">│                                                        │</div>
+        <div class="line">│                                                        │</div>
+        <div class="line">│                                                        │</div>
+        <div class="line">│                                                        │</div>
+        <div class="line">│                                                        │</div>
+        <div class="line">╰────────────────────────────────────────────────────────╯</div>
+
+        <div id="title"><span style="color:var(--brightPurple)">@Model.Title</span></div>
+        <div id="content">
+            @if (string.IsNullOrWhiteSpace(Model.Description) == false)
+            {
+                <p>@Html.Raw(Markdown.ToHtml(Model.Description))</p>
+            }
+            @if (string.IsNullOrWhiteSpace(Model.Highlights) == false)
+            {
+                <ul>
+                    @foreach (var highlight in Model.Highlights.Split("||"))
+                    {
+                        <li>@Html.Raw(Markdown.ToHtml(highlight))</li>
+                    }
+                </ul>
+            }
+            @if (string.IsNullOrWhiteSpace(Model.Footer) == false)
+            {
+                <div id="footer"><span style="color:var(--brightBlack)">@Html.Raw(@Markdown.ToHtml(@Model.Footer))</span></div>
+            }
+        </div>
+
+    </div>
+    <svg id="logo" version="1.0" xmlns="http://www.w3.org/2000/svg" width="1270.000000pt" height="1270.000000pt" viewBox="0 0 1270.000000 1270.000000" preserveAspectRatio="xMidYMid meet">
+      <metadata>
+        Created by potrace 1.16, written by Peter Selinger 2001-2019
+      </metadata>
+      <g transform="translate(0.000000,1270.000000) scale(0.100000,-0.100000)" stroke="none">
+        <path d="M799 10610 c-199 -48 -354 -191 -414 -383 l-25 -78 0 -3084 0 -3084
+25 -79 c45 -141 155 -270 289 -335 124 -61 -80 -57 2819 -57 l2646 0 5 -43 c3
+-23 8 -71 11 -105 13 -137 88 -334 179 -471 57 -85 187 -219 247 -254 25 -15
+76 -34 112 -43 87 -22 163 -7 246 46 120 78 195 211 234 411 l23 124 14 -55
+c63 -263 172 -511 326 -741 94 -142 229 -291 313 -348 272 -185 583 -197 750
+-30 66 67 84 109 89 215 4 90 4 91 -51 230 -108 276 -137 477 -122 868 l7 196
+77 0 c55 0 118 -11 229 -39 l154 -38 50 -84 c103 -172 221 -427 277 -599 38
+-120 70 -274 86 -412 8 -75 21 -155 29 -178 37 -106 117 -199 220 -253 51 -26
+202 -35 283 -17 83 18 193 97 268 192 157 199 256 485 286 825 11 122 6 524
+-7 583 -5 24 -1 26 62 43 64 16 67 16 80 0 39 -50 109 -215 149 -351 25 -85
+55 -174 67 -199 73 -156 261 -206 441 -117 65 32 110 70 159 135 128 169 178
+414 157 764 -8 143 -38 350 -55 376 -2 4 7 25 22 46 77 112 168 344 200 504
+l16 86 87 28 c188 60 391 170 498 269 132 122 183 230 183 383 0 71 -5 98 -24
+138 -24 52 -82 112 -138 141 -52 28 -205 30 -378 5 -80 -11 -179 -23 -220 -27
+l-75 -6 -29 56 c-33 65 -137 182 -211 236 -75 55 -156 94 -382 181 -110 43
+-221 87 -245 100 -54 27 -92 69 -125 138 -25 52 -26 59 -20 180 4 69 16 200
+26 291 52 430 53 809 5 1170 -54 405 -249 740 -569 979 -136 102 -297 190
+-419 231 l-36 12 0 433 c0 433 0 434 -25 512 -52 167 -171 292 -341 360 l-69
+28 -4215 2 c-2318 0 -4231 -3 -4251 -7z m8363 -1476 c417 -53 735 -193 962
+-423 98 -98 155 -175 210 -282 84 -160 117 -292 141 -559 28 -313 17 -684 -30
+-1025 -9 -60 -18 -164 -22 -230 -10 -208 22 -314 136 -452 76 -91 124 -118
+391 -218 307 -116 377 -155 450 -249 23 -31 41 -58 39 -60 -2 -2 -47 8 -99 21
+-131 35 -268 36 -360 3 -132 -47 -248 -116 -364 -218 -163 -143 -516 -488
+-703 -687 -350 -372 -504 -514 -701 -644 -348 -231 -878 -408 -1322 -442 -409
+-31 -796 45 -1059 208 -111 69 -249 210 -292 298 -32 65 -34 76 -33 165 1 104
+23 178 85 287 75 131 137 194 430 441 181 152 251 295 250 511 -1 152 -16 223
+-117 560 -35 117 -61 217 -58 222 3 5 20 9 38 9 55 0 217 31 261 50 53 23 103
+73 132 131 43 88 56 187 59 437 2 266 -1 258 91 292 108 40 254 21 330 -45 35
+-30 35 -32 53 -170 41 -311 106 -484 206 -546 48 -29 168 -48 381 -59 188 -10
+432 -1 548 20 76 14 206 56 266 86 64 32 122 101 144 170 15 49 17 82 12 253
+-5 198 -27 398 -52 482 -42 146 -125 221 -290 265 -57 15 -108 19 -268 19
+l-197 0 0 45 c0 120 -37 255 -82 300 -76 77 -210 5 -291 -157 -31 -60 -67
+-184 -67 -229 0 -27 -6 -34 -41 -50 -65 -29 -159 -98 -195 -144 -34 -43 -67
+-119 -79 -181 l-6 -35 -57 28 c-114 57 -270 58 -379 2 -61 -31 -70 -21 -49 54
+33 118 16 442 -29 536 -38 79 -114 84 -188 12 -68 -66 -136 -230 -137 -330 l0
+-29 -61 7 c-34 3 -93 6 -131 6 l-69 0 6 48 c14 97 56 282 84 368 155 475 486
+821 963 1008 108 42 308 94 430 110 62 9 124 17 138 20 76 11 479 5 592 -10z
+m-7029 -78 c18 -8 261 -243 569 -552 582 -584 560 -559 543 -651 -6 -33 -69
+-101 -523 -557 -553 -554 -564 -564 -644 -551 -89 15 -151 110 -128 198 10 37
+65 95 463 495 l452 452 -472 473 c-414 414 -472 477 -478 510 -25 132 98 235
+218 183z m7169 -1405 c164 -57 201 -136 234 -502 37 -414 9 -486 -212 -558
+-155 -50 -298 -64 -579 -57 -249 6 -398 23 -439 50 -95 62 -177 346 -180 621
+-1 135 0 142 28 203 50 109 148 179 304 218 149 37 329 53 567 50 191 -2 216
+-4 277 -25z m-2002 -174 c95 -34 118 -52 152 -114 52 -94 63 -159 62 -368 -1
+-358 -44 -479 -187 -520 -146 -42 -612 -65 -727 -36 -153 38 -196 98 -226 316
+-16 120 -31 487 -21 527 9 35 89 121 140 151 99 58 228 76 522 73 200 -2 214
+-3 285 -29z m-1604 -443 c45 -33 67 -70 71 -121 5 -59 -25 -117 -77 -147 -35
+-21 -47 -21 -980 -24 -520 -2 -964 0 -988 3 -57 8 -116 60 -130 115 -19 75 12
+146 78 182 34 17 75 18 1017 16 974 -3 982 -3 1009 -24z m5329 -2140 c66 -7
+173 -14 237 -14 103 0 146 5 247 26 24 5 24 5 18 -64 -15 -159 -89 -371 -180
+-515 l-43 -68 -57 113 c-72 145 -160 261 -318 422 l-126 128 51 -7 c28 -3 105
+-13 171 -21z m-812 -652 c53 -41 140 -115 193 -165 96 -91 224 -231 224 -245
+0 -5 -30 -18 -67 -30 -79 -25 -305 -84 -308 -80 -1 2 -12 53 -24 113 -28 135
+-70 268 -127 402 -24 57 -44 106 -44 109 0 9 43 -20 153 -104z m-1173 -560
+c-9 -4 -271 61 -315 78 -29 11 -28 12 79 55 59 24 111 46 114 49 3 3 33 -36
+67 -87 34 -50 59 -93 55 -95z" />
+      </g>
+    </svg>
+  </div>
+</body>
+</html>

docs/src/SocialCards/index.cshtml.cs

@@ -0,0 +1,31 @@
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.RazorPages;
+using Microsoft.Extensions.Logging;
+
+namespace Docs.SocialCards{
+    public class SocialCardModel : PageModel
+    {
+        [BindProperty(Name = "title", SupportsGet = true)]
+        public string Title { get; set; }
+
+        [BindProperty(Name = "desc", SupportsGet = true)]
+        public string Description { get; set; }
+
+        [BindProperty(Name = "highlights", SupportsGet = true)]
+        public string Highlights { get; set; }
+
+        [BindProperty(Name = "footer", SupportsGet = true)]
+        public string Footer { get; set; }
+
+        private readonly ILogger<SocialCardModel> _logger;
+
+        public SocialCardModel(ILogger<SocialCardModel> logger)
+        {
+            _logger = logger;
+        }
+
+        public void OnGet()
+        {
+        }
+    }
+}

docs/src/SocialCards/styles.css

@@ -0,0 +1,148 @@
+@font-face {
+    font-family: 'CascadiaCodePL';
+    src: url('CascadiaCodePL.woff2') format('woff2');
+}
+
+* {
+    padding:0;
+    margin:0;
+  }
+
+  :root {
+    --height: 618px;
+    --width:1200px;
+    --line-height: 39px;
+    --padding: 20px;
+    --rows: calc((--var(--height) - var(--padding) * 2) / var(--line-height));
+    --background: #1E2127;
+    --black: #000000;
+    --blue: #61AFEF;
+    --brightBlack: #5C6370;
+    --brightBlue: #61AFEF;
+    --brightCyan: #56B6C2;
+    --brightGreen: #98C379;
+    --brightPurple: #C678DD;
+    --brightRed: #E06C75;
+    --brightWhite: #FFFFFF;
+    --brightYellow: #D19A66;
+    --cyan: #56B6C2;
+    --foreground: #5C6370;
+    --green: #98C379;
+    --purple: #C678DD;
+    --red: #E06C75;
+    --white: #ABB2BF;
+    --yellow: #D19A66;
+    --folder: var(--yellow);
+    --dotnet: var(--blue);
+    --git: var(--green);
+  }
+
+
+  body{
+    font-family:'CascadiaCodePL',monospace;
+    font-weight:400;
+    font-size: calc(var(--line-height) - 5px);
+  }
+
+  #container {
+    background-color: var(--background);
+    color: #fff;
+    width: calc(var(--width) - var(--padding) * 2);
+    height: calc(var(--height) - var(--padding) * 2);
+    padding:var(--padding);
+    position: relative;
+  }
+
+  #console{
+    position: relative;
+  }
+
+  .line{
+      height:var(--line-height);
+      width:100%;
+      white-space: pre;
+  }
+
+  #title{
+    position: absolute;
+    left: 3ch;
+    top: calc(3 * var(--line-height));
+    margin: 0 -3px;
+    padding: 0 3px;
+    background:var(--background);
+    z-index:4;
+  }
+
+  #content{
+    position: absolute;
+    left: 3ch;
+    top: calc(5 * var(--line-height));;
+    height:calc(var(--height) - 7 * var(--line-height));
+    width: 53ch;
+    line-height:var(--line-height);
+    overflow-y: hidden;
+  }
+
+  #content p {
+    margin: 0;
+  }
+
+  #content p + ul {
+    margin-top:var(--line-height);
+  }
+
+  #content strong {
+    color: var(--yellow);
+    font-weight: 400;
+  }
+
+  #content em, #content i {
+    color: var(--blue);
+    font-style: normal;
+  }
+
+  #content ul {
+    list-style: "*";
+    margin-left: 1ch;
+  }
+
+  #content ul li {
+    padding-left:1ch;
+  }
+
+
+
+  #footer{
+    position: absolute;
+    top: calc(var(--height) - var(--padding) - var(--line-height) * 3);
+    left  : 3ch;
+    background:var(--background);
+    width:51ch;
+    z-index:4;
+  }
+
+  #logo{
+    height:calc(var(--line-height) * 2.5);
+    width:calc(var(--line-height) * 2.5);
+    position:absolute;
+    right:2ch;
+    top:calc(var(--padding) / 2);
+    fill: var(--white);
+    opacity:.4;
+  }
+
+  #container::before {
+    /* fake scan lines */
+    content: " ";
+    display: block;
+    position: absolute;
+    top: 0;
+    left: 0;
+    bottom: 0;
+    right: 0;
+    background: linear-gradient(rgba(18, 16, 16, 0) 50%, rgba(0, 0, 0, 0.25) 50%), linear-gradient(90deg, rgba(255, 0, 0, 0.06), rgba(0, 255, 0, 0.02), rgba(0, 0, 255, 0.06));
+    z-index: 200;
+    background-size: 100% 4px, 5px 100%;
+    pointer-events: none;
+  }
+

dotnet-tools.json

@@ -3,7 +3,7 @@
   "isRoot": true,
   "tools": {
     "cake.tool": {
-      "version": "1.1.0",
+      "version": "2.0.0-rc0001",
       "commands": [
         "dotnet-cake"
       ]
@@ -15,7 +15,7 @@
       ]
     },
     "dotnet-example": {
-      "version": "1.3.1",
+      "version": "1.5.0",
       "commands": [
         "dotnet-example"
       ]

examples/Cli/Delegates/Delegates.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <IsPackable>false</IsPackable>
     <ExampleName>Delegates</ExampleName>
     <ExampleDescription>Demonstrates how to specify commands as delegates.</ExampleDescription>

examples/Cli/Demo/Demo.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <IsPackable>false</IsPackable>
     <ExampleName>Demo</ExampleName>
     <ExampleDescription>Demonstrates the most common use cases of Spectre.Cli.</ExampleDescription>

examples/Cli/Demo/Utilities/SettingsDumper.cs

@@ -23,7 +23,7 @@ namespace Demo.Utilities
                     value ?? "[grey]null[/]");
             }
 
-            AnsiConsole.Render(table);
+            AnsiConsole.Write(table);
         }
     }
 }

examples/Cli/Dynamic/Dynamic.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <IsPackable>false</IsPackable>
     <ExampleName>Dynamic</ExampleName>
     <ExampleDescription>Demonstrates how to define dynamic commands.</ExampleDescription>

examples/Cli/Injection/Infrastructure/TypeResolver.cs

@@ -15,7 +15,12 @@ namespace Spectre.Console.Examples
 
         public object Resolve(Type type)
         {
-            return _provider.GetRequiredService(type);
+            if (type == null)
+            {
+                return null;
+            }
+
+            return _provider.GetService(type);
         }
 
         public void Dispose()

examples/Cli/Injection/Injection.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <IsPackable>false</IsPackable>
     <ExampleName>Injection</ExampleName>
     <ExampleDescription>Demonstrates how to use dependency injection with Spectre.Cli.</ExampleDescription>

examples/Cli/Logging/Logging.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <IsPackable>false</IsPackable>
     <ExampleName>Logging</ExampleName>
     <ExampleDescription>Demonstrates how to dynamically configure Serilog for logging using parameters from a command.</ExampleDescription>

examples/Cli/Logging/Program.cs

@@ -8,7 +8,7 @@ using Spectre.Console.Cli;
  * This works around the chicken and egg situation with configuring serilog via the command line.
  * The logger needs to be configured prior to executing the parser, but the logger needs the parsed values
  * to be configured. By using serilog.sinks.map we can defer configuration. We use a LogLevelSwitch to control the
- * logging levels dynamically, and then we use a serilog enricher that has it's state populated via a
+ * logging levels dynamically, and then we use a serilog enricher that has its state populated via a
  * Spectre.Console CommandInterceptor
  */
 

examples/Console/Borders/Borders.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <ExampleTitle>Borders</ExampleTitle>
     <ExampleDescription>Demonstrates the different kind of borders.</ExampleDescription>
     <ExampleGroup>Widgets</ExampleGroup>

examples/Console/Borders/Program.cs

@@ -35,7 +35,7 @@ namespace Spectre.Console.Examples
                 CreatePanel("None", BoxBorder.None),
             };
 
-            AnsiConsole.Render(
+            AnsiConsole.Write(
                 new Padder(
                     new Columns(items).PadRight(2),
                     new Padding(2,0,0,0)));
@@ -77,13 +77,13 @@ namespace Spectre.Console.Examples
                 CreateTable("Markdown", TableBorder.Markdown),
             };
 
-            AnsiConsole.Render(new Columns(items).Collapse());
+            AnsiConsole.Write(new Columns(items).Collapse());
         }
 
         private static void HorizontalRule(string title)
         {
             AnsiConsole.WriteLine();
-            AnsiConsole.Render(new Rule($"[white bold]{title}[/]").RuleStyle("grey").LeftAligned());
+            AnsiConsole.Write(new Rule($"[white bold]{title}[/]").RuleStyle("grey").LeftAligned());
             AnsiConsole.WriteLine();
         }
     }

examples/Console/Calendars/Calendars.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <ExampleTitle>Calendars</ExampleTitle>
     <ExampleDescription>Demonstrates how to render calendars.</ExampleDescription>
     <ExampleGroup>Widgets</ExampleGroup>

examples/Console/Calendars/Program.cs

@@ -5,7 +5,7 @@ namespace Spectre.Console.Examples
         public static void Main(string[] args)
         {
             AnsiConsole.WriteLine();
-            AnsiConsole.Render(new Calendar(2020, 10)
+            AnsiConsole.Write(new Calendar(2020, 10)
                     .RoundedBorder()
                     .HighlightStyle(Style.Parse("red"))
                     .HeaderStyle(Style.Parse("yellow"))

examples/Console/Canvas/Canvas.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <ExampleTitle>Canvas</ExampleTitle>
     <ExampleDescription>Demonstrates how to render pixels and images.</ExampleDescription>
     <ExampleGroup>Widgets</ExampleGroup>

examples/Console/Canvas/Program.cs

@@ -39,9 +39,9 @@ namespace Spectre.Console.Examples
         private static void Render(IRenderable canvas, string title)
         {
             AnsiConsole.WriteLine();
-            AnsiConsole.Render(new Rule($"[yellow]{title}[/]").LeftAligned().RuleStyle("grey"));
+            AnsiConsole.Write(new Rule($"[yellow]{title}[/]").LeftAligned().RuleStyle("grey"));
             AnsiConsole.WriteLine();
-            AnsiConsole.Render(canvas);
+            AnsiConsole.Write(canvas);
         }
     }
 }

examples/Console/Charts/Charts.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <ExampleTitle>Charts</ExampleTitle>
     <ExampleDescription>Demonstrates how to render charts in a console.</ExampleDescription>
     <ExampleGroup>Widgets</ExampleGroup>

examples/Console/Charts/Program.cs

@@ -32,7 +32,7 @@ namespace Spectre.Console.Examples
 
         private static void Render(string title, IRenderable chart)
         {
-            AnsiConsole.Render(
+            AnsiConsole.Write(
                 new Panel(chart)
                     .Padding(1, 1)
                     .Header(title));

examples/Console/Colors/Colors.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <ExampleTitle>Colors</ExampleTitle>
     <ExampleDescription>Demonstrates how to use [yellow]c[/][red]o[/][green]l[/][blue]o[/][aqua]r[/][lime]s[/] in the console.</ExampleDescription>
     <ExampleGroup>Misc</ExampleGroup>

examples/Console/Colors/Program.cs

@@ -20,7 +20,7 @@ namespace Spectre.Console.Examples
             {
                 AnsiConsole.ResetColors();
                 AnsiConsole.WriteLine();
-                AnsiConsole.Render(new Rule("[yellow bold underline]3-bit Colors[/]").RuleStyle("grey").LeftAligned());
+                AnsiConsole.Write(new Rule("[yellow bold underline]3-bit Colors[/]").RuleStyle("grey").LeftAligned());
                 AnsiConsole.WriteLine();
 
                 for (var i = 0; i < 8; i++)
@@ -43,7 +43,7 @@ namespace Spectre.Console.Examples
             {
                 AnsiConsole.ResetColors();
                 AnsiConsole.WriteLine();
-                AnsiConsole.Render(new Rule("[yellow bold underline]4-bit Colors[/]").RuleStyle("grey").LeftAligned());
+                AnsiConsole.Write(new Rule("[yellow bold underline]4-bit Colors[/]").RuleStyle("grey").LeftAligned());
                 AnsiConsole.WriteLine();
 
                 for (var i = 0; i < 16; i++)
@@ -66,7 +66,7 @@ namespace Spectre.Console.Examples
             {
                 AnsiConsole.ResetColors();
                 AnsiConsole.WriteLine();
-                AnsiConsole.Render(new Rule("[yellow bold underline]8-bit Colors[/]").RuleStyle("grey").LeftAligned());
+                AnsiConsole.Write(new Rule("[yellow bold underline]8-bit Colors[/]").RuleStyle("grey").LeftAligned());
                 AnsiConsole.WriteLine();
 
                 for (var i = 0; i < 16; i++)
@@ -93,10 +93,10 @@ namespace Spectre.Console.Examples
             {
                 AnsiConsole.ResetColors();
                 AnsiConsole.WriteLine();
-                AnsiConsole.Render(new Rule("[yellow bold underline]24-bit Colors[/]").RuleStyle("grey").LeftAligned());
+                AnsiConsole.Write(new Rule("[yellow bold underline]24-bit Colors[/]").RuleStyle("grey").LeftAligned());
                 AnsiConsole.WriteLine();
 
-                AnsiConsole.Render(new ColorBox(width: 80, height: 15));
+                AnsiConsole.Write(new ColorBox(width: 80, height: 15));
             }
         }
     }

examples/Console/Columns/Columns.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <ExampleTitle>Columns</ExampleTitle>
     <ExampleDescription>Demonstrates how to render data into columns.</ExampleDescription>
     <ExampleGroup>Widgets</ExampleGroup>

examples/Console/Columns/Program.cs

@@ -16,7 +16,7 @@ namespace Spectre.Console.Examples
             }
 
             // Render all cards in columns
-            AnsiConsole.Render(new Columns(cards));
+            AnsiConsole.Write(new Columns(cards));
         }
 
         private static string GetCardContent(User user)

examples/Console/Cursor/Cursor.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <ExampleTitle>Cursor</ExampleTitle>
     <ExampleDescription>Demonstrates how to move the cursor.</ExampleDescription>
     <ExampleGroup>Misc</ExampleGroup>

examples/Console/Emojis/Emojis.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <ExampleTitle>Emojis</ExampleTitle>
     <ExampleDescription>Demonstrates how to render emojis.</ExampleDescription>
     <ExampleGroup>Misc</ExampleGroup>

examples/Console/Emojis/Program.cs

@@ -14,7 +14,7 @@ namespace Spectre.Console.Examples
 
         private static void RenderEmoji()
         {
-            AnsiConsole.Render(
+            AnsiConsole.Write(
                 new Panel("[yellow]Hello :globe_showing_europe_africa:![/]")
                     .RoundedBorder());
         }

examples/Console/Exceptions/Exceptions.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <ExampleTitle>Exceptions</ExampleTitle>
     <ExampleDescription>Demonstrates how to render formatted exceptions.</ExampleDescription>
     <ExampleGroup>Misc</ExampleGroup>

examples/Console/Exceptions/Program.cs

@@ -14,17 +14,17 @@ namespace Spectre.Console.Examples
             catch (Exception ex)
             {
                 AnsiConsole.WriteLine();
-                AnsiConsole.Render(new Rule("Default").LeftAligned());
+                AnsiConsole.Write(new Rule("Default").LeftAligned());
                 AnsiConsole.WriteLine();
                 AnsiConsole.WriteException(ex);
 
                 AnsiConsole.WriteLine();
-                AnsiConsole.Render(new Rule("Compact").LeftAligned());
+                AnsiConsole.Write(new Rule("Compact").LeftAligned());
                 AnsiConsole.WriteLine();
                 AnsiConsole.WriteException(ex, ExceptionFormats.ShortenEverything | ExceptionFormats.ShowLinks);
 
                 AnsiConsole.WriteLine();
-                AnsiConsole.Render(new Rule("Compact + Custom colors").LeftAligned());
+                AnsiConsole.Write(new Rule("Compact + Custom colors").LeftAligned());
                 AnsiConsole.WriteLine();
                 AnsiConsole.WriteException(ex, new ExceptionSettings
                 {

examples/Console/Figlet/Figlet.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
     <ExampleTitle>Figlet</ExampleTitle>
     <ExampleDescription>Demonstrates how to render FIGlet text.</ExampleDescription>
     <ExampleGroup>Widgets</ExampleGroup>