Use docfx Alerts

Author: bkoelman

docs/request-examples/index.md

@@ -4,7 +4,8 @@ These requests have been generated against the "GettingStarted" application and
 
 All of these requests have been created using out-of-the-box features.
 
-_Note that cURL requires "[" and "]" in URLs to be escaped._
+> [!NOTE]
+> curl requires "[" and "]" in URLs to be escaped.
 
 # Reading data
 

docs/usage/caching.md

@@ -59,8 +59,8 @@ ETag: "356075D903B8FE8D9921201A7E7CD3F9"
   "data": [ ... ]
 }
 ```
-
-**Note:** To just poll for changes (without fetching them), send a HEAD request instead:
+> [!TIP]
+> To just poll for changes (without fetching them), send a HEAD request instead.
 
 ```http
 HEAD /articles?sort=-lastModifiedAt HTTP/1.1

docs/usage/extensibility/layer-overview.md

@@ -23,8 +23,6 @@ on your needs, you may want to replace other parts by deriving from the built-in
 
 ## Replacing injected services
 
-**Note:** If you're using [auto-discovery](~/usage/resource-graph.md#auto-discovery), then resource services, repositories and resource definitions will be automatically registered for you.
-
 Replacing built-in services is done on a per-resource basis and can be done at startup.
 For convenience, extension methods are provided to register layers on all their implemented interfaces.
 
@@ -37,3 +35,6 @@ builder.Services.AddResourceDefinition<ProductDefinition>();
 builder.Services.AddScoped<IResourceFactory, CustomResourceFactory>();
 builder.Services.AddScoped<IResponseModelAdapter, CustomResponseModelAdapter>();
 ```
+
+> [!TIP]
+> If you're using [auto-discovery](~/usage/resource-graph.md#auto-discovery), then resource services, repositories and resource definitions will be automatically registered for you.

docs/usage/extensibility/repositories.md

@@ -13,13 +13,14 @@ builder.Services.AddScoped<IResourceWriteRepository<Article, int>, ArticleReposi
 In v4.0 we introduced an extension method that you can use to register a resource repository on all of its JsonApiDotNetCore interfaces.
 This is helpful when you implement (a subset of) the resource interfaces and want to register them all in one go.
 
-**Note:** If you're using [auto-discovery](~/usage/resource-graph.md#auto-discovery), this happens automatically.
-
 ```c#
 // Program.cs
 builder.Services.AddResourceRepository<ArticleRepository>();
 ```
 
+> [!TIP]
+> If you're using [auto-discovery](~/usage/resource-graph.md#auto-discovery), then resource services, repositories and resource definitions will be automatically registered for you.
+
 A sample implementation that performs authorization might look like this.
 
 All of the methods in EntityFrameworkCoreRepository will use the `GetAll()` method to get the `DbSet<TResource>`, so this is a good method to apply filters such as user or tenant authorization.

docs/usage/extensibility/resource-definitions.md

@@ -7,19 +7,19 @@ They are resolved from the dependency injection container, so you can inject dep
 
 In v4.2 we introduced an extension method that you can use to register your resource definition.
 
-**Note:** If you're using [auto-discovery](~/usage/resource-graph.md#auto-discovery), this happens automatically.
-
 ```c#
 // Program.cs
 builder.Services.AddResourceDefinition<ArticleDefinition>();
 ```
 
-**Note:** Prior to the introduction of auto-discovery (in v3), you needed to register the
-resource definition on the container yourself:
+> [!TIP]
+> If you're using [auto-discovery](~/usage/resource-graph.md#auto-discovery), then resource services, repositories and resource definitions will be automatically registered for you.
 
-```c#
-builder.Services.AddScoped<ResourceDefinition<Article, int>, ArticleDefinition>();
-```
+> [!NOTE]
+> Prior to the introduction of auto-discovery (in v3), you needed to register the resource definition on the container yourself:
+> ```c#
+> builder.Services.AddScoped<ResourceDefinition<Article, int>, ArticleDefinition>();
+> ```
 
 ## Customizing queries
 
@@ -37,7 +37,8 @@ from Entity Framework Core `IQueryable` execution.
 There are some cases where you want attributes or relationships conditionally excluded from your resource response.
 For example, you may accept some sensitive data that should only be exposed to administrators after creation.
 
-**Note:** to exclude fields unconditionally, [attribute capabilities](~/usage/resources/attributes.md#capabilities) and [relationship capabilities](~/usage/resources/relationships.md#capabilities) can be used instead.
+> [!NOTE]
+> To exclude fields unconditionally, [attribute capabilities](~/usage/resources/attributes.md#capabilities) and [relationship capabilities](~/usage/resources/relationships.md#capabilities) can be used instead.
 
 ```c#
 public class UserDefinition : JsonApiResourceDefinition<User, int>
