diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md
index 9ec5460a88..f16a2ad13e 100644
--- a/docs/deployment/docker.md
+++ b/docs/deployment/docker.md
@@ -141,8 +141,12 @@ browser at `http://localhost:7007`
 
 ## Multi-stage Build
 
-> NOTE: The `.dockerignore` is different in this setup, read on for more
-> details.
+:::note Note
+
+The `.dockerignore` is different in this setup, read on for more
+details.
+
+:::
 
 This section describes how to set up a multi-stage Docker build that builds the
 entire project within Docker. This is typically slower than a host build, but is
@@ -293,10 +297,14 @@ browser at `http://localhost:7007`
 
 ## Separate Frontend
 
-> NOTE: This is an optional step, and you will lose out on the features of the
-> `@backstage/plugin-app-backend` plugin. Most notably the frontend configuration
-> will no longer be injected by the backend, you will instead need to use the
-> correct configuration when building the frontend bundle.
+:::note Note
+
+This is an optional step, and you will lose out on the features of the
+`@backstage/plugin-app-backend` plugin. Most notably the frontend configuration
+will no longer be injected by the backend, you will instead need to use the
+correct configuration when building the frontend bundle.
+
+:::
 
 It is sometimes desirable to serve the frontend separately from the backend,
 either from a separate image or for example a static file serving provider. The
diff --git a/docs/deployment/index.md b/docs/deployment/index.md
index da2c29ba23..0524e71db8 100644
--- a/docs/deployment/index.md
+++ b/docs/deployment/index.md
@@ -13,8 +13,12 @@ This documentation shows common examples that may be useful when deploying
 Backstage for the first time, or for those without established deployment
 practices.
 
-> Note: The _easiest_ way to explore Backstage is to visit the
-> [live demo site](https://demo.backstage.io).
+:::note Note
+
+The _easiest_ way to explore Backstage is to visit the
+[live demo site](https://demo.backstage.io).
+
+:::
 
 At Spotify, we deploy software generally by:
 
diff --git a/docs/deployment/k8s.md b/docs/deployment/k8s.md
index 00bf7464e3..46ba273e14 100644
--- a/docs/deployment/k8s.md
+++ b/docs/deployment/k8s.md
@@ -107,10 +107,14 @@ $ echo -n "backstage" | base64
 YmFja3N0YWdl
 ```
 
-> Note: Secrets are base64-encoded, but not encrypted. Be sure to enable
-> [Encryption at Rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/)
-> for the cluster. For storing secrets in Git, consider
-> [SealedSecrets or other solutions](https://learnk8s.io/kubernetes-secrets-in-git).
+:::note Note
+
+Secrets are base64-encoded, but not encrypted. Be sure to enable
+[Encryption at Rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/)
+for the cluster. For storing secrets in Git, consider
+[SealedSecrets or other solutions](https://learnk8s.io/kubernetes-secrets-in-git).
+
+:::
 
 The secrets can now be applied to the Kubernetes cluster: