cppalliance · sgerbino · Mar 12, 2026 · Mar 12, 2026
diff --git a/doc/modules/ROOT/pages/3.tutorials/3a.echo-server.adoc b/doc/modules/ROOT/pages/3.tutorials/3a.echo-server.adoc
@@ -13,7 +13,9 @@ This tutorial builds a production-quality echo server using the `tcp_server`
 framework. We'll explore worker pools, connection lifecycle, and the launcher
 pattern.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio/tcp_server.hpp>
@@ -23,6 +25,7 @@ NOTE: Code snippets assume:
 namespace corosio = boost::corosio;
 namespace capy = boost::capy;
 ----
+====
 
 == Overview
 

diff --git a/doc/modules/ROOT/pages/3.tutorials/3b.http-client.adoc b/doc/modules/ROOT/pages/3.tutorials/3b.http-client.adoc
@@ -13,7 +13,9 @@ This tutorial builds a simple HTTP client that connects to a server, sends
 a GET request, and reads the response. You'll learn socket connection,
 composed I/O operations, and the exception-based error handling pattern.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio.hpp>
@@ -26,6 +28,7 @@ NOTE: Code snippets assume:
 namespace corosio = boost::corosio;
 namespace capy = boost::capy;
 ----
+====
 
 == Overview
 

diff --git a/doc/modules/ROOT/pages/3.tutorials/3c.dns-lookup.adoc b/doc/modules/ROOT/pages/3.tutorials/3c.dns-lookup.adoc
@@ -13,7 +13,9 @@ This tutorial builds a command-line DNS lookup tool similar to `nslookup`.
 You'll learn to use the asynchronous resolver to convert hostnames to IP
 addresses.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio.hpp>
@@ -23,6 +25,7 @@ NOTE: Code snippets assume:
 namespace corosio = boost::corosio;
 namespace capy = boost::capy;
 ----
+====
 
 == Overview
 

diff --git a/doc/modules/ROOT/pages/3.tutorials/3d.tls-context.adoc b/doc/modules/ROOT/pages/3.tutorials/3d.tls-context.adoc
@@ -13,13 +13,16 @@ This tutorial covers how to configure TLS contexts for secure connections.
 A `tls_context` stores certificates, keys, and settings that define how
 TLS connections are established and verified.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio/tls_context.hpp>
 
 namespace tls = boost::corosio::tls;
 ----
+====
 
 == Introduction
 

diff --git a/doc/modules/ROOT/pages/4.guide/4c.io-context.adoc b/doc/modules/ROOT/pages/4.guide/4c.io-context.adoc
@@ -13,12 +13,15 @@ The `io_context` class is the heart of Corosio. It's an event loop that
 processes asynchronous I/O operations, manages timers, and coordinates
 coroutine execution.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio/io_context.hpp>
 namespace corosio = boost::corosio;
 ----
+====
 
 == Overview
 

diff --git a/doc/modules/ROOT/pages/4.guide/4d.sockets.adoc b/doc/modules/ROOT/pages/4.guide/4d.sockets.adoc
@@ -13,7 +13,9 @@ The `tcp_socket` class provides asynchronous TCP networking. It supports
 connecting to servers, reading and writing data, and graceful connection
 management.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio/tcp_socket.hpp>
@@ -23,6 +25,7 @@ NOTE: Code snippets assume:
 namespace corosio = boost::corosio;
 namespace capy = boost::capy;
 ----
+====
 
 == Overview
 

diff --git a/doc/modules/ROOT/pages/4.guide/4e.tcp-acceptor.adoc b/doc/modules/ROOT/pages/4.guide/4e.tcp-acceptor.adoc
@@ -12,7 +12,9 @@
 The `tcp_acceptor` class listens for incoming TCP connections and accepts them
 into socket objects. It's the foundation for building TCP servers.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio/tcp_acceptor.hpp>
@@ -21,6 +23,7 @@ NOTE: Code snippets assume:
 
 namespace corosio = boost::corosio;
 ----
+====
 
 == Overview
 

diff --git a/doc/modules/ROOT/pages/4.guide/4f.endpoints.adoc b/doc/modules/ROOT/pages/4.guide/4f.endpoints.adoc
@@ -13,7 +13,9 @@ The `endpoint` class represents a network endpoint: an IP address (IPv4 or
 IPv6) combined with a port number. Endpoints are used for connecting sockets
 and binding acceptors.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio/endpoint.hpp>
@@ -22,6 +24,7 @@ NOTE: Code snippets assume:
 
 namespace corosio = boost::corosio;
 ----
+====
 
 == Overview
 

diff --git a/doc/modules/ROOT/pages/4.guide/4g.composed-operations.adoc b/doc/modules/ROOT/pages/4.guide/4g.composed-operations.adoc
@@ -12,7 +12,9 @@
 Corosio provides composed operations that build on the primitive `read_some()`
 and `write_some()` functions to provide higher-level guarantees.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio/read.hpp>
@@ -22,6 +24,7 @@ NOTE: Code snippets assume:
 namespace corosio = boost::corosio;
 namespace capy = boost::capy;
 ----