@@ -218,7 +219,8 @@ _since v3_
 You can define additional query string parameters with the LINQ expression that should be used.
 If the key is present in a query string, the supplied LINQ expression will be added to the database query.
 
-Note this directly influences the Entity Framework Core `IQueryable`. As opposed to using `OnApplyFilter`, this enables the full range of Entity Framework Core operators. 
+> [!NOTE]
+> This directly influences the Entity Framework Core `IQueryable`. As opposed to using `OnApplyFilter`, this enables the full range of Entity Framework Core operators. 
 But it only works on primary resource endpoints (for example: /articles, but not on /blogs/1/articles or /blogs?include=articles).
 
 ```c#

docs/usage/extensibility/services.md

@@ -135,13 +135,14 @@ builder.Services.AddScoped<IDeleteService<Article, int>, ArticleService>();
 In v3.0 we introduced an extension method that you can use to register a resource service on all of its JsonApiDotNetCore interfaces.
 This is helpful when you implement (a subset of) the resource interfaces and want to register them all in one go.
 
-**Note:** If you're using [auto-discovery](~/usage/resource-graph.md#auto-discovery), this happens automatically.
-
 ```c#
 // Program.cs
 builder.Services.AddResourceService<ArticleService>();
 ```
 
+> [!TIP]
+> If you're using [auto-discovery](~/usage/resource-graph.md#auto-discovery), then resource services, repositories and resource definitions will be automatically registered for you.
+
 Then on your model, pass in the set of endpoints to expose (the ones that you've registered services for):
 
 ```c#

docs/usage/options.md

@@ -24,7 +24,11 @@ options.AllowClientGeneratedIds = true;
 
 The default page size used for all resources can be overridden in options (10 by default). To disable paging, set it to `null`.
 The maximum page size and number allowed from client requests can be set too (unconstrained by default).
-You can also include the total number of resources in each response. Note that when using this feature, it does add some query overhead since we have to also request the total number of resources.
+
+You can also include the total number of resources in each response.
+
+> [!NOTE]
+> Including the total number of resources adds some overhead, because the count is fetched in a separate query.
 
 ```c#
 options.DefaultPageSize = new PageSize(25);

docs/usage/reading/filtering.md

@@ -69,7 +69,8 @@ GET /articles?include=author,tags&filter=equals(author.lastName,'Smith')&filter[
 
 In the above request, the first filter is applied on the collection of articles, while the second one is applied on the nested collection of tags.
 
-Note this does **not** hide articles without any matching tags! Use the `has` function with a filter condition (see below) to accomplish that.
+> [!WARNING]
+> The request above does **not** hide articles without any matching tags! Use the `has` function with a filter condition (see below) to accomplish that.
 
 Putting it all together, you can build quite complex filters, such as:
 

docs/usage/reading/sparse-fieldset-selection.md

@@ -36,7 +36,8 @@ Example for both top-level and relationship:
 GET /articles?include=author&fields[articles]=title,body,author&fields[authors]=name HTTP/1.1
 ```
 
-Note that in the last example, the `author` relationship is also added to the `articles` fieldset, so that the relationship from article to author is returned.
+> [!NOTE]
+> In the last example, the `author` relationship is also added to the `articles` fieldset, so that the relationship from article to author is returned.
 When omitted, you'll get the included resources returned, but without full resource linkage (as described [here](https://jsonapi.org/examples/#sparse-fieldsets)).
 
 ## Overriding

