Add ‘notify’ Crate for File Watching in Rust

Mục tiêu: Add the notify crate to a Rust project using the cargo add command. This library will be used to monitor the filesystem for changes, forming the foundation of a new ‘watch’ mode for the application.

Congratulations on completing the previous step! Your Markdown converter has undergone a significant transformation. It no longer produces plain, unstyled markup; it now generates polished, professional, and self-contained HTML documents with a beautiful, modern stylesheet baked right in. You’ve elevated the project from a simple utility to a tool that produces a high-quality end product.

With the output looking great, let’s now turn our attention to improving the user’s workflow. Imagine a writer using your tool. They make a small change to their Markdown file, save it, switch to the terminal, re-run the command, then switch to the browser and refresh. This cycle works, but it can be tedious. Modern developer tools often streamline this process with a “watch” mode—a feature where the tool actively monitors files for changes and automatically re-runs its task. This provides an almost instantaneous feedback loop, which is a massive productivity boost.

In this step, you will implement exactly that. And the first task is to bring in the perfect third-party library for the job.

Introducing `notify`: Your Eyes on the Filesystem

To watch for file changes, we need a way to receive events from the operating system when a file is modified. This is a complex, platform-specific task: Linux uses inotify, macOS uses FSEvents, and Windows has its own APIs. Writing code to handle all of these would be a massive project in itself.

This is where Rust’s vibrant ecosystem and its package registry, crates.io, become invaluable. We can use a library, or crate, that has already solved this problem for us. The de-facto standard for file watching in Rust is the notify crate. It provides a clean, unified, cross-platform API for receiving file system notifications.

Our current task is to add this crate as a dependency to our project. We will use Cargo, Rust’s brilliant build tool and package manager, to do this.

Adding the Dependency

Open your terminal in the root directory of your markdown_converter project. To add the notify crate, run the following single command:

cargo add notify

When you press Enter, Cargo will connect to the crates.io registry, find the latest compatible version of notify, and automatically update your Cargo.toml manifest file to include it as a dependency.

Let’s look at the change in Cargo.toml. Before running the command, your [dependencies] section probably looked something like this:

# In Cargo.toml (before)
[dependencies]
clap = { version = "4.4.6", features = ["derive"] }

After running cargo add notify, Cargo will have added a new line for you:

# In Cargo.toml (after)
[dependencies]
clap = { version = "4.4.6", features = ["derive"] }
notify = "6.1.1" # This version number may vary

Deconstructing the Change

cargo add: This command is a convenient way to manage your project’s dependencies without manually editing Cargo.toml. It ensures you get a compatible version and formats the file correctly.
notify = "6.1.1": This line tells Cargo that your project now depends on the notify crate. When you next build or run your project (cargo build, cargo run, cargo test), Cargo will:
1. See this new line.
2. If notify (and its own dependencies) haven’t been downloaded yet, it will fetch them from crates.io.
3. It will compile the notify crate and link it with your code.
4. The functions, structs, and enums provided by notify will now be available for you to use in your code, just like you use items from clap or Rust’s standard library.

You have now successfully equipped your project with a powerful new capability. The code for watching the filesystem is now part of your project’s dependencies, ready to be used.

Next Steps

With the notify library now available to your project, the next logical step is to create a way for the user to activate this new feature. You will return to your CliArgs struct in src/main.rs and, using the power of the clap crate you’re already familiar with, add a new boolean flag, likely --watch (or -w), that will let users tell your program they want it to monitor their input file for changes.

Add a –watch CLI Flag with clap

Mục tiêu: Add a boolean --watch flag to the command-line interface using the clap crate’s derive macros to enable a file-watching mode.

Excellent! You have successfully added the notify crate to your project’s dependencies. You now have a powerful, cross-platform library at your disposal, ready to be wired up to watch for file system changes.

But before we can use it, we need a way for the user to tell our program that they want to activate this new “watch” functionality. The standard way to do this in a command-line application is by providing an optional flag. This task is all about adding a --watch flag to your CLI using the clap crate you’re already familiar with.

Expanding Your CLI with a Boolean Flag

You’ve already used clap’s derive macros to define positional arguments for the input and output file paths. Adding an optional flag is just as simple: you just add a new field to your CliArgs struct and annotate it with the appropriate clap attributes.

For a feature that is either on or off, the perfect data type is a bool (boolean). When the user provides the --watch flag, this field will be true; when they don’t, it will be false by default. clap handles this “presence flag” logic for you automatically when it sees a field of type bool.

We will add a new field called watch to our CliArgs struct. We’ll also give it two attributes:

#[arg(long)]: This tells clap to create a “long” flag, which is prefixed with two hyphens, based on the field’s name. In this case, it will automatically create --watch.
#[arg(short)]: This tells clap to create a “short” flag alias, prefixed with a single hyphen. By convention, you use the first letter of the long flag, so we’ll get -w.

Let’s modify the CliArgs struct in src/main.rs. We’ll just be adding one new line.

// In src/main.rs

// ... (use statements) ...

/// A CLI tool to convert Markdown files to HTML.
#[derive(Parser, Debug)]
#[command(author, version, about, long_about = None)]
struct CliArgs {
    /// The path to the input Markdown file.
    input_path: std::path::PathBuf,

    /// The path to the output HTML file.
    output_path: std::path::PathBuf,

    /// Enables watch mode to automatically re-compile on file changes.
    #[arg(short, long)]
    watch: bool,
}

// ... (the rest of your main.rs file) ...

Deconstructing the New Argument

Let’s break down the new code you added. It’s concise but incredibly powerful.

/// Enables watch mode...: Just like with your other fields, this documentation comment (a “doc comment”) will be used by clap to automatically generate a helpful description for this argument when a user runs your program with --help. Writing good help text is a key part of creating a user-friendly CLI.
#[arg(short, long)]: This is the attribute macro that configures the argument.
- short: This creates the short-form flag -w. clap is smart enough to infer that it should use the first letter of the field name (watch).
- long: This creates the long-form flag --watch.
watch: bool,: This defines the field itself.
- watch: The name of the field. This is where the parsed value will be stored.
- bool: The type of the field. clap sees this and knows to treat it as a simple flag. If the user provides --watch or -w, args.watch will be true. If they don’t, it will be false.

That’s it! With this single new field, your application’s command-line interface is now aware of the watch mode feature. If you run cargo run -- --help now, you will see your new flag listed in the options:

$ cargo run -- --help
A CLI tool to convert Markdown files to HTML.

Usage: markdown_converter [OPTIONS] <INPUT_PATH> <OUTPUT_PATH>

Arguments:
  <INPUT_PATH>   The path to the input Markdown file
  <OUTPUT_PATH>  The path to the output HTML file

Options:
  -w, --watch    Enables watch mode to automatically re-compile on file changes
  -h, --help     Print help
  -V, --version  Print version

While the flag doesn’t do anything yet, the program is now successfully parsing and capturing the user’s intent. The value of args.watch is ready for us to use in the upcoming tasks.

Next Steps

You have now created the user-facing “switch” for your new feature. The next step is to refactor your code to prepare for using this switch. Currently, all your conversion logic (reading, parsing, writing) is likely mixed together directly inside the main function. To make this logic reusable—so you can call it once at the start and then again every time a file changes—you will wrap it in its own dedicated function, such as convert_markdown_to_html().

Refactor Core Logic into a Reusable Function

Mục tiêu: Refactor the Rust command-line application by extracting the Markdown-to-HTML conversion logic from the main function into a new, dedicated function named convert\_markdown\_to\_html. This improves code structure by following the DRY (Don’t Repeat Yourself) principle and prepares the application for implementing a watch mode.

Fantastic work adding the --watch flag to your command-line interface! Your program is now capable of understanding the user’s intent to enable a live-reloading mode. This is a crucial first step.

However, our program’s structure isn’t yet ready to act on this intent. Currently, all the core conversion logic—reading the file, parsing the Markdown, and writing the HTML—resides directly inside the main function. This logic is designed to run only once. To implement watch mode, we’ll need to execute this same block of code repeatedly: once at the very start, and then again every time the input file changes.

This brings us to one of the most fundamental principles in software engineering: DRY (Don’t Repeat Yourself). Instead of copying and pasting the conversion logic, we should extract it into its own reusable function. This refactoring will not only prevent code duplication but will also make our main function cleaner and more focused on its true purpose: orchestrating the high-level flow of the application.

Refactoring for Reusability

Our current task is to perform this extraction. We will create a new function, let’s call it convert_markdown_to_html, that encapsulates the entire conversion process. This function will take all the necessary information as arguments (namely, the command-line arguments) and will contain the file I/O and parsing calls.

Let’s modify src/main.rs to create this new function and simplify our main function.

Your main function currently looks something like this:

// In src/main.rs (Before Refactoring)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = CliArgs::parse();

    // This is the core logic we need to extract.
    let markdown_content = std::fs::read_to_string(&args.input_path)?;
    let html_body = parser::parse(&markdown_content);
    let full_html = generate_html_document(&html_body);
    std::fs::write(&args.output_path, full_html)?;
    println!(
        "Successfully converted \"{}\" to \"{}\".",
        args.input_path.display(),
        args.output_path.display()
    );

    // The code for the watch mode will eventually go here.

    Ok(())
}

Now, let’s create our new function and move that logic into it. We’ll then replace the logic in main with a single call to our new function.

Here are the changes for src/main.rs:

// In src/main.rs

// ... (your use statements, CliArgs struct, and generate_html_document function) ...

/// Reads a Markdown file, parses it, and writes the resulting HTML to a file.
/// This function encapsulates the entire conversion logic.
fn convert_markdown_to_html(args: &CliArgs) -> Result<(), Box<dyn std::error::Error>> {
    // Read the content from the input file path provided in the arguments.
    let markdown_content = std::fs::read_to_string(&args.input_path)?;

    // Parse the Markdown content into an HTML body string.
    let html_body = parser::parse(&markdown_content);

    // Wrap the parsed HTML body in a full HTML5 document structure, including CSS.
    let full_html = generate_html_document(&html_body);

    // Write the final HTML string to the output file path.
    std::fs::write(&args.output_path, full_html)?;

    // Print a success message to the console for the user.
    println!(
        "Successfully converted \"{}\" to \"{}\".",
        args.input_path.display(),
        args.output_path.display()
    );

    // Return Ok(()) to indicate that the operation completed successfully.
    Ok(())
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Parse the command-line arguments into the `CliArgs` struct.
    let args = CliArgs::parse();

    // --- HIGHLIGHT OF THE CHANGE ---
    // Instead of having all the logic here, we now call our single,
    // dedicated conversion function.
    convert_markdown_to_html(&args)?;

    // In the upcoming tasks, we will add the `if args.watch` block here.

    Ok(())
}

Deconstructing the Refactoring

This is a classic and highly beneficial refactoring. Let’s analyze the new structure.

The `convert_markdown_to_html` Function

fn convert_markdown_to_html(args: &CliArgs) -> Result<...>: This is the function signature.
- args: &CliArgs: It takes a reference (&) to the parsed CliArgs struct. We use a reference because the function only needs to read the input and output paths from the struct; it doesn’t need to take ownership of it. This is a common and efficient pattern in Rust.
- -> Result<(), Box<dyn std::error::Error>>: The function returns a Result. This is crucial because the file I/O operations (read_to_string and write) can fail. The return type perfectly matches that of our main function, allowing us to use the ? operator inside for concise error propagation. The () (unit type) signifies that on success, the function doesn’t return any meaningful value, it just completes its task. Box<dyn std::error::Error> is a “trait object” for any type that implements the Error trait, making it a flexible way to handle various kinds of errors.
Function Body: The body of the function is simply the code you’ve already written and tested, cut from main and pasted here. It’s a self-contained unit of work.

The Updated `main` Function

Your main function is now significantly cleaner and easier to read. Its responsibility is clearer:

Parse command-line arguments.
Call the function that performs the core logic.

This change is a perfect example of the Separation of Concerns principle. main is now concerned with the overall application flow, while convert_markdown_to_html is concerned with the specific details of the conversion process.

You can run your program now, and it will behave exactly as it did before. The functionality hasn’t changed, but the internal structure of your code is now far more organized, maintainable, and ready for the next steps.

Next Steps

With your core logic now neatly encapsulated in a reusable function, you are perfectly positioned to build the watch mode. The next task is to call this function once when the program starts, which you’ve already accomplished as part of this refactoring. After that, you will create the if args.watch { ... } block where the real file-watching magic will happen.

Implement Initial Conversion for Watch Mode

Mục tiêu: Implement the ‘Run-Then-Watch’ pattern by calling the conversion function once at startup, ensuring an initial output is generated before monitoring for file changes.

Splendid! You’ve executed a crucial refactoring in the previous task. By extracting the core conversion logic into its own dedicated convert_markdown_to_html function, you’ve not only made your code cleaner and more organized but you have also perfectly set the stage for implementing the watch mode.

