fix: markdownlint

Author: YuanYuYuan

.markdownlint.json

@@ -1,5 +1,6 @@
 {
   "MD013": false,
+  "MD025": false,
   "MD033": {
     "allowed_elements": ["div", "h1", "p", "strong", "a", "sub"]
   },

CONTRIBUTING.md

@@ -116,6 +116,7 @@ When adding a new ros-z feature:
    - Use `{{#include ../../ros-z/examples/your_example.rs}}` to reference the example
    - Update `book/src/SUMMARY.md` if adding a new chapter
 4. **Test everything**:
+
    ```bash
    cargo build
    cargo test
@@ -240,7 +241,7 @@ Follow conventional commit format:
 
 ## Project Structure
 
-```
+```text
 ros-z/
 ├── ros-z/                  # Core library
 │   ├── src/               # Production code
@@ -260,16 +261,19 @@ ros-z/
 ### If-Then Flows
 
 **IF adding new ros-z feature:**
+
 - ADD `examples/new_feature.rs`
 - ADD/UPDATE book chapter with `{{#include}}`
 - RUN `cargo build && mdbook test book -L ./target/debug/deps`
 
 **IF making API breaking change:**
+
 - UPDATE `examples/*.rs` files
 - UPDATE book text references
 - Single commit: "feat: new API + examples + docs"
 
 **IF mdbook test fails:**
+
 - RUN `cargo clean && cargo build`
 - CHECK `target/debug/deps` contains `libros_z-*.rlib`
 - RE-RUN `mdbook test book -L ./target/debug/deps`

README.md

@@ -38,6 +38,7 @@ Comprehensive documentation with examples is available:
 - **Local**: Build and view locally with `mdbook serve book` (see [book/README.md](book/README.md))
 
 The documentation includes:
+
 - Getting started guide
 - Publisher/subscriber examples
 - Service examples

WORKFLOW_STATUS.md

@@ -6,7 +6,7 @@ The suggested two-Cargo.toml approach is **NOT needed**. The current structure a
 
 ## Current Structure (Already Optimal)
 
-```
+```text
 ros-z/                          # Workspace root
 ├── Cargo.toml                  # Workspace definition
 ├── ros-z/                      # Library crate
@@ -81,8 +81,8 @@ required-features = ["external_msgs"]
 ### ✅ 4. mdBook Can Test Examples
 
 ```bash
-$ cargo build
-$ mdbook test book -L ./target/debug/deps
+cargo build
+mdbook test book -L ./target/debug/deps
 ```
 
 The `-L ./target/debug/deps` flag links examples against the compiled library.
@@ -149,6 +149,7 @@ jobs:
 **✅ Keep the current structure** - it's optimal and follows Rust best practices.
 
 **❌ Don't implement the two-Cargo.toml approach** - it would:
+
 - Add unnecessary complexity
 - Break existing include paths (20+ files to update)
 - Create a non-standard project structure
@@ -166,16 +167,19 @@ jobs:
 ## Next Steps
 
 1. **Reload nix environment** to get mdbook:
+
    ```bash
    direnv allow
    ```
 
 2. **Run the full workflow**:
+
    ```bash
    ./test-docs.sh
    ```
 
 3. **Preview the book**:
+
    ```bash
    mdbook serve book
    ```

book/QUICK_REFERENCE.md

@@ -24,6 +24,7 @@ The `mdbook test` command tests **every Rust code block** in your markdown files
 ```
 
 This code block will be:
+
 1. Extracted by mdbook
 2. Compiled with rustc
 3. Linked against `libros_z.rlib` (from `target/debug/deps`)
@@ -93,7 +94,8 @@ mdbook test book -L ./target/debug/deps
 ```
 
 Without `-L ./target/debug/deps`, the test will fail with:
-```
+
+```text
 error[E0463]: can't find crate for `ros_z`
 ```
 
@@ -125,12 +127,15 @@ Runs automatically on every push and pull request.
 1. Create `ros-z/examples/my_feature.rs`
 2. Add chapter `book/src/chapters/my_feature.md`
 3. Include the example:
+
    ```markdown
    \`\`\`rust,no_run
    {{#include ../../../ros-z/examples/my_feature.rs}}
    \`\`\`
    ```
+
 4. Test it:
+
    ```bash
    cargo build --example my_feature  # Verify example compiles
    mdbook test book -L ./target/debug/deps  # Verify book sees it

book/README.md

@@ -51,6 +51,7 @@ mdbook test book -L ./target/debug/deps
 ```
 
 This command:
+
 - Tests all Rust code blocks in the book chapters
 - Uses `-L ./target/debug/deps` to link against the compiled ros-z library
 - Validates that all `{{#include}}` directives work correctly
@@ -79,7 +80,7 @@ See [TESTING.md](TESTING.md) for detailed information about testing.
 
 The current structure follows **standard Rust practices**:
 
-```
+```text
 ros-z/                     # Workspace root
 ├── ros-z/                # Library crate
 │   ├── Cargo.toml       # Has ALL dependencies (clap, tokio, etc.)
@@ -91,6 +92,7 @@ ros-z/                     # Workspace root
 ```
 
 **Why this works:**
+
 - ✅ Examples in `ros-z/examples/` have access to all dependencies
 - ✅ `cargo run --example name` works out of the box
 - ✅ `mdbook test` finds examples via `{{#include ../../../ros-z/examples/...}}`
@@ -110,7 +112,7 @@ The output will be in `book/book/` directory.
 
 ## Book Structure
 
-```
+```text
 book/
 ├── book.toml           # mdBook configuration
 └── src/

book/TESTING.md

@@ -5,6 +5,7 @@ This document explains how to test that all code examples in the book compile an
 ## The `mdbook test` Command
 
 mdBook has a built-in test command that:
+
 1. Extracts all Rust code blocks from markdown files
 2. Compiles them as mini test programs
 3. Links them against your library
@@ -29,14 +30,15 @@ mdbook test book -L ./target/debug/deps
 ```
 
 **Explanation:**
+
 - `mdbook test book` - Test all code blocks in the book
 - `-L ./target/debug/deps` - Tell the Rust compiler where to find the compiled `ros-z` library
 
 ### Expected Output
 
 On success, you'll see:
 
-```
+```text
 2025-12-16 [INFO] (mdbook::book): Book building has started
 2025-12-16 [INFO] (mdbook::book): Running the html backend
 2025-12-16 [INFO] (mdbook::renderer::html_handlebars::search): Index built in ...
@@ -52,14 +54,14 @@ test result: ok. 15 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
 
 If an example fails to compile, you'll see detailed error messages:
 
-```
+```text
 test book/src/chapters/example.md - example::rust_1 (line 5) ... FAILED
 
 error[E0425]: cannot find value `xyz` in this scope
  --> /tmp/.tmpXYZ/main.rs:5:10
   |
 5 |     let x = xyz;
-  |             ^^^ not found in this scope
+     |             ^^^ not found in this scope
 ```
 
 ## Code Block Annotations
@@ -209,18 +211,20 @@ Or use the Nix pre-commit hooks (already configured in the development shell).
 2. **Use `no_run` for full programs**: Examples with `main()` that run indefinitely
 3. **Use `ignore` sparingly**: Only for pseudo-code or intentionally incomplete examples
 4. **Test locally before pushing**: Run the full workflow:
+
    ```bash
    cargo build
    cargo test
    mdbook test book -L ./target/debug/deps
    ```
+
 5. **Keep examples simple**: Complex examples are harder to test in documentation
 
 ## Understanding Test Output
 
 Each test corresponds to a code block:
 
-```
+```text
 test book/src/chapters/demo_talker.md - demo_talker::rust_1 (line 11) ... ok
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^  ^^^^^^^^
      File path                           Test name             Line number
@@ -235,6 +239,7 @@ When a test fails:
 1. **Check the file and line number** in the error message
 2. **Extract the code block** from the markdown
 3. **Try compiling manually**:
+
    ```bash
    # Create a test file
    cat > test.rs << 'EOF'
@@ -247,6 +252,7 @@ When a test fails:
    # Compile it
    rustc --edition 2021 -L target/debug/deps --extern ros_z test.rs
    ```
+
 4. **Fix the issue** in the example file (not the markdown!)
 5. **Update the markdown** if needed (should auto-update if using `{{#include}}`)
 6. **Re-run**: `mdbook test book -L ./target/debug/deps`

book/WORKFLOW_VERIFICATION.md

@@ -4,7 +4,7 @@ This document verifies that the complete workflow works as intended.
 
 ## Current Structure (Optimal)
 
-```
+```text
 ros-z/                          # Workspace root
 ├── Cargo.toml                  # Workspace definition
 ├── ros-z/                      # Library crate
@@ -71,6 +71,7 @@ mdbook test book -L ./target/debug/deps
 ```
 
 **How it works:**
+
 1. `cargo build` creates `libros_z-*.rlib` in `target/debug/deps/`
 2. `mdbook test` extracts code blocks from markdown
 3. `-L ./target/debug/deps` tells rustc where to find the library
@@ -81,14 +82,16 @@ mdbook test book -L ./target/debug/deps
 ### Step 4: Include Paths Work
 
 Book chapters use:
+
 ```markdown
 \`\`\`rust,no_run
 {{#include ../../../ros-z/examples/demo_nodes/talker.rs}}
 \`\`\`
 ```
 
 **Path resolution:**
-```
+
+```text
 book/src/chapters/demo_talker.md
                   ↓ ../
 book/src/
@@ -133,6 +136,7 @@ path = "examples/demo_nodes/talker.rs"
 ```
 
 Benefits:
+
 - ✅ Examples automatically have access to all dependencies
 - ✅ `cargo build` builds everything
 - ✅ `cargo run --example` works out of the box
@@ -143,13 +147,14 @@ Benefits:
 
 Some suggest making examples a separate workspace member:
 
-```
+```text
 examples/
 ├── Cargo.toml  # Separate package
 └── *.rs
 ```
 
 Problems:
+
 - ❌ Non-standard structure
 - ❌ Breaks `{{#include}}` paths (need to update 20+ files)
 - ❌ More complex `cargo` commands
@@ -169,6 +174,7 @@ GitHub Actions (`.github/workflows/docs.yml`) runs:
 ```
 
 This ensures:
+
 1. Library compiles
 2. Tests pass
 3. **All documentation examples compile and work**
@@ -195,6 +201,7 @@ X = "version"
 ```
 
 Then rebuild:
+
 ```bash
 cargo build
 mdbook test book -L ./target/debug/deps
@@ -210,6 +217,7 @@ cargo build --example demo_nodes_talker
 ```
 
 Or add the feature:
+
 ```bash
 cargo build --example z_srvcli --features external_msgs
 ```

book/src/chapters/actions.md

@@ -10,11 +10,13 @@ Actions provide a mechanism for long-running tasks in ROS 2, with the ability to
 ## Overview
 
 Actions are useful for tasks that:
+
 - Take a long time to complete
 - Need to provide progress updates
 - May need to be cancelled
 
 Common examples include:
+
 - Navigation to a goal
 - Gripper control
 - Long computations

book/src/chapters/demo_add_two_ints_server.md

@@ -62,7 +62,7 @@ cargo run --example demo_nodes_add_two_ints_client -- --a 10 --b 20
 
 Expected output:
 
-```
+```text
 # Server output:
 Incoming request
 a: 10 b: 20