docs/usage/resource-graph.md

@@ -3,7 +3,8 @@
 The `ResourceGraph` is a map of all the JSON:API resources and their relationships that your API serves.
 It is built at app startup and available as a singleton through Dependency Injection.
 
-**Note:** Prior to v4 this was called the `ContextGraph`.
+> [!NOTE]
+> Prior to v4, this was called the `ContextGraph`.
 
 ## Constructing The Graph
 

docs/usage/resources/index.md

@@ -8,7 +8,8 @@ public class Person : Identifiable<Guid>
 }
 ```
 
-**Note:** Earlier versions of JsonApiDotNetCore allowed a short-hand notation when `TId` is of type `int`. This was removed in v5.
+> [!NOTE]
+> Earlier versions of JsonApiDotNetCore allowed a short-hand notation when `TId` is of type `int`. This was removed in v5.
 
 If you need to attach annotations or attributes on the `Id` property, you can override the virtual property.
 

docs/usage/resources/relationships.md

@@ -277,7 +277,8 @@ This can be overridden per relationship.
 Indicates whether the relationship can be returned in responses. When not allowed and requested using `?fields[]=`, it results in an HTTP 400 response.
 Otherwise, the relationship (and its related resources, when included) are silently omitted.
 
-Note that this setting does not affect retrieving the related resources directly.
+> [!WARNING]
+> This setting does not affect retrieving the related resources directly.
 
 ```c#
 #nullable enable

docs/usage/writing/creating.md

@@ -71,4 +71,6 @@ POST /articles?include=owner&fields[people]=firstName HTTP/1.1
 }
 ```
 
-After the resource has been created on the server, it is re-fetched from the database using the specified query string parameters and returned to the client.
+> [!NOTE]
+> After the resource has been created on the server, it is re-fetched from the database using the specified query string parameters and returned to the client.
+> However, the used query string parameters only have an effect when `200 OK` is returned.

docs/usage/writing/updating.md

@@ -21,12 +21,14 @@ POST /articles HTTP/1.1
 This preserves the values of all other unsent attributes and is called a *partial patch*.
 
 When only the attributes that were sent in the request have changed, the server returns `204 No Content`.
-But if additional attributes have changed (for example, by a database trigger that refreshes the last-modified date) the server returns `200 OK`, along with all attributes of the updated resource.
+But if additional attributes have changed (for example, by a database trigger or [resource definition](~/usage/extensibility/resource-definitions.md) that refreshes the last-modified date) the server returns `200 OK`, along with all attributes of the updated resource.
 
 ## Updating resource relationships
 
 Besides its attributes, the relationships of a resource can be changed using a PATCH request too.
-Note that all resources being assigned in a relationship must already exist.
+
+> [!NOTE]
+> All resources being assigned in a relationship must already exist.
 
 When updating a HasMany relationship, the existing set is replaced by the new set. See below on how to add/remove resources.
 
@@ -65,7 +67,8 @@ PATCH /articles/1 HTTP/1.1
 
 A HasOne relationship can be cleared by setting `data` to `null`, while a HasMany relationship can be cleared by setting it to an empty array.
 
-By combining the examples above, both attributes and relationships can be updated using a single PATCH request.
+> [!TIP]
+> By combining the examples above, both attributes and relationships can be updated using a single PATCH request.
 
 ## Response body
 
@@ -79,8 +82,9 @@ PATCH /articles/1?include=owner&fields[people]=firstName HTTP/1.1
 }
 ```
 
-After the resource has been updated on the server, it is re-fetched from the database using the specified query string parameters and returned to the client.
-Note this only has an effect when `200 OK` is returned.
+> [!NOTE]
+> After the resource has been updated on the server, it is re-fetched from the database using the specified query string parameters and returned to the client.
+> However, the used query string parameters only have an effect when `200 OK` is returned.
 
 # Updating relationships