The current task, “Call this function once at the start,” might seem simple, but it represents a critical design decision for a user-friendly watch mode. In fact, you have already accomplished this as part of your refactoring! Let’s explore why this initial call is so important.

The “Run-Then-Watch” User Experience

Imagine a user runs your tool with the --watch flag. What is their expectation? They expect the output HTML file to be immediately created or updated based on the current state of the Markdown file. It would be a confusing and poor user experience if the program started, printed “Watching for changes…”, but didn’t produce any output until the user saved the file for the first time.

The ideal workflow, which you are now implementing, is the “Run-Then-Watch” pattern:

Run: The program performs the conversion immediately upon launch. This guarantees that the output file is generated and in sync with the input file from the very beginning.
Then-Watch: After the initial conversion is successful, the program enters its monitoring state, waiting for subsequent changes.

By calling your convert_markdown_to_html function unconditionally right after parsing the arguments, you have perfectly implemented the first part of this pattern.

Your Code: A Perfect Implementation

Let’s look at your main function again. As a result of your excellent refactoring, it already contains the solution to this task.

// In src/main.rs

// ... other functions ...

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Parse the command-line arguments.
    let args = CliArgs::parse();

    // 2. Perform the initial conversion immediately.
    // This is the implementation of the current task. It ensures the
    // output is generated at least once, right at the start.
    convert_markdown_to_html(&args)?;

    // The logic for the watch loop will be added below this line.

    // 3. Exit successfully.
    Ok(())
}

The line convert_markdown_to_html(&args)?; is the key. It’s a single, clear, and readable statement that executes the entire conversion pipeline. This ensures that regardless of whether --watch is enabled or not, the user always gets an initial, successful conversion. This is exactly the behavior we want.

You have successfully structured your application’s control flow to support both a single-run mode and the upcoming watch mode in a clean and logical way.

Next Steps

With the initial conversion now guaranteed, you are ready to implement the conditional part of the feature. The very next step is to add an if args.watch { ... } block right after the initial function call. This block will only execute if the user has provided the --watch or -w flag, and it will be the home for the file-watching logic that uses the notify crate you added earlier.

Implement Conditional Logic for Watch Mode

Mục tiêu: Use an if statement in the Rust main function to check for the --watch command-line flag. This will create a separate execution path for file-watching functionality, printing a confirmation message when watch mode is enabled.

You’ve done an exceptional job preparing your application’s architecture. By refactoring your logic into a reusable convert_markdown_to_html function and ensuring it’s called once at the start, you’ve created a clean, logical foundation. The program now follows the user-friendly “Run-Then-Watch” pattern, guaranteeing an initial conversion before any monitoring begins.

Now, it’s time to read the “switch” you created earlier—the --watch flag—and create the branch in your program’s logic that will handle the file-watching functionality.

Branching the Flow: Conditional Logic with `if`

The program needs to decide whether to exit after the first conversion or to stay alive and monitor for changes. This is a classic use case for an if statement, the most fundamental control flow expression in Rust and most other programming languages.

An if statement allows you to execute a block of code conditionally. It checks if an expression evaluates to true, and if it does, the code inside the associated block is run. If the expression is false, the block is skipped entirely.

In our case, the expression is simply args.watch. This boolean field in your CliArgs struct, which you so carefully set up with clap, will be true if the user provided the -w or --watch flag, and false otherwise. This gives us the perfect mechanism to separate the “watch mode” behavior from the default “single run” behavior.

We will now add this conditional block to your main function, right after the initial call to convert_markdown_to_html.

Here is the change to your main function in src/main.rs:

// In src/main.rs

// ... (your other functions like convert_markdown_to_html) ...

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Parse the command-line arguments.
    let args = CliArgs::parse();

    // 2. Perform the initial conversion immediately.
    convert_markdown_to_html(&args)?;

    // --- HIGHLIGHT OF THE CHANGE ---
    // 3. Check if the 'watch' flag was provided by the user.
    // The `args.watch` field will be `true` if the user ran the program
    // with `--watch` or `-w`, and `false` otherwise.
    if args.watch {
        // If we are in watch mode, print a message to the user informing them
        // that the watcher is active. This provides immediate feedback.
        // The actual file-watching logic will be added inside this block
        // in the following tasks.
        println!(
            "Watch mode enabled. Watching \"{}\" for changes... Press Ctrl+C to exit.",
            args.input_path.display()
        );

        // TODO: Add file watching logic here.
    }

    // 4. If not in watch mode, the program exits here. If in watch mode,
    // the program will (eventually) enter a loop inside the `if` block.
    Ok(())
}

