Feature/docs basic entries (#129)

* Re-arranged basic docs, added configuration page

* Altered ordering of pages

* Added changelog to docs

* Added about header to index

* Removed reference to code base

* Added quote type to docs config

* Made configuration docs into a directory

* Added HSTS and X-Frame-Options docs

* Added empty CSP docs file

* Added docs for the  X-Content-Type-Options header

* Added docs for the X-XSS-Protection header

* Linked to the CSP header docs in the X-Frame-Options header

* Fixed layout types on header config docs

* Fixed layout for CSP header config page

* Set header options files as children of the Configuration leaf

* Add docs build badge to readme

* Removed "layout" from front matter of all Configuration child pages

* Set parent on all Configuration child pages

* Added explicit default layout for all Configuration pages

* Added layout type to parent Configuration page

* Increased text coverage in Configuration page

docs/_config.yml

@@ -68,6 +68,9 @@ callouts:
   note:
     title: Note
     color: purple
+  suggestion:
+    title: Suggestion
+    color: green
   warning:
     title: Warning
     color: red

docs/configuration/index.md

@@ -4,17 +4,21 @@ nav_order: 2
 layout: page
 ---
 
-This Middleware uses the builder pattern to set up the header information, which is a compile time dependency. If you need to change the configuration, you will need to rebuild your application.
+OwaspHeaders.Core uses the builder pattern to set up the header information, which is a compile time dependency. If you need
+to change the configuration, you will need to rebuild your application. This is an intentional design choice, as a change
+to any of the HTTP headers that the OwaspHeaders.Core middleware injects should require the application to restart.
 
 ## Basic Configuration
 
-Adding the default configuration by adding the following to your `Program.cs` somewhere in the Middleware pipeline:
+Add the default configuration by adding the following to your `Program.cs` the Middleware pipeline as early as is
+possible for your application design:
 
 ```csharp
 app.UseSecureHeadersMiddleware();
 ```
 
-This will use the default configuration for the OwaspHeaders.Core middleware. The method looks like this:
+The above will use the default configuration for the OwaspHeaders.Core middleware. The method that sets the defaults looks
+like this:
 
 ```csharp
 public static SecureHeadersMiddlewareConfiguration BuildDefaultConfiguration() 
@@ -38,29 +42,64 @@ public static SecureHeadersMiddlewareConfiguration BuildDefaultConfiguration()
 {: .warning }
 The default configuration is INCREDIBLY restrictive.
 
+The following is an example of the response headers from version 9.1.0 (taken on November 19th, 2024) when using the
+default configuration: 
+
+```plaintext
+Cache-Control: max-age=31536000;private
+Strict-Transport-Security: max-age=31536000;includeSubDomains
+X-Frame-Options: DENY
+X-XSS-Protection: 0
+X-Content-Type-Options: nosniff
+Content-Security-Policy: script-src 'self';object-src 'self';block-all-mixed-content;upgrade-insecure-requests;
+X-Permitted-Cross-Domain-Policies: none;
+Referrer-Policy: no-referrer
+Cross-Origin-Resource-Policy: same-origin
+```
+
+{: .note }
+The above example contains only the headers added by the Middleware.
+
 ### Custom Configuration
 
-In order to use a custom configuration, follow the same pattern (perhaps creating your own extension method to encapsulate it). In the following example, we've created a static method called `CustomConfiguration` within a helpers class (called `CustomSecureHeaderExtensions`) which returns a completely custom configuration:
+In most cases (except for the [Content-Security Policy](./Content-Security-Policy.md)), the default configuration will
+be suitable. This is because it adds the OWASP recommended headers and values. Content-Security Policy is a non-trivial
+header, and is an allowlist for sources of content for the rendered page.
+
+In some cases, you may need to provide a custom configuration for the OwaspHeaders.Core middleware. In order to use a
+custom configuration, follow the same pattern.
+
+{: .suggestion }
+We recommend creating your own extension method to encapsulate your custom configuration.
+
+In the following example, we've created a static method called `CustomConfiguration` within a static extensions class
+(called `CustomSecureHeaderExtensions`). This custom method returns an instance of the `SecureHeadersMiddlewareConfiguration`
+which contains all the configuration required for a fictional custom configuration:
 
 ``` csharp
-public static CustomSecureHeaderExtensions
+using OwaspHeaders.Core.Enums;
+using OwaspHeaders.Core.Extensions;
+using OwaspHeaders.Core.Models;
+
+namespace OwaspHeaders.Core.Example.Helpers;
+
+public static class CustomSecureHeaderExtensions
 {
     public static SecureHeadersMiddlewareConfiguration CustomConfiguration()
     {
         return SecureHeadersMiddlewareBuilder
             .CreateBuilder()
             .UseHsts(1200, false)
             .UseContentDefaultSecurityPolicy()
-            .UsePermittedCrossDomainPolicy
-                (XPermittedCrossDomainOptionValue.masterOnly)
+            .UsePermittedCrossDomainPolicies(XPermittedCrossDomainOptionValue.masterOnly)
             .UseReferrerPolicy(ReferrerPolicyOptions.sameOrigin)
             .Build();
     }
 }
 ```
 
 {: .note }
-This is an example configuration
+This is an example configuration. It is recommended that you do NOT use this configuration in a production environment.
 
 Then consume it in the following manner, within your `Program.cs`'s Middleware pipeline:
 
@@ -69,3 +108,16 @@ app.UseSecureHeadersMiddleware(
     CustomSecureHeaderExtensions.CustomConfiguration()
 );
 ```
+
+This configuration will add the following headers to all server-generated responses:
+
+```plaintext
+Strict-Transport-Security: max-age=1200
+Content-Security-Policy: script-src 'self';object-src 'self';block-all-mixed-content;upgrade-insecure-requests;
+X-Permitted-Cross-Domain-Policies: master-only;
+Referrer-Policy: same-origin
+```
+
+{: .note }
+The above example contains only the headers added by the Middleware for the configuration provided in the
+`CustomConfiguration` extension method.

docs/index.md

@@ -33,7 +33,7 @@ app.UseSecureHeadersMiddleware();
 
 This will add a number of default HTTP headers to all responses from your server component.
 
-The following is an example of the response headers from version 9.0.0 (taken on November 19th, 2024)
+The following is an example of the response headers from version 9.1.0 (taken on November 19th, 2024)
 
 ```plaintext
 Cache-Control: max-age=31536000;private
@@ -50,7 +50,7 @@ Cross-Origin-Resource-Policy: same-origin
 {: .note }
 The above example contains only the headers added by the Middleware.
 
-For a more detailed explanation of how to use the middleware, including how to configure it, see [Using the Middleware]().
+For a more detailed explanation of how to use the middleware, including how to configure it, see [Configuration](./configuration).
 
 ## Server Header: A Warning