cargo-sync-rdme

cargo-sync-rdme is a Cargo subcommand for keeping package READMEs and other Markdown files up to date.

The Markdown content is generated from your package metadata and crate documentation.

Single source of truth -- keep information in its canonical locations instead of duplicating it in README files.
Cargo metadata -- generate the Markdown title and badges from Cargo.toml.
Crate documentation -- embed sections from crate documentation.
Accurate link resolution -- use rustdoc's JSON output to resolve intra-doc links.
Preserve existing Markdown -- synchronize only the sections you configure, while leaving the rest of your Markdown untouched.
Markdown as configuration -- configure which sections to synchronize directly in the Markdown file. You can read the Markdown as usual, and no separate template files are needed.

Documentation

Latest: documentation for the development version
Stable: documentation for the latest release

Installation

For detailed installation instructions, see the installation guide.

Quick installation options:

Download executable binaries from GitHub Releases.
Install prebuilt binaries via cargo-binstall: cargo binstall cargo-sync-rdme
Build from source using Rust: cargo install cargo-sync-rdme

Usage

cargo-sync-rdme is a subcommand to synchronize the package README and additional configured Markdown files with package metadata and crate documentation. By embedding marker comments in a Markdown file, you can insert content generated by cargo-sync-rdme. By default, cargo-sync-rdme updates the package README specified by package.readme (commonly README.md). You can also synchronize additional Markdown files with package.metadata.cargo-sync-rdme.extra-targets. There are three kinds of marker comments:

: generate document title (H1 element) from package name.
: generate badges from package metadata.
: generate documentation for a crate from document comments.

Write a Markdown file, such as README.md, as follows:

<!-- cargo-sync-rdme title -->
<!-- cargo-sync-rdme badge -->
<!-- cargo-sync-rdme rustdoc -->

To update the package README and any additional configured Markdown files, run the following:

cargo sync-rdme --toolchain nightly

cargo-sync-rdme uses unstable rustdoc features, so a nightly toolchain is required when synchronizing crate documentation into Markdown files. If the nightly toolchain is not installed, install it manually with the following command:

rustup toolchain install nightly

Alternatively, cargo-sync-rdme can install the requested toolchain automatically:

cargo sync-rdme --toolchain nightly --install-toolchain

The package README or another configured Markdown file will be updated as follows:

<!-- cargo-sync-rdme title [[ -->
(document title)
<!-- cargo-sync-rdme ]] -->
<!-- cargo-sync-rdme badge [[ -->
(badges)
<!-- cargo-sync-rdme ]] -->
<!-- cargo-sync-rdme rustdoc [[ -->
(crate documentation)
<!-- cargo-sync-rdme ]] -->

See examples/lib for actual examples.

Configuration

You can customize the behavior of cargo-sync-rdme by adding the following section to Cargo.toml.

[package.metadata.cargo-sync-rdme.badge]
badges = {
  maintenance = true,
  license = true,
}

[package.metadata.cargo-sync-rdme.rustdoc]
html-root-url = "https://docs.rs/<package-name>/<version>/"

See Configuration for details.

Minimum Supported Rust Version (MSRV)

The minimum supported Rust version is Rust 1.98.0.

While a crate is a pre-release status (0.x.x) it may have its MSRV bumped in a patch release. Once a crate has reached 1.x, any MSRV bump will be accompanied by a new minor version.

License

This project is licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

See CONTRIBUTING.md.

cargo-sync-rdme 0.8.0