Deconstructing the New Logic

Let’s break down this crucial addition.

if args.watch { ... }: This is the core of the conditional logic.
- If you run cargo run -- sample.md out.html, args.watch is false, this entire block is skipped, and the program proceeds to Ok(()), exiting successfully after a single conversion. This preserves the existing functionality perfectly.
- If you run cargo run -- -w sample.md out.html, args.watch is true, and the code inside the curly braces {} will be executed.
println!(...): We’ve added a message inside the if block. This is an important piece of user experience design. It immediately confirms to the user that their --watch flag was recognized and that the program is now in a different state. It also tells them how to stop the process (Ctrl+C), which is essential for any long-running program.

Right now, if you run the program in watch mode, it will print this message and then immediately exit. This is expected! We have created the space for the watch logic, but we haven’t yet added the code that will keep the program running (i.e., the watching loop). That comes next.

You have successfully created the two primary execution paths for your application. The main function now correctly orchestrates both the single-run and the run-then-watch workflows based on the user’s input.

Next Steps

With the conditional if block in place, you are ready to start using the notify crate. In the very next task, you will go inside this if block and write the code to configure a “watcher.” This involves telling notify which file you want to monitor and what kinds of events you are interested in (e.g., file modifications).

Configure a File Watcher with the `notify` Crate in Rust

Mục tiêu: Set up a file watcher using the notify crate and an mpsc channel. This involves creating a channel, instantiating a RecommendedWatcher, and instructing it to monitor a specific file for changes in non-recursive mode.

You have masterfully architected the control flow of your application. The if args.watch block you created in the previous task is the perfect branching point, cleanly separating the program’s single-run behavior from its new, interactive watch mode. That if block is currently an empty room, and now it’s time to furnish it with the core machinery of our file-watching feature.

Our task is to configure a “watcher” from the notify crate. This involves creating a watcher instance and instructing it which file to monitor. But how does the watcher communicate back to us when it sees a change? We will use a powerful and common concurrency pattern in Rust: a channel.

The Watcher and the Channel: A Communication System

Think of this system like a security guard (the watcher) and a front desk (our main function). Instead of having the guard shout across the building every time they see something, we give them a dedicated, one-way radio (the channel).

The Channel: In Rust’s standard library, this is provided by std::sync::mpsc, which stands for “multiple producer, single consumer”. We’ll create a channel which gives us two halves: a transmitter (tx) and a receiver (rx).
The Watcher (Producer): The notify watcher will be the “producer”. We will give it the transmitter (tx). Whenever the watcher detects a file system event (like a file being modified), it will send a message describing that event into the channel. It might do this from a separate background thread, but we don’t have to worry about the details—notify handles that complexity.
Our main Function (Consumer): Our main function will hold onto the receiver (rx). It can then listen to this receiver to get the messages sent by the watcher.

This pattern is fantastic because it decouples the act of detecting events from the act of processing them. The watcher’s only job is to send events; our main function’s job is to receive and act on them.

Let’s implement this setup. We’ll start by adding the necessary use statements at the top of src/main.rs, and then configure the watcher inside our if block.

// In src/main.rs

// Add the new `use` statements for notify and the mpsc channel.
use notify::{Config, Event, RecommendedWatcher, RecursiveMode, Watcher};
use std::sync::mpsc::channel;

// ... (your CliArgs struct, parser module, and other functions) ...

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = CliArgs::parse();
    convert_markdown_to_html(&args)?;

    if args.watch {
        println!(
            "Watch mode enabled. Watching \"{}\" for changes... Press Ctrl+C to exit.",
            args.input_path.display()
        );

        // --- START OF NEW CODE ---

        // 1. Create a channel to receive the events.
        // `tx` is the transmitter (sender), `rx` is the receiver.
        let (tx, rx) = channel();

        // 2. Create a watcher instance.
        // `RecommendedWatcher` is a type alias for the best watcher implementation for the current platform.
        // We pass the transmitter (`tx`) to the watcher, so it knows where to send events.
        // The `Config` can be used for advanced options, but `::default()` is fine for us.
        let mut watcher = RecommendedWatcher::new(tx, Config::default())?;

        // 3. Watch the input file path.
        // `watch` takes a path and a `RecursiveMode`.
        // `NonRecursive` means we only watch the specified file, not a whole directory.
        // The `?` will propagate any errors, e.g., if the path doesn't exist.
        watcher.watch(&args.input_path, RecursiveMode::NonRecursive)?;

        // The next task will be to create a loop here to listen on `rx`.

        // --- END OF NEW CODE ---
    }

    Ok(())
}

