md: replace admonitions with callouts

.github/workflows/ci.yml

@@ -26,7 +26,6 @@ jobs:
 
       - uses: DavidAnson/markdownlint-cli2-action@v18
         with:
-          config: .markdownlint.json
           globs: '**/*.md'
 
       - uses: dtolnay/rust-toolchain@nightly
@@ -54,16 +53,9 @@ jobs:
         with:
           tool: bpf-linker
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - uses: astral-sh/setup-uv@v3
 
-      - name: Install python dependencies
-        run: |
-          python -m pip install --upgrade pip
-          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-
-      - name: Build docs
-        run: mkdocs build
+      - run: uv run mkdocs build
 
       - name: Check Examples
         working-directory: examples

.python-version

@@ -0,0 +1 @@
+3.8

README.md

@@ -11,12 +11,9 @@ This book is a living document, and is updated continuously.
 
 ## Local Render
 
-    ```console
-    virtualenv .venv
-    source .venv/bin/activate
-    pip install -r requirements.txt
-    mkdocs serve
-    ```
+```console
+uv run mkdocs serve
+```
 
 ## License
 

docs/book/aya/aya-tool.md

@@ -1,9 +1,7 @@
 # Using aya-tool
 
-!!! example "Source Code"
-
-    Full code for the example in this chapter is available
-    [here](https://github.com/aya-rs/book/tree/main/examples/aya-tool)
+> [!EXAMPLE] Source Code
+> Full code for the example in this chapter is available [here][source-code].
 
 Very often you will need to use type definitions that your running Linux kernel
 uses in its source code. For example, you might need a definition of
@@ -53,13 +51,14 @@ done with:
 aya-tool generate task_struct > myapp-ebpf/src/vmlinux.rs
 ```
 
-!!! tip "Generating for multiple types"
-
-    You can also specify multiple types to generate, for example:
-    ```console
-    $ aya-tool generate task_struct dentry > vmlinux.rs
-    ```
-    But in the following example, we will focus only on `task_struct`.
+> [!TIP] Generating for multiple types
+> You can also specify multiple types to generate, for example:
+>
+> ```console
+> aya-tool generate task_struct dentry > vmlinux.rs
+> ```
+>
+> But in the following example, we will focus only on `task_struct`.
 
 Then we can use `vmlinux` as a module with `mod vmlinux` in our eBPF program,
 like here:
@@ -77,4 +76,5 @@ The structures are not simply generated from kernel headers. However, the
 target kernel (regardless of version) should have `CONFIG_DEBUG_INFO_BTF`
 option enabled.
 
+[source-code]: https://github.com/aya-rs/book/tree/main/examples/aya-tool
 [task-struct]: https://elixir.bootlin.com/linux/v5.15.3/source/include/linux/sched.h#L723

docs/book/programs/cgroup-skb.md

@@ -1,8 +1,7 @@
 # Cgroup SKB
 
-!!! example "Source Code"
-
-    Full code for the example in this chapter is available [here](https://github.com/aya-rs/book/tree/main/examples/cgroup-skb-egress)
+> [!EXAMPLE] Source Code
+> Full code for the example in this chapter is available [here][source-code].
 
 ## What is Cgroup SKB?
 
@@ -47,6 +46,8 @@ cargo install bindgen-cli
 Let's use `xtask` to automate the process of generating bindings so we can
 easily reproduce it in the future by adding the following code:
 
+<!-- markdownlint-disable MD046 -->
+
 === "xtask/src/codegen.rs"
 
     ```rust linenums="1"
@@ -65,6 +66,8 @@ easily reproduce it in the future by adding the following code:
     --8<-- "examples/cgroup-skb-egress/xtask/src/main.rs"
     ```
 
+<!-- markdownlint-enable MD046 -->
+
 Once we've generated our file using `cargo xtask codegen` from the root of the
 project, we can access it by including `mod bindings` from eBPF code.
 
@@ -169,3 +172,5 @@ LOG: DST 172.217.19.78, ACTION 1
 LOG: DST 172.217.19.78, ACTION 1
 LOG: DST 172.217.19.78, ACTION 1
 ```
+
+[source-code]: https://github.com/aya-rs/book/tree/main/examples/cgroup-skb-egress

docs/book/programs/classifiers.md

@@ -1,9 +1,7 @@
 # Classifiers
 
-!!! example "Source Code"
-
-    Full code for the example in this chapter is available
-    [here](https://github.com/aya-rs/book/tree/main/examples/tc-egress)
+> [!EXAMPLE] Source Code
+> Full code for the example in this chapter is available [here][source-code].
 
 ## What is Classifier in eBPF?
 
@@ -48,18 +46,17 @@ packet. Otherwise, we are going to **pipe** it with `TC_ACT_PIPE` action - which
 means allowing it on our side, but let the packet be inspected also by another
 Classifier programs and qdisc filters.
 
-!!! note "TC_ACT_OK"
-
-    There is also a possibility to allow the packet while bypassing the other
-    programs and filters - `TC_ACT_OK`. We recommend that option only if absolutely
-    sure that you want your program to have a precedence over the other programs
-    or filters.
+> [!NOTE] TC_ACT_OK
+> There is also a possibility to allow the packet while bypassing the other
+> programs and filters - `TC_ACT_OK`. We recommend that option only if absolutely
+> sure that you want your program to have a precedence over the other programs
+> or filters.
 
 Here's how the eBPF code looks like:
 
-  ```rust linenums="1" title="tc-egress-ebpf/src/main.rs"
-  --8<-- "examples/tc-egress/tc-egress-ebpf/src/main.rs"
-  ```
+```rust linenums="1" title="tc-egress-ebpf/src/main.rs"
+--8<-- "examples/tc-egress/tc-egress-ebpf/src/main.rs"
+```
 
 1. Create our map.
 1. Check if we should allow or deny our packet.
@@ -74,9 +71,9 @@ In this example, we'll block all egress traffic going to `1.1.1.1`.
 
 Here's how the code looks like:
 
-  ```rust linenums="1" title="tc-egress/src/main.rs"
-  --8<-- "examples/tc-egress/tc-egress/src/main.rs"
-  ```
+```rust linenums="1" title="tc-egress/src/main.rs"
+--8<-- "examples/tc-egress/tc-egress/src/main.rs"
+```
 
 1. Get a reference to the map.
 1. Create an IPv4Addr.
@@ -90,16 +87,18 @@ is an appropriate type to use in eBPF maps.
 
 ## Running the program
 
-  ```console
-  $ RUST_LOG=info cargo xtask run
-  LOG: SRC 1.1.1.1, ACTION 2
-  LOG: SRC 35.186.224.47, ACTION 3
-  LOG: SRC 35.186.224.47, ACTION 3
-  LOG: SRC 1.1.1.1, ACTION 2
-  LOG: SRC 168.100.68.32, ACTION 3
-  LOG: SRC 168.100.68.239, ACTION 3
-  LOG: SRC 168.100.68.32, ACTION 3
-  LOG: SRC 168.100.68.239, ACTION 3
-  LOG: SRC 1.1.1.1, ACTION 2
-  LOG: SRC 13.248.212.111, ACTION 3
-  ```
+```console
+$ RUST_LOG=info cargo xtask run
+LOG: SRC 1.1.1.1, ACTION 2
+LOG: SRC 35.186.224.47, ACTION 3
+LOG: SRC 35.186.224.47, ACTION 3
+LOG: SRC 1.1.1.1, ACTION 2
+LOG: SRC 168.100.68.32, ACTION 3
+LOG: SRC 168.100.68.239, ACTION 3
+LOG: SRC 168.100.68.32, ACTION 3
+LOG: SRC 168.100.68.239, ACTION 3
+LOG: SRC 1.1.1.1, ACTION 2
+LOG: SRC 13.248.212.111, ACTION 3
+```
+
+[source-code]: https://github.com/aya-rs/book/tree/main/examples/tc-egress

docs/book/programs/lsm.md

@@ -1,9 +1,7 @@
 # LSM
 
-!!! example "Source Code"
-
-    Full code for the example in this chapter is available
-    [here](https://github.com/aya-rs/book/tree/main/examples/lsm-nice)
+> [!EXAMPLE] Source Code
+> Full code for the example in this chapter is available [here][source-code].
 
 ## What is LSM
 
@@ -204,6 +202,7 @@ renice: failed to set priority for 587184 (process ID): Operation not permitted
 If doing that resulted in `Operation not permitted`, congratulations, your LSM
 eBPF program works!
 
+[source-code]: https://github.com/aya-rs/book/tree/main/examples/lsm-nice
 [lsm-wikipedia]: https://en.wikipedia.org/wiki/Linux_Security_Modules
 [lsm-kernel-docs]: https://www.kernel.org/doc/html/latest/security/lsm.html
 [lsm-hook-defs]: https://github.com/torvalds/linux/blob/master/include/linux/lsm_hook_defs.h

docs/book/programs/probes.md

@@ -1,9 +1,7 @@
 # Probes
 
-!!! example "Source Code"
-
-    Full code for the example in this chapter is available
-    [here](https://github.com/aya-rs/book/tree/main/examples/kprobetcp).
+> [!EXAMPLE] Source Code
+> Full code for the example in this chapter is available [here][source-code].
 
 ## What are the probes in eBPF?
 
@@ -67,5 +65,6 @@ $ RUST_LOG=info cargo xtask run --release
 
 <!-- markdownlint-enable MD013 -->
 
+[source-code]: https://github.com/aya-rs/book/tree/main/examples/kprobetcp
 [kernel-docs]: https://docs.kernel.org/trace/kprobes.html
 [tcp-connect]: https://elixir.bootlin.com/linux/latest/source/net/ipv4/tcp_output.c#L3837

docs/book/programs/xdp.md

@@ -1,8 +1,7 @@
 # XDP
 
-!!! example "Source Code"
-
-    Full code for the example in this chapter is available [here](https://github.com/aya-rs/book/tree/main/examples/xdp-drop)
+> [!EXAMPLE] Source Code
+> Full code for the example in this chapter is available [here][source-code].
 
 ## What is XDP in eBPF?
 
@@ -128,8 +127,8 @@ We import the necessary dependencies:
 - `core::mem`: For memory manipulation
 - `network_types`: For Ethernet and IP header definitions
 
-!!! note "Important"
-    Make sure you add the `network_types` dependency in your `Cargo.toml`.
+> [!IMPORTANT]
+> Make sure you add the `network_types` dependency in your `Cargo.toml`.
 
 Here's how the code looks:
 
@@ -413,16 +412,15 @@ human-readable and can be easily converted to a u32.
 
 We'll block all traffic originating from `1.1.1.1` in this example.
 
-!!! note "Endianness"
-
-    IP addresses are always encoded in network byte order (big endian) within
-    packets. In our eBPF program, before checking the blocklist, we convert them
-    to host endian using `u32::from_be`. Therefore it's correct to write our IP
-    addresses in host endian format from userspace.
-
-    The other approach would work too: we could convert IPs to network endian
-    when inserting from userspace, and then we wouldn't need to convert when
-    indexing from the eBPF program.
+> [!NOTE] Endianness
+> IP addresses are always encoded in network byte order (big endian) within
+> packets. In our eBPF program, before checking the blocklist, we convert them
+> to host endian using `u32::from_be`. Therefore it's correct to write our IP
+> addresses in host endian format from userspace.
+>
+> The other approach would work too: we could convert IPs to network endian
+> when inserting from userspace, and then we wouldn't need to convert when
+> indexing from the eBPF program.
 
 Let's begin with writing the user-space code:
 
@@ -455,11 +453,11 @@ we use for informational and warning messages
 - `tokio::signal`: For handling signals asynchronously, see
   [this link][tokio-signal] for more information
 
-!!! note
-    `aya::Bpf` is deprecated since version `0.13.0` and `aya_log:BpfLogger`
-    since `0.2.1`. Use [`aya::Ebpf`][aya-ebpf] and
-    [`aya_log:EbpfLogger`][aya-ebpf-logger] instead if you are using the more
-    recent versions.
+> [!NOTE]
+> `aya::Bpf` is deprecated since version `0.13.0` and `aya_log:BpfLogger`
+> since `0.2.1`. Use [`aya::Ebpf`][aya-ebpf] and
+> [`aya_log:EbpfLogger`][aya-ebpf-logger] instead if you are using the more
+> recent versions.
 
 #### Defining command-line arguments
 
@@ -628,6 +626,7 @@ RUST_LOG=info cargo xtask run -- --iface <interface>
 if you want to provide another network interface name. note that you can also
 use `cargo xtask run` without the rest, but you won't get any logging.
 
+[source-code]: https://github.com/aya-rs/book/tree/main/examples/xdp-drop
 [af-xdp]: https://www.kernel.org/doc/html/latest/networking/af_xdp.html
 [kernel-documentation]: https://www.kernel.org/doc/html/latest/networking/af_xdp.html
 [cilium-xdp]: https://docs.cilium.io/en/latest/bpf/progtypes/#xdp