automd-rs

automd-rs is a Rust crate that updates your README.md from your Cargo.toml automatically. Put special HTML comments in your README; run the tool (CLI or as a library), and it fills those blocks with badges, contributor info, and more—so you don’t have to keep version, repo URL, or author in sync by hand.

Features

• Badges – Crates.io version, downloads, docs.rs, GitHub commit activity, repo stars
• Contributors – License line and contrib.rocks image from repo
• With-automdrs – Optional “auto updated with automd-rs” footer
• Extensible – Use the library with a custom BlockHandler to add your own blocks

Installation

As a dependency (library):

cargo add automd-rs

As a binary (to run in your project root):

cargo install automd-rs

Usage

CLI

From your crate root (where Cargo.toml and README.md live):

automd-rs

This reads Cargo.toml, finds all <!-- automdrs:... --> blocks in README.md, generates content for each, and overwrites README.md with the result.

Library

use automd_rs::run;
use std::path::Path;

fn main() -> automd_rs::Result<()> {
    let manifest_dir = Path::new(".");
    let readme_path = Path::new("README.md");
    run(manifest_dir, readme_path)?;
    Ok(())
}

For custom block types, use run_with_handler and implement the BlockHandler trait.

README block syntax

Blocks are HTML comments. Open with <!-- automdrs:NAME [options] -->, close with <!-- /automdrs -->. The content between is replaced by generated output.

Example – badges (all on):

<!-- automdrs:badges showCrateVersion="true" showCrateDownloads="true" showCrateDocs="true" showCommitActivity="true" showRepoStars="true" -->
...generated badges...
<!-- /automdrs -->

Example – contributors:

<!-- automdrs:contributors author="YONGQI" license="MIT" -->
...generated license + contrib.rocks...
<!-- /automdrs -->

Your Cargo.toml must include repository = "https://github.com/owner/repo" (or similar) so the tool can derive the GitHub owner/repo for badges and contributors.

Contribution

• Clone this repository
• Install the latest version of Rust
• Run tests using cargo test or cargo run

Credits

automd-rs was inspired by the idea of keeping README and crate metadata in sync via comment-driven blocks, similar in spirit to doc-generation and badge tools in the Rust and JavaScript ecosystems, such as @automd.

License

Published under the MIT license. Made by @YONGQI 💛

🛠️ auto updated with automd-rs