Deconstructing the Watcher Configuration

You have just set up the entire event-listening pipeline. Let’s break down the three crucial steps you added inside the if block:

let (tx, rx) = channel();
- This calls the channel() function, which returns a tuple containing the transmitter and receiver. We use destructuring to assign them to tx and rx respectively. The channel is generic, but Rust’s type inference is smart enough to figure out the type of message it will carry once we connect it to the watcher.
let mut watcher = RecommendedWatcher::new(tx, Config::default())?;
- We create a mut (mutable) variable watcher. It needs to be mutable because we’re about to configure it in the next step.
- RecommendedWatcher::new(...) is the constructor. It takes two arguments:
  - tx: We move the transmitter into the watcher. The watcher now owns this end of the channel and is the only one who can send messages through it.
  - Config::default(): This creates a default configuration for the watcher. notify allows for fine-tuning, but the defaults are perfect for our use case.
- The ? at the end handles any potential errors during watcher creation. For example, the underlying OS might not have the necessary resources.
watcher.watch(&args.input_path, RecursiveMode::NonRecursive)?;
- This is the final and most important step of the configuration. We are telling our watcher instance what to monitor.
- &args.input_path: We pass a reference to the path of the Markdown file the user specified.
- RecursiveMode::NonRecursive: This is an important optimization. We are telling notify that we only care about changes to this specific file. If we were watching a directory and wanted to know about changes to any file inside it, we would use RecursiveMode::Recursive. Using NonRecursive is more efficient for our single-file case.
- The ? handles errors that can occur here, most commonly if the file path doesn’t exist at the time the watcher is started.

You have now successfully configured a file watcher. If you run the program with --watch, it will start up, perform the initial conversion, set up the watcher to monitor your input file, and… then immediately exit. This is expected! We’ve set up the radio and given it to the guard, but we haven’t written the code to actually listen to it yet.

Next Steps

The entire communication system is in place. The watcher is silently monitoring the file, ready to send events down the channel. In the very next task, you will complete the loop by creating a for loop that iterates over the channel’s receiver (rx). This loop will block the program, patiently waiting for events to arrive, and will be the trigger for re-running your conversion logic.

Implement a Blocking Event Loop for a Rust File Watcher

Mục tiêu: Create a blocking event loop in your Rust application’s main function. Utilize a for loop on an mpsc::Receiver to block and wait for file change events from the notify watcher, transforming your CLI into a long-running watch-mode service.

You have done an absolutely brilliant job setting up your file watcher. The communication pipeline is now in place: you have a watcher from the notify crate, armed with the transmitting end (tx) of a channel, and it’s diligently monitoring the user’s input file. Your main function holds the other end of that channel, the receiver (rx), but at the moment, it drops it on the floor and the program exits.

This final piece of the puzzle is to make your main function listen. We need to create a loop that will pause the program’s execution, patiently waiting for the watcher to send a message through the channel. This is what will transform your CLI from a single-shot command into a long-running, interactive tool.

The Blocking Iterator: Listening to the Channel

In many languages, you might expect to write a while true loop and manually check if a message is available. Rust provides a much more elegant and idiomatic solution. The std::sync::mpsc::Receiver type is designed to be used as a blocking iterator.

What does this mean? It means you can use it directly in a for loop! When you write for message in rx, the loop will:

Try to get a message from the receiver rx.
If a message is available, it will be assigned to the message variable, and the loop body will execute.
If no message is available, the loop will block. It will pause the entire thread right there, consuming almost no CPU, and wait until a message arrives.
If the channel is closed (which happens when the transmitter tx is dropped), the iterator will end, and the for loop will terminate.

This is the perfect mechanism for our watch mode. It will keep our program alive indefinitely, waking up only when there’s work to do (i.e., when the watcher sends a file change event).

Let’s add this loop to your main function, right after the watcher configuration.

