feat: add admonitions (#99)

Example result:

<img width="790" alt="image"
src="https://github.com/user-attachments/assets/df01333d-3240-468b-abfd-37a2c688ad25">

Closes #22

.editorconfig

@@ -19,12 +19,12 @@ indent_size = unset
 max_line_length = unset
 trim_trailing_whitespace = unset
 
-[{*.yml,*.yaml,*.toml}]
+[{*.yml,*.yaml,*.toml,*.css}]
 indent_size = 2
 max_line_length = 150
 
 # Ignore paths
-[{.git/**/*,LICENSE,**/Move.lock}]
+[{.git/**/*,LICENSE,**/Move.lock,mdbook-admonish.css}]
 charset = unset
 end_of_line = unset
 indent_size = unset

.github/actions/build-mdbook/action.yaml

@@ -21,6 +21,11 @@ runs:
         unzip "$_" -d bin
         chmod +x bin/mdbook-linkcheck
       shell: bash
+    - name: Install mdbook-admonish
+      run: |
+        url="https://github.com/tommilligan/mdbook-admonish/releases/download/v1.18.0/mdbook-admonish-v1.18.0-x86_64-unknown-linux-gnu.tar.gz"
+        curl -sSL "$url" | tar -xz --directory=bin
+      shell: bash
     - name: Build the book and check for broken links
       run: mdbook build
       env:

README.md

@@ -16,6 +16,7 @@ You can also build and access the documentation locally (assuming you have Rust
 
 ```sh
 cargo install mdbook
+cargo install [email protected] --locked
 mdbook serve
 ```
 

book.toml

@@ -10,6 +10,7 @@ build-dir = "build"
 
 
 [output.html]
+additional-css = ["./mdbook-admonish.css"]
 
 [output.linkcheck]
 optional = true
@@ -21,3 +22,10 @@ exclude = [
   'walrus\.site', # No service worker in the link checker.
   'google\.com',
 ]
+
+[preprocessor]
+
+[preprocessor.admonish]
+command = "mdbook-admonish"
+on_failure = "bail"
+assets_version = "3.0.2" # do not edit: managed by `mdbook-admonish install`

docs/README.md

@@ -5,9 +5,27 @@ protocol designed specifically for large binary files, or "blobs". Walrus focuse
 robust, but affordable solution for storing unstructured content on decentralized storage nodes
 while ensuring high availability and reliability even in the presence of Byzantine faults.
 
-Fun fact: If you are viewing this site at <https://docs.walrus.site>, you are fetching this from
+```admonish tip title="Fun fact"
+If you are viewing this site at <https://docs.walrus.site>, you are fetching this from
 Walrus behind the scenes. See the [Walrus Sites chapter](./walrus-sites/intro.md) for further
 details on how this works.
+```
+
+```admonish danger title="Disclaimer about the Walrus developer preview"
+The current Devnet release of Walrus and Walrus Sites is a developer preview intended to showcase
+the technology and solicit feedback from builders. All storage nodes and aggregators are operated by
+Mysten Labs and all transactions are executed on the Sui Testnet and use Testnet SUI which has no
+value. The state of the store **can and will be wiped**, at any point and possibly with no warning.
+Do not rely on this developer preview for any production purposes, it comes with no availability or
+persistence guarantees.
+
+Furthermore, encodings and blob IDs may be incompatible with the future Testnet and Mainnet and
+developers will be responsible for migrating any Devnet applications and data to Testnet. Detailed
+migration guides will be provided when Testnet becomes available.
+
+Also see the [Devnet terms of service](../tos.md) under which this developer preview is made
+available.
+```
 
 ## Features
 

docs/design/operations-off-chain.md

@@ -70,14 +70,16 @@ The flow is as follows:
   [availability period](./properties.md). No storage attestation challenges are issued for this
   blob ID.
 
-A blob ID that is inconsistent always resolves to `None` upon reading: this is because
+```admonish tip title="Reading inconsistent blobs"
+A blob ID that is inconsistent always resolves to `None` upon reading because
 the read process re-encodes the received blob to check that the blob ID is correctly derived from a
 consistent encoding. This means that an inconsistency proof reveals only a true fact to storage
 nodes (that do not otherwise run decoding), and does not change the output of read in any case.
 
-Note, however, that partial reads leveraging the systematic nature of the encoding might return
+However, partial reads leveraging the systematic nature of the encoding might successfully return
 partial reads for inconsistently encoded files. Thus, if consistency and availability of reads is
 important, dApps should do full reads rather than partial reads.
+```
 
 ## Read paths
 

docs/design/properties.md

@@ -30,8 +30,9 @@ stored by a user that incorrectly encoded a blob.
 Note that there is no delete operation and a blob ID past PoA will be available for the full
 availability period.
 
-As a rule of thumb: before PoA it is the responsibility of a client to ensure the availability of
-a blob and its upload to Walrus. After PoA it is the responsibility of Walrus as a system to
-maintain the availability of the blob as part of its operation for the full availability period
-remaining. Emission of the event corresponding to the PoA for a blob ID attests its
-availability.
+```admonish tip title="Rule of thumb"
+Before the PoA it is the responsibility of a client to ensure the availability of a blob and its
+upload to Walrus. After the PoA it is the responsibility of Walrus as a system to maintain the
+availability of the blob as part of its operation for the full availability period remaining.
+Emission of the event corresponding to the PoA for a blob ID attests its availability.
+```

docs/dev-guide/dev-guide.md

@@ -14,14 +14,18 @@ This developer guide describes:
 
 A [glossary](../glossary.md) of terms used is also available for reference.
 
-## Disclaimer about the Walrus developer preview
+```admonish danger title="Disclaimer about the Walrus developer preview"
+The current Devnet release of Walrus and Walrus Sites is a developer preview intended to showcase
+the technology and solicit feedback from builders. All storage nodes and aggregators are operated by
+Mysten Labs and all transactions are executed on the Sui Testnet and use Testnet SUI which has no
+value. The state of the store **can and will be wiped**, at any point and possibly with no warning.
+Do not rely on this developer preview for any production purposes, it comes with no availability or
+persistence guarantees.
 
-**This release of Walrus \& Walrus Sites is a
-developer preview, to showcase the technology and solicit feedback from builders. All storage nodes
-and aggregators are operated by Mysten Labs, all transactions are executed on the Sui testnet,
-and use testnet SUI which has no value. The state of the store can be, and will be wiped, at any
-point and possibly with no warning. Do not rely on this developer preview for any production
-purposes, it comes with no availability or persistence guarantees.**
+Furthermore, encodings and blob IDs may be incompatible with the future Testnet and Mainnet and
+developers will be responsible for migrating any Devnet applications and data to Testnet. Detailed
+migration guides will be provided when Testnet becomes available.
 
 Also see the [Devnet terms of service](../tos.md) under which this developer preview is made
 available.
+```

docs/dev-guide/dev-operations.md

@@ -12,10 +12,11 @@ You can derive the blob ID of a file locally using the command: `walrus blob-id
 
 Walrus may be used to **store a blob**, via the native client APIs or a publisher.
 
-> **All blobs
-> stored in Walrus are public and discoverable by all**. Therefore you must not use Walrus to store
-> anything that contains secrets or private data without additional measures to protect
-> confidentiality.
+```admonish warning
+**All blobs stored in Walrus are public and discoverable by all.** Therefore you must not use Walrus
+to store anything that contains secrets or private data without additional measures to protect
+confidentiality.
+```
 
 Under the hood a number of operations happen both on Sui as well as on storage nodes:
 

docs/dev-guide/sui-struct.md

@@ -15,9 +15,10 @@ the Walrus contracts is available at
 The following sections provide further insights into the contract and an overview of how you may use
 Walrus objects in your own Sui smart contracts.
 
-**A word of caution:** Walrus testnet will use new Move packages with struct layouts and function
-signatures that may not be compatible with this package. Move code that builds against this package
-will need to rewritten.
+```admonish danger title="A word of caution"
+Walrus Testnet will use new Move packages with struct layouts and function signatures that may not
+be compatible with this package. Move code that builds against this package will need to rewritten.
+```
 
 ## Blob and Storage Objects
 

docs/usage/setup.md

@@ -6,7 +6,9 @@ patterns (see [the next chapter](./interacting.md)). This chapter describes the
 [prerequisites](#prerequisites), [installation](#installation), and [configuration](#configuration)
 of the Walrus client.
 
-Note that our Walrus devnet uses Sui **testnet** for coordination.
+```admonish note
+Note that our Walrus Devnet uses Sui **Testnet** for coordination.
+```
 
 ## Prerequisites
 
@@ -103,6 +105,13 @@ Commands:
 ⋮
 ```
 
+```admonish tip
+Our latest Walrus binaries are also available on Walrus itself, namely on <https://bin.walrus.site>.
+Note, however, that you can only access this through a web browser and not through CLI tools like
+cURL due to the service-worker architecture (see the [Walrus Sites docs](../walrus-sites/portal.md)
+for further insights).
+```
+
 ### Custom path (optional) {#binary-custom-path}
 
 Instead of `~/.local/bin`, you can place the binary in any other directory you like. You need to
@@ -182,4 +191,6 @@ communication_config:
       nanos: 0
 ```
 
-**Important**: If you specify a wallet path, make sure your wallet is set up for Sui **testnet**.
+```admonish warning title="Important"
+If you specify a wallet path, make sure your wallet is set up for Sui **Testnet**.
+```

docs/usage/web-api.md

@@ -31,9 +31,13 @@ walrus publisher -b $PUB_ADDRESS # run a publisher to store blobs
 ```
 
 The aggregator provides all read APIs, the publisher all the store APIs, and the daemon provides
-both. Note that the aggregator does not perform Sui on-chain actions, and therefore consumes no gas.
-However, the publisher does perform actions on-chain and will consume gas. It is therefore important
-to ensure only authorized parties may access it, or other measures to manage gas costs.
+both.
+
+```admonish warning
+While the aggregator does not perform Sui on-chain actions, and therefore consumes no gas, the
+publisher does perform actions on-chain and will consume gas. It is therefore important to ensure
+only authorized parties may access it, or other measures to manage gas costs.
+```
 
 ## Using a public aggregator or publisher {#public-services}
 
@@ -136,6 +140,8 @@ Alternatively you may print the contents of a blob in the terminal with the cURL
 curl "$AGGREGATOR/v1/<some blob ID>
 ```
 
+```admonish tip title="Content sniffing"
 Modern browsers will attempt to sniff the content type for such resources, and will generally do a
 good job of inferring content types for media. However, the aggregator on purpose prevents such
-sniffing from inferring dangerous executable types such as javascript or style sheet types.
+sniffing from inferring dangerous executable types such as JavaScript or style sheet types.
+```

docs/walrus-sites/tutorial-publish.md

@@ -82,6 +82,10 @@ old `index.html`, and update it with the newer one.
 
 Browsing to the provided URL should reflect the change. You've updated the site!
 
+```admonish note
+The wallet you are using must be the *owner* of the Walrus Site object to be able to update it.
+```
+
 ## Additional commands
 
 The `site-builder` tool provides two additional utilities:
@@ -92,4 +96,8 @@ The `site-builder` tool provides two additional utilities:
 - the `sitemap` command, which shows the resources that compose the Walrus Site at the given object
   ID.
 
-In general, the `--help` flag is your friend!
+```admonish tip
+In general, the `--help` flag is your friend, you can add it to get further details for the whole
+CLI (`./target/release/site-builder --help`) or individual commands (e.g.,
+`./target/release/site-builder update --help`).
+```