diff --git a/cmd/docs-gen/main.go b/cmd/docs-gen/main.go
index fc6ab95..054826d 100644
--- a/cmd/docs-gen/main.go
+++ b/cmd/docs-gen/main.go
@@ -32,7 +32,7 @@ const (
 	firstParagraph = `# API
 This document is a reference of the API types introduced by Kilo.
 
-> Note this document is generated from code comments. When contributing a change to this document, please do so by changing the code comments.`
+> **Note**: this document is generated from code comments. When contributing a change to this document, please do so by changing the code comments.`
 )
 
 var (
diff --git a/docs/annotations.md b/docs/annotations.md
index 548671d..29037bf 100644
--- a/docs/annotations.md
+++ b/docs/annotations.md
@@ -36,7 +36,7 @@ In some situations it may be desirable to manually select the leader for a locat
  * _firewall_: Kilo requires an open UDP port, which defaults to 51820, to communicate between locations; if only one node is configured to have that port open, then that node should be given the leader annotation;
  * _bandwidth_: if certain nodes in the cluster have a higher bandwidth or lower latency Internet connection, then those nodes should be given the leader annotation.
 
-_Note_: multiple nodes within a single location can be given the leader annotation; in this case, Kilo will select one leader from the set of annotated nodes. 
+> **Note**: multiple nodes within a single location can be given the leader annotation; in this case, Kilo will select one leader from the set of annotated nodes.
 
 ### location
 Kilo allows nodes in different logical or physical locations to route packets to one-another.
@@ -44,7 +44,7 @@ In order to know what connections to create, Kilo needs to know which nodes are
 Kilo will try to infer each node's location from the [topology.kubernetes.io/region](https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/#topologykubernetesioregion) node label.
 If the label is not present for a node, for example if running a bare-metal cluster or on an unsupported cloud provider, then the location annotation should be specified.
 
-_Note_: all nodes without a defined location will be considered to be in the default location `""`.
+> **Note**: all nodes without a defined location will be considered to be in the default location `""`.
 
 ### persistent-keepalive
 In certain deployments, cluster nodes may be located behind NAT or a firewall, e.g. edge nodes located behind a commodity router.
diff --git a/docs/api.md b/docs/api.md
index 0dc13f5..dbb3651 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1,7 +1,7 @@
 # API
 This document is a reference of the API types introduced by Kilo.
 
-> Note this document is generated from code comments. When contributing a change to this document, please do so by changing the code comments.
+> **Note**: this document is generated from code comments. When contributing a change to this document, please do so by changing the code comments.
 
 ## Table of Contents
 * [DNSOrIP](#dnsorip)
diff --git a/docs/building_kilo.md b/docs/building_kilo.md
index 13d1f11..526d593 100644
--- a/docs/building_kilo.md
+++ b/docs/building_kilo.md
@@ -55,7 +55,7 @@ To execute basic end to end tests, run:
 ```shell
 make e2e
 ```
-__Note__: The end to end tests are currently flaky, so try running them again if they fail.
+> **Note**: The end to end tests are currently flaky, so try running them again if they fail.
 
 To instead run all of the tests with a single command, run:
 ```shell
diff --git a/docs/building_website.md b/docs/building_website.md
index 415b48f..fc29362 100644
--- a/docs/building_website.md
+++ b/docs/building_website.md
@@ -41,4 +41,4 @@ Then, regenerate the markdown for the website with the command:
 make website/docs/README.md
 ```
 Edit `/website/sidebars.js` accordingly.
-_Note:_ The `id` in the header file `/website/docs/<new file>` must match the `id` specified in `website/sidebars.js`.
+> **Note**: The `id` in the header file `/website/docs/<new file>` must match the `id` specified in `website/sidebars.js`.
diff --git a/docs/userspace-wireguard.md b/docs/userspace-wireguard.md
index bd72587..d9135b4 100644
--- a/docs/userspace-wireguard.md
+++ b/docs/userspace-wireguard.md
@@ -13,7 +13,7 @@ One example of a userspace implementation of WireGuard is [BoringTun].
 In a homogeneous cluster where no node has the WireGuard kernel module, a userspace WireGuard implementation can be made available by deploying a DaemonSet.
 This DaemonSet creates a WireGuard interface that Kilo will manage.
 
-__Note:__ in order to avoid race conditions, `kg` needs to be passed the `--create-interface=false` flag. 
+> **Note**: in order to avoid race conditions, `kg` needs to be passed the `--create-interface=false` flag. 
 
 An example configuration for a K3s cluster with [BoringTun] can be applied with:
 
@@ -22,7 +22,7 @@ kubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/crd
 kubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/kilo-k3s-userspace.yaml
 ```
 
-__Note:__ even if some nodes have the WireGuard kernel module, this configuration will cause all nodes to use the userspace implementation of WireGuard.
+> **Note**: even if some nodes have the WireGuard kernel module, this configuration will cause all nodes to use the userspace implementation of WireGuard.
 
 ## Heterogeneous Clusters
 
@@ -39,6 +39,6 @@ It will also create two different DaemonSets with Kilo:
 1. `kilo` without userspace WireGuard; and
 1. `kilo-userspace` with [BoringTun] as a sidecar.
 
-__Note:__ because Kilo is dependant on nkml, nkml must be run on the host network before CNI is available and requires a kubeconfig in order to access the Kubernetes API.
+> **Note**: because Kilo is dependant on nkml, nkml must be run on the host network before CNI is available and requires a kubeconfig in order to access the Kubernetes API.
 
 [BoringTun]: https://github.com/cloudflare/boringtun