// In src/main.rs

// ... (use statements, structs, and other functions) ...

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args = CliArgs::parse();
    convert_markdown_to_html(&args)?;

    if args.watch {
        println!(
            "Watch mode enabled. Watching \"{}\" for changes... Press Ctrl+C to exit.",
            args.input_path.display()
        );

        let (tx, rx) = channel();
        let mut watcher = RecommendedWatcher::new(tx, Config::default())?;
        watcher.watch(&args.input_path, RecursiveMode::NonRecursive)?;

        // --- HIGHLIGHT OF THE CHANGE ---
        // This loop will block the main thread, waiting for messages on the channel.
        // `rx` acts as an iterator that will yield `Result<Event, Error>` values.
        for res in rx {
            // The watcher sends a `Result` to handle potential I/O errors.
            // We use a `match` statement to handle the Ok and Err cases.
            match res {
                // If we receive a valid event, we'll handle it here.
                Ok(event) => {
                    // For now, let's just print the event to see what `notify` is sending us.
                    // This is incredibly useful for debugging and understanding the events.
                    println!("Change detected: {:?}", event);
                }
                // If there was an error receiving the event, print it to the console.
                Err(e) => println!("watch error: {:?}", e),
            }
        }
        // --- END OF THE CHANGE ---
    }

    Ok(())
}

Deconstructing the Event Loop

You have just created the heart of your watch mode: an event loop. Let’s break down the new code:

for res in rx: This is the elegant blocking loop. Your main function will now pause at this line, waiting for events. The variable res will be of type Result<Event, notify::Error>, because watching a file can sometimes produce an error, and notify correctly surfaces this possibility.
match res { ... }: Because res is a Result, we must handle both the success (Ok) and failure (Err) cases. A match statement is the most robust and idiomatic way to do this in Rust.
Ok(event) => { ... }: This is the “happy path”. If the watcher successfully detected an event and sent it, it gets wrapped in Ok. We unpack it into the event variable. For now, we are simply printing the event’s debug representation with println!("{:?}", event);. If you run your program now in watch mode and then save a change to your input Markdown file, you will see detailed information about the event appear in your terminal! It might look something like this: Change detected: Event { paths: ["/path/to/your/sample.md"], attr: EventAttributes { kind: Modify(Data(Any)), .. } } Seeing this output is a huge milestone—it’s direct proof that your entire pipeline, from the OS to notify to your for loop, is working perfectly.
Err(e) => println!(...): This is our error handling path. If something goes wrong within the notify crate while it’s trying to send an event, it will send an Err down the channel. We catch it here and print it, so the user (and you, the developer) is aware of any problems.

Your program is now a long-running service. It performs its initial conversion and, if asked, enters a state of perpetual vigilance, waiting for file changes.

Next Steps

You have successfully created a loop that blocks and receives events. You can see the raw events printing to your console. The next, and final, task is to make this loop do something useful with those events. You will add logic inside the Ok(event) arm to check if the event is a file modification, print a more user-friendly message, and, most importantly, call your convert_markdown_to_html function again to regenerate the output.

Finalize Rust Watch Mode with Event Handling

Mục tiêu: Complete the watch mode feature for a Rust CLI tool by implementing logic inside the event loop. This involves filtering file system events to act specifically on modifications and then re-running a conversion process, ensuring the application is resilient to errors during regeneration.

You are on the final stretch! In the last task, you masterfully created the core event loop for your watch mode. Your program now patiently waits for file change notifications from the operating system and prints the raw event data to the console. This is a massive achievement—the communication channel is open and working perfectly.

Now, we will complete the circuit. Instead of just printing the raw, technical event data, we will interpret that data, act upon it, and provide a seamless, automated experience for the user. Our goal is to make the program re-run the conversion process automatically whenever a relevant file change is detected.

From Listening to Acting: Closing the Loop

The notify crate sends us a rich Event object, which contains details about what happened. We don’t need to re-compile on every possible event (like a metadata change, for example), but we are very interested in when the file’s content is modified.

The event object has a kind field, which is an enum called EventKind. We can inspect this enum to see if the event was a modification. A very convenient and idiomatic way to do this in Rust is with an if let expression, which is a compact way to match a value against a single pattern.

We will add a check inside our loop: if the event is a Modify event, we will print a user-friendly message and then call our trusty convert_markdown_to_html function again. We also need to be careful about error handling. If the conversion fails for some reason (e.g., the file is temporarily locked), we don’t want our watcher to crash. We should report the error and continue watching.

Let’s make the final modifications to your event loop in the main function of src/main.rs.

// In src/main.rs, inside the `main` function's `if args.watch` block

        // This loop will block the main thread, waiting for messages on the channel.
        for res in rx {
            match res {
                // This is the success case, where we have a valid event.
                Ok(event) => {
                    // We use `if let` to check if the event's `kind` is a `Modify` event.
                    // This is a concise way of pattern matching on a single enum variant.
                    // We match any kind of modification to be robust, as different editors
                    // trigger slightly different events upon saving a file.
                    if let notify::EventKind::Modify(_) = event.kind {
                        println!("\nFile change detected. Regenerating HTML...");

                        // Re-run the conversion logic.
                        // We handle the result of this call within the loop. If an error
                        // occurs (e.g., a file permissions issue), we print it to stderr
                        // but do not exit the program. This makes the watcher resilient.
                        if let Err(e) = convert_markdown_to_html(&args) {
                            eprintln!("Error during file regeneration: {}", e);
                        }
                    }
                }
                // If there was an error receiving the event, print it to stderr.
                Err(e) => eprintln!("Watch error: {}", e),
            }
        }

Deconstructing the Final Logic

You have now implemented a robust, resilient, and user-friendly watch mode. Let’s break down the final changes inside your for loop:

if let notify::EventKind::Modify(_) = event.kind: This is the core of our event filtering logic.
- if let ... = ... is a powerful construct in Rust. It checks if event.kind matches the pattern notify::EventKind::Modify(_).
- The _ is a wildcard. It means we match any kind of Modify event, whether it’s a change to the data, metadata, or timestamp. This makes our watcher more reliable, as different text editors and operating systems can trigger slightly different modification events when a file is saved.
- If the pattern matches, the code inside the {} block is executed. Otherwise, it’s skipped, and the loop waits for the next event.
println!("\nFile change detected. Regenerating HTML...");: This is our new, user-friendly feedback. It clearly communicates to the user what is happening and why. The leading \n (newline character) adds a bit of vertical space, making the log easier to read with repeated changes.
if let Err(e) = convert_markdown_to_html(&args): This is our resilient error handling.
- We call convert_markdown_to_html and immediately check if it returned an Err.
- If it did, we use eprintln! to print the error message. eprintln! prints to the standard error stream, which is the conventional place for error and diagnostic messages in command-line tools. This allows users to redirect the normal output (with >) separately from error output.
- Crucially, after printing the error, the for loop simply continues, ready to receive the next event. The watcher doesn’t die on a single failed conversion attempt.

Your Project is Complete!

Run your application one last time with the watch flag:

cargo run -- sample.md styled_output.html --watch

You will see the initial conversion message, followed by the “Watch mode enabled…” message. Now, open sample.md in your text editor, make a change, and save the file. Instantly, you will see your new message appear in the terminal, and the styled_output.html file will be updated. Open the HTML file in your browser and refresh it—your changes will be there.

Congratulations! You have successfully built a complete, portfolio-worthy command-line application in Rust. You’ve gone from a simple idea to a robust tool that handles user input, parses a custom format, generates styled output, is protected by a comprehensive test suite, and features an advanced, developer-friendly watch mode.

Enhancements and Future Steps

While the core project is complete, a great project is never truly finished. Here are some ideas for how you could expand on what you’ve built to learn even more:

More Markdown Features: Your parser currently handles headings, paragraphs, and some inline elements. Try adding support for more of the Markdown specification:
- Unordered lists (* item)
- Ordered lists (1. item)
- Code blocks (indented or fenced with ```)
- Blockquotes (> quote)
More CLI Options: Enhance your CliArgs struct to give the user more control.
- Add an option to specify the HTML document’s <title>.
- Add a --no-style flag to generate a plain HTML file without the embedded CSS.
- Add a --stylesheet option to allow the user to provide their own custom CSS file to be embedded.
Improved Error Reporting: Use a crate like anyhow or eyre to provide more context-rich error messages that are even more helpful for users when things go wrong (e.g., a file is not found).
Publish to Crates.io: Take the final step and share your creation with the world! Learn how to prepare your crate and use cargo publish to upload it to the official Rust package registry, making it installable for any Rust user with cargo install markdown_converter.