+====
 
 == The Problem with Primitives
 

diff --git a/doc/modules/ROOT/pages/4.guide/4h.timers.adoc b/doc/modules/ROOT/pages/4.guide/4h.timers.adoc
@@ -14,13 +14,16 @@ The `timer` class provides asynchronous delays and timeouts. It integrates
 with the I/O context to schedule operations at specific times or after
 durations.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio/timer.hpp>
 namespace corosio = boost::corosio;
 using namespace std::chrono_literals;
 ----
+====
 
 == Overview
 

diff --git a/doc/modules/ROOT/pages/4.guide/4i.signals.adoc b/doc/modules/ROOT/pages/4.guide/4i.signals.adoc
@@ -13,14 +13,17 @@ The `signal_set` class provides asynchronous signal handling. It allows
 coroutines to wait for operating system signals like SIGINT (Ctrl+C) or
 SIGTERM.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio/signal_set.hpp>
 #include <csignal>
 
 namespace corosio = boost::corosio;
 ----
+====
 
 == Overview
 

diff --git a/doc/modules/ROOT/pages/4.guide/4j.resolver.adoc b/doc/modules/ROOT/pages/4.guide/4j.resolver.adoc
@@ -13,12 +13,15 @@ The `resolver` class performs asynchronous DNS lookups, converting hostnames
 to IP addresses. It wraps the system's `getaddrinfo()` function with an
 asynchronous interface.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio/resolver.hpp>
 namespace corosio = boost::corosio;
 ----
+====
 
 == Overview
 

diff --git a/doc/modules/ROOT/pages/4.guide/4k.tcp-server.adoc b/doc/modules/ROOT/pages/4.guide/4k.tcp-server.adoc
@@ -13,7 +13,9 @@ The `tcp_server` class provides a framework for building TCP servers with
 connection pooling. It manages acceptors, worker pools, and connection
 lifecycle automatically.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio/tcp_server.hpp>
@@ -23,6 +25,7 @@ NOTE: Code snippets assume:
 namespace corosio = boost::corosio;
 namespace capy = boost::capy;
 ----
+====
 
 == Overview
 

diff --git a/doc/modules/ROOT/pages/4.guide/4l.tls.adoc b/doc/modules/ROOT/pages/4.guide/4l.tls.adoc
@@ -13,7 +13,9 @@ Corosio provides TLS encryption through the `tls_context` configuration class
 and stream wrappers that add encryption to existing connections. This chapter
 covers context configuration, stream usage, and common TLS patterns.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio/tls_context.hpp>
@@ -23,6 +25,7 @@ NOTE: Code snippets assume:
 namespace corosio = boost::corosio;
 namespace tls = corosio::tls;
 ----
+====
 
 == Overview
 

diff --git a/doc/modules/ROOT/pages/4.guide/4m.error-handling.adoc b/doc/modules/ROOT/pages/4.guide/4m.error-handling.adoc
@@ -12,7 +12,9 @@
 Corosio provides flexible error handling through the `io_result` type, which
 supports both error-code and exception-based patterns.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio.hpp>
@@ -22,6 +24,7 @@ NOTE: Code snippets assume:
 namespace corosio = boost::corosio;
 namespace capy = boost::capy;
 ----
+====
 
 == The io_result Type
 

diff --git a/doc/modules/ROOT/pages/4.guide/4n.buffers.adoc b/doc/modules/ROOT/pages/4.guide/4n.buffers.adoc
@@ -12,12 +12,15 @@
 Corosio I/O operations work with buffer sequences from Boost.Capy. This page
 explains how to use buffers effectively.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/capy/buffers.hpp>
 namespace capy = boost::capy;
 ----
+====
 
 == Buffer Types
 

diff --git a/doc/modules/ROOT/pages/5.testing/5a.mocket.adoc b/doc/modules/ROOT/pages/5.testing/5a.mocket.adoc
@@ -13,7 +13,9 @@ The `mocket` class provides mock sockets for testing I/O code without
 actual network operations. Mockets let you stage data for reading and
 verify expected writes.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio/test/mocket.hpp>
@@ -22,6 +24,7 @@ NOTE: Code snippets assume:
 namespace corosio = boost::corosio;
 namespace capy = boost::capy;
 ----
+====
 
 == Overview
 

diff --git a/doc/modules/ROOT/pages/quick-start.adoc b/doc/modules/ROOT/pages/quick-start.adoc
@@ -13,7 +13,9 @@ This guide walks you through building your first network application with
 Corosio: a simple echo server that accepts connections and echoes back
 whatever clients send.
 
-NOTE: Code snippets assume:
+[NOTE]
+====
+Code snippets assume:
 [source,cpp]
 ----
 #include <boost/corosio/tcp_server.hpp>
@@ -23,6 +25,7 @@ NOTE: Code snippets assume:
 namespace corosio = boost::corosio;
 namespace capy = boost::capy;
 ----
+====
 
 == Step 1: Create the I/O Context