# cargo-sync-rdme
[](https://doc.rust-lang.org/cargo/reference/manifest.html#the-badges-section)
[](#license)
[](https://crates.io/crates/cargo-sync-rdme)
[](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field)
[](https://github.com/gifnksm/cargo-sync-rdme/actions/workflows/ci.yml)
[](https://codecov.io/gh/gifnksm/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.
[intra-doc links]: https://doc.rust-lang.org/rustdoc/linking-to-items-by-name.html
[rustdoc's JSON output]: https://doc.rust-lang.org/rustdoc/unstable-features.html#json-output
## Documentation
* [**Latest**](https://cargo-sync-rdme.readthedocs.io/en/latest/): documentation for the development version
* [**Stable**](https://cargo-sync-rdme.readthedocs.io/en/stable/): documentation for the latest release
## Installation
For detailed installation instructions, see the [installation guide](https://cargo-sync-rdme.readthedocs.io/en/stable/installation.html).
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`
[GitHub Releases]: https://github.com/gifnksm/cargo-sync-rdme/releases/
[cargo-binstall]: https://github.com/cargo-bins/cargo-binstall
## 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:
* `<!-- cargo-sync-rdme title -->`: generate document title (H1 element) from package name.
* `<!-- cargo-sync-rdme badge -->`: generate badges from package metadata.
* `<!-- cargo-sync-rdme rustdoc -->`: generate documentation for a crate from document comments.
Write a Markdown file, such as `README.md`, as follows:
```markdown
```
To update the package README and any additional configured Markdown files, run the following:
```console
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:
```console
rustup toolchain install nightly
```
Alternatively, `cargo-sync-rdme` can install the requested toolchain automatically:
```console
cargo sync-rdme --toolchain nightly --install-toolchain
```
The package README or another configured Markdown file will be updated as follows:
```markdown
(document title)
(badges)
(crate documentation)
```
See [examples/lib](examples/lib) for actual examples.
## Configuration
You can customize the behavior of `cargo-sync-rdme` by adding the following section to `Cargo.toml`.
```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](https://cargo-sync-rdme.readthedocs.io/en/stable/configuration.html) 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](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
* MIT license
([LICENSE-MIT](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](CONTRIBUTING.md).