Modified Markdown intended to be read in GitHub to utilize [!NOTE] format (#5776)

Author: MichaelSimons

.markdownlint.json

@@ -9,7 +9,6 @@
     "MD022": false, // blanks-around-headings Headings should be surrounded by blank lines
     "MD024": false, // no-duplicate-heading Multiple headings with the same content
     "MD025": false, // single-title/single-h1 Multiple top-level headings in the same document
-    "MD028": false, // no-blanks-blockquote Blank line inside blockquote
     "MD034": false, // no-bare-urls Bare URL used
     "MD036": false, // no-emphasis-as-heading Emphasis used instead of a heading
     "MD041": false, // first-line-heading/first-line-h1 First line in a file should be a top-level heading

documentation/image-artifact-details.md

@@ -100,8 +100,9 @@ FROM mcr.microsoft.com/cbl-mariner/base/core:2.0
 COPY --from=distroless / /distroless
 ```
 
-Note the last instruction copies the entire contents of the distroless container's filesystem to the `/distroless` directory in the wrapper.
-This will be the target location used when executing commands.
+> [!NOTE]
+> The last instruction copies the entire contents of the distroless container's filesystem to the `/distroless` directory in the wrapper.
+> This will be the target location used when executing commands.
 
 Next, build the Dockerfile, specifying the distroless image tag you wish to inspect:
 

documentation/scenarios/nuget-credentials.md

@@ -207,7 +207,8 @@ COPY --from=build /app/out ./
 ENTRYPOINT ["dotnet", "dotnetapp.dll"]
 ```
 
-_Note that a script is called to install the Credential Provider. When `dotnet restore` is run, the Credential Provider is invoked to resolve the credentials and it retrieves them from the `VSS_NUGET_EXTERNAL_FEED_ENDPOINTS` environment variable._
+> [!NOTE]
+> A script is called to install the Credential Provider. When `dotnet restore` is run, the Credential Provider is invoked to resolve the credentials and it retrieves them from the `VSS_NUGET_EXTERNAL_FEED_ENDPOINTS` environment variable.
 
 Before running `docker build`, first populate the `FEED_ACCESSTOKEN` environment variable with a [personal access token](https://docs.microsoft.com/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate). Then, this Dockerfile would be built using this command:
 

documentation/supported-tags.md

@@ -52,7 +52,9 @@ They include:
 - Debian, unless specified (like `8.0-alpine`).
 - All [supported architectures](supported-platforms.md#architectures).
 
-> Note: Since .NET 8, these multi-platform tags **specifically exclude all Windows versions** due to `containerd`'s platform matching algorithm for Windows hosts.
+> [!NOTE]
+> Since .NET 8, these multi-platform tags **specifically exclude all Windows versions** due to `containerd`'s platform matching algorithm for Windows hosts.
+
 Please see [#4492 (Switch multi-platform tags to Linux only)](https://github.com/dotnet/dotnet-docker/issues/4492) for more context.
 If you are using Windows, you will need to explicitly specify an OS Version with a single-platform tag like so:
 
@@ -90,11 +92,11 @@ Examples:
 - `6.0-alpine`
 - `8.0-alpine`
 
-Notes:
-
-- New versions of Alpine will be published with version-specific tags (e.g. `6.0-alpine3.20`).
-- Floating tag (e.g. `6.0-alpine`) will be updated with the new Alpine version a month later.
-- Tag changes will be [announced](https://github.com/dotnet/dotnet-docker/discussions/categories/announcements) so that users know when the tags they want are available.
+> [!NOTE]
+>
+> - New versions of Alpine will be published with version-specific tags (e.g. `6.0-alpine3.20`).
+> - Floating tag (e.g. `6.0-alpine`) will be updated with the new Alpine version a month later.
+> - Tag changes will be [announced](https://github.com/dotnet/dotnet-docker/discussions/categories/announcements) so that users know when the tags they want are available.
 
 ### `<Major.Minor.Patch .NET Version>`
 
@@ -131,10 +133,10 @@ For more information, see the [Image Variants documentation](./image-variants.md
 
 These "floating version" `latest` tag references an image with the latest `Major.Minor.Patch` .NET version, while operating system and architecture will be chosen based on the requesting environment.
 
-Notes:
-
-- The `latest` tag references the latest stable release.
-- In the `nightly` image repo, it may reference the latest preview release.
+> [!NOTE]
+>
+> - The `latest` tag references the latest stable release.
+> - In the `nightly` image repo, it may reference the latest preview release.
 
 ## Tag policies
 
@@ -149,12 +151,12 @@ Examples:
 - `6.0.32`
 - `8.0.7-alpine3.20`
 
-Notes:
-
-- These tags are considered _fixed tags_ since they reference a specific .NET patch version.
-- They are updated in response to base image updates (like a Debian base image) for the supported life of the image (typically one month).
-- The .NET components within the image will not be updated.
-- In the rare event that .NET components are updated before the next regular .NET service release, then a new image with a `-1` tag will be created. The same practice will repeat itself if necessary (with `-2` and then `-3` tags).
+> [!NOTE]
+>
+> - These tags are considered _fixed tags_ since they reference a specific .NET patch version.
+> - They are updated in response to base image updates (like a Debian base image) for the supported life of the image (typically one month).
+> - The .NET components within the image will not be updated.
+> - In the rare event that .NET components are updated before the next regular .NET service release, then a new image with a `-1` tag will be created. The same practice will repeat itself if necessary (with `-2` and then `-3` tags).
 
 ### Floating version tags
 
@@ -165,11 +167,11 @@ Examples:
 - `6.0`
 - `8.0-alpine3.20`
 
-Notes:
-
-- These tags are considered _floating tags_ since they do not reference a specific .NET patch version.
-- They are updated in response to base image updates (like a Debian base image) for the supported life of the .NET release.
-- The .NET components within the image will be updated, which typically occurs on Patch Tuesday.
+> [!NOTE]
+>
+> - These tags are considered _floating tags_ since they do not reference a specific .NET patch version.
+> - They are updated in response to base image updates (like a Debian base image) for the supported life of the .NET release.
+> - The .NET components within the image will be updated, which typically occurs on Patch Tuesday.
 
 ### OS tags and base image updates
 
@@ -180,12 +182,12 @@ Examples:
 - `6.0-jammy`
 - `8.0-alpine3.20`
 
-Notes:
-
-- These tags are updated in response to base image updates (like an Ubuntu base image) for the supported life of the .NET release.
-- Digest pinning is required to request a specific patch of an operating system (e.g. `mcr.microsoft.com/dotnet/runtime@sha256:4d3d5a5131a0621509ab8a75f52955f2d0150972b5c5fb918e2e59d4cb9a9823`).
-- If an image is only available for one operating system, then the operating system will be omitted from the tag.
-- For [Debian](https://en.wikipedia.org/wiki/Debian_version_history) and [Ubuntu](https://en.wikipedia.org/wiki/Ubuntu_version_history) images, release codenames are used instead of version numbers.
+> [!NOTE]
+>
+> - These tags are updated in response to base image updates (like an Ubuntu base image) for the supported life of the .NET release.
+> - Digest pinning is required to request a specific patch of an operating system (e.g. `mcr.microsoft.com/dotnet/runtime@sha256:4d3d5a5131a0621509ab8a75f52955f2d0150972b5c5fb918e2e59d4cb9a9823`).
+> - If an image is only available for one operating system, then the operating system will be omitted from the tag.
+> - For [Debian](https://en.wikipedia.org/wiki/Debian_version_history) and [Ubuntu](https://en.wikipedia.org/wiki/Ubuntu_version_history) images, release codenames are used instead of version numbers.
 
 ### Windows tags
 

samples/aspnetapp/README.md

@@ -2,7 +2,8 @@
 
 This sample demonstrates how to build container images for ASP.NET Core web apps. See [.NET Docker Samples](../README.md) for more samples.
 
-> Note: .NET 8 container images use port `8080`, by default. Previous .NET versions used port `80`. The instructions for the sample assume the use of port `8080`.
+> [!NOTE]
+> .NET 8 container images use port `8080`, by default. Previous .NET versions used port `80`. The instructions for the sample assume the use of port `8080`.
 
 ## Run the sample image
 
@@ -39,7 +40,8 @@ Supported with .NET Core 1.0+
 ASPNETCORE_URLS=http://+:80 
 ```
 
-> Note: `ASPNETCORE_URLS` overwrites `ASPNETCORE_HTTP_PORTS` if set.
+> [!NOTE]
+> `ASPNETCORE_URLS` overwrites `ASPNETCORE_HTTP_PORTS` if set.
 
 These environment variables are used in [.NET 8](https://github.com/dotnet/dotnet-docker/blob/6da64f31944bb16ecde5495b6a53fc170fbe100d/src/runtime-deps/8.0/bookworm-slim/amd64/Dockerfile#L7C5-L7C31) and [.NET 6](https://github.com/dotnet/dotnet-docker/blob/6da64f31944bb16ecde5495b6a53fc170fbe100d/src/runtime-deps/6.0/bookworm-slim/amd64/Dockerfile#L5) Dockerfiles, respectively.
 
@@ -64,7 +66,8 @@ info: Microsoft.Hosting.Lifetime[0]
 
 After the application starts, navigate to `http://localhost:8000` in your web browser. You can also view the ASP.NET Core site running in the container from another machine with a local IP address such as `http://192.168.1.18:8000`.
 
-> Note: ASP.NET Core apps (in official images) listen to [port 8080 by default](https://github.com/dotnet/dotnet-docker/blob/6da64f31944bb16ecde5495b6a53fc170fbe100d/src/runtime-deps/8.0/bookworm-slim/amd64/Dockerfile#L7), starting with .NET 8. The [`-p` argument](https://docs.docker.com/engine/reference/commandline/run/#publish) in these examples maps host port `8000` to container port `8080` (`host:container` mapping). The container will not be accessible without this mapping. ASP.NET Core can be [configured to listen on a different or additional port](https://learn.microsoft.com/aspnet/core/fundamentals/servers/kestrel/endpoints).
+> [!NOTE]
+> ASP.NET Core apps (in official images) listen to [port 8080 by default](https://github.com/dotnet/dotnet-docker/blob/6da64f31944bb16ecde5495b6a53fc170fbe100d/src/runtime-deps/8.0/bookworm-slim/amd64/Dockerfile#L7), starting with .NET 8. The [`-p` argument](https://docs.docker.com/engine/reference/commandline/run/#publish) in these examples maps host port `8000` to container port `8080` (`host:container` mapping). The container will not be accessible without this mapping. ASP.NET Core can be [configured to listen on a different or additional port](https://learn.microsoft.com/aspnet/core/fundamentals/servers/kestrel/endpoints).
 
 You can see the app running via `docker ps`.
 

samples/build-for-a-platform.md

@@ -79,7 +79,8 @@ The `--platform` argument is the best way to specify the desired architecture. T
 
 In addition, Docker [Buildkit exposes multiple environment variables](https://github.com/dotnet/dotnet-docker/pull/4387#issuecomment-1416565213) that can be used to further conditionalize behavior. These environment variables can be controlled with the pattern demonstrated in [Dockerfile](https://github.com/mthalman/dredge/blob/main/src/Valleysoft.Dredge/Dockerfile). As mentioned, .NET doesn't support being run in emulation. The pattern in that Dockerfile results in the SDK always being run natively while the final image is affected by the `--platform` switch. This model also has the best performance since the bulk of computation is run natively.
 
-> Note: We are enabling the following model in a future release: https://github.com/dotnet/dotnet-docker/issues/4388#issuecomment-1421401384.
+> [!NOTE]
+> We are enabling the following model in a future release: https://github.com/dotnet/dotnet-docker/issues/4388#issuecomment-1421401384.
 
 ## .NET and QEMU
 

samples/complexapp/README.md

@@ -45,7 +45,8 @@ There are two primary ways to test within the workflow of an application contain
 
 This is different than running tests within a [.NET SDK container](../run-tests-in-sdk-container.md), which establishes a generic environment (which also works well). The rest of this document is focused on running tests within the same container environment as the application.
 
-> Note: See [Establishing docker environment](../establishing-docker-environment.md) for more information on correctly configuring Dockerfiles and `docker build` commands.
+> [!NOTE]
+> See [Establishing docker environment](../establishing-docker-environment.md) for more information on correctly configuring Dockerfiles and `docker build` commands.
 
 ## Running tests as an opt-in stage
 

samples/deploy-container-to-aci.md

@@ -18,7 +18,8 @@ docker build --pull -t aspnetapp -f Dockerfile .
 
 Create an ACR registry per the instructions at [Push Docker Images to Azure Container Registry](push-image-to-acr.md). The following is a summarized version of those instructions.
 
-> Note: Change the password location and the user account ("rich" and "richlander") example values in your environment.
+> [!NOTE]
+> Change the password location and the user account ("rich" and "richlander") example values in your environment.
 
 ```console
 az login

samples/host-aspnetcore-https.md

@@ -59,10 +59,9 @@ dotnet dev-certs https --trust
 ```
 
 > [!NOTE]
-> `dotnet dev-certs https --trust` is only supported on macOS and Windows. You need to trust certs on Linux in the way that is supported by your distro. It is likely that you need to trust the certificate in your browser.
-
-> [!NOTE]
-> `<CREDENTIAL_PLACEHOLDER>` is used as a stand-in for a password of your own choosing.
+>
+> - `dotnet dev-certs https --trust` is only supported on macOS and Windows. You need to trust certs on Linux in the way that is supported by your distro. It is likely that you need to trust the certificate in your browser.
+> - `<CREDENTIAL_PLACEHOLDER>` is used as a stand-in for a password of your own choosing.
 
 Run the container image with ASP.NET Core configured for HTTPS:
 

samples/kubernetes/graceful-shutdown/graceful-shutdown.md

@@ -107,7 +107,8 @@ public class DelayedShutdownHostLifetime : IHostLifetime, IDisposable
 }
 ```
 
-> Note: do not confuse `IHostLifetime` with `IHostApplicationLifetime`--they are related, but different interfaces. It is the `IHostLifetime` instance that listens for signals, including `SIGTERM`, and once a signal arrives, it calls into `IHostApplicationLifetime` instance to orchestrate application shutdown. For more information see [generic host shutdown documentation](https://learn.microsoft.com/dotnet/core/extensions/generic-host#host-shutdown)
+> [!NOTE]
+> Do not confuse `IHostLifetime` with `IHostApplicationLifetime`--they are related, but different interfaces. It is the `IHostLifetime` instance that listens for signals, including `SIGTERM`, and once a signal arrives, it calls into `IHostApplicationLifetime` instance to orchestrate application shutdown. For more information see [generic host shutdown documentation](https://learn.microsoft.com/dotnet/core/extensions/generic-host#host-shutdown)
 
 Make ASP.NET use `DelayedShutdownHostLifetime` by adding it to the dependency injection container:
 

samples/push-image-to-acr.md

@@ -26,7 +26,8 @@ docker run --rm dotnetapp
 
 The following example demonstrates how to create a private ACR Registry. Once an image is in ACR, it is easy to deploy it to ACI.
 
-> Note: The instructions use example values that need to be changed to for your environment, specifically the password location, and the user account. More simply, make sure to change "rich" and "richlander" to something else.
+> [!NOTE]
+> The instructions use example values that need to be changed to for your environment, specifically the password location, and the user account. More simply, make sure to change "rich" and "richlander" to something else.
 
 ```console
 az login

samples/push-image-to-dockerhub.md

@@ -34,7 +34,8 @@ You need to [login to Docker Hub](https://docs.docker.com/docker-hub/accounts/)
 
 There are a couple ways of passing a password to `docker login`. These instructions [pass the password to stdin](https://github.com/docker/cli/pull/218) via a text file called password-dh.txt. Make sure to save to a location not managed by source control (to avoid accidental disclosure).
 
-> Note: The instructions use example values that need to be changed to for your environment, specifically the password location, and the user account. More simply, make sure to change "rich" and "richlander" to something else.
+> [!NOTE]
+> The instructions use example values that need to be changed to for your environment, specifically the password location, and the user account. More simply, make sure to change "rich" and "richlander" to something else.
 
 Login on Windows:
 

samples/releasesapi/README.md

@@ -2,7 +2,8 @@
 
 This app demonstrates publishing an app as [native AOT](https://learn.microsoft.com/dotnet/core/deploying/native-aot/) in containers.
 
-> Note: The base images used by this sample are in preview.
+> [!NOTE]
+> The base images used by this sample are in preview.
 
 A similar console app sample supports [single file deployment](../releasesapp/README.md) (non-AOT scenario). This app could also be deployed that way.