cargo-sync-rdme 0.7.0

# Configuration

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

```toml
[package.metadata.cargo-sync-rdme]
extra-targets = "./docs/configuration.md"

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

[package.metadata.cargo-sync-rdme.rustdoc]
html-root-url = "<url>"
```

## Common configuration

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

```toml
[package.metadata.cargo-sync-rdme]
extra-targets = "./docs/configuration.md"
```

### `extra-targets`

The `extra-targets` option specifies files to update in addition to `README.md` when `cargo sync-rdme` runs.

You can specify either a string or an array of strings.

```toml
[package.metadata.cargo-sync-rdme]
extra-targets = "./docs/configuration.md"
```

```toml
[package.metadata.cargo-sync-rdme]
extra-targets = ["./docs/configuration.md", "./docs/usage.md"]
```

## Badge configuration

You can customize the badges generated by `cargo-sync-rdme` by adding the following section to `Cargo.toml`:

```toml
[package.metadata.cargo-sync-rdme.badge]
style = "flat-square"
badges = {
  maintenance = true,
  license = true,
}
```

Badges are output in the order in which the configuration items are written.

The updated README looks like this:

```markdown
<!-- cargo-sync-rdme badge [[ -->
[![Maintenance: actively-developed](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg?style=flat-square)](https://doc.rust-lang.org/cargo/reference/manifest.html#the-badges-section)
[![License: MIT OR Apache-2.0](https://img.shields.io/crates/l/cargo-sync-rdme.svg?style=flat-square)](#license)
<!-- cargo-sync-rdme ]] -->
```

### `badge.style`

The `style` option specifies the style of the badge.

The following styles are supported:

|      Style      |                                              Example                                               |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `flat`          | ![flat](https://img.shields.io/badge/style-flat-green.svg?style=flat)                              |
| `flat-square`   | ![flat-square](https://img.shields.io/badge/style-flat--square-green.svg?style=flat-square)        |
| `for-the-badge` | ![for-the-badge](https://img.shields.io/badge/style-for--the--badge-green.svg?style=for-the-badge) |
| `plastic`       | ![plastic](https://img.shields.io/badge/style-plastic-green.svg?style=plastic)                     |
| `social`        | ![social](https://img.shields.io/badge/style-social-green.svg?style=social)                        |

### Badge configuration items

The following configuration items are available for badges:

#### Maintenance status (`badge.{badges,badges-*}.{maintenance,maintenance-*}`)

<!-- cargo-sync-rdme badge:maintenance [[ -->
[![Maintenance: actively-developed](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg?style=flat-square)](https://doc.rust-lang.org/cargo/reference/manifest.html#the-badges-section)
<!-- cargo-sync-rdme ]] -->

A badge indicating the maintenance status of the package.

The badge is generated from the `package.metadata.maintenance.status` field in `Cargo.toml`
(see [the cargo documentation](https://doc.rust-lang.org/cargo/reference/manifest.html#the-badges-section) for details).

The link target of the badge is set to <https://doc.rust-lang.org/cargo/reference/manifest.html#the-badges-section>.

Available values:

* `maintenance = true`: Output a maintenance status badge
* `maintenance = false`: Do not output a maintenance status badge

#### License (`badge.{badges,badges-*}.{license,license-*}`)

<!-- cargo-sync-rdme badge:license [[ -->
![License: MIT OR Apache-2.0](https://img.shields.io/crates/l/cargo-sync-rdme.svg?style=flat-square)
<!-- cargo-sync-rdme ]] -->

A badge indicating the license of the package.

The badge is generated from the `package.license` field or `package.license-file` field in `Cargo.toml`
(see [the cargo documentation](https://doc.rust-lang.org/cargo/reference/manifest.html#the-license-and-license-file-fields) for details).

The link target of the badge is determined by the badge configuration.

Available values:

* `license = { link = "<link>" }`: Output a license badge. The link target of the badge is set to `<link>`
* `license = true`: Output a license badge
  * If `package.license-file` is specified, the link target of the badge is set to the license file
  * If `package.license` is specified, no link is set
* `license = false`: Do not output a license badge

#### crates.io (`badge.{badges,badges-*}.{crates-io,crates-io-*}`)

<!-- cargo-sync-rdme badge:crates-io [[ -->
[![crates.io](https://img.shields.io/crates/v/cargo-sync-rdme.svg?logo=rust&style=flat-square)](https://crates.io/crates/cargo-sync-rdme)
<!-- cargo-sync-rdme ]] -->

A badge indicating the version of the package on crates.io.

The badge is generated from the `package.name` field in `Cargo.toml`
(see [the cargo documentation](https://doc.rust-lang.org/cargo/reference/manifest.html#the-name-field) for details).

The link target of the badge is set to `https://crates.io/crates/<package name>`.

Available values:

* `crates-io = true`: Output a crates.io badge
* `crates-io = false`: Do not output a crates.io badge

#### Docs.rs (`badge.{badges,badges-*}.{docs-rs,docs-rs-*}`)

<!-- cargo-sync-rdme badge:docs-rs [[ -->
[![docs.rs](https://img.shields.io/docsrs/cargo-sync-rdme.svg?logo=docs.rs&style=flat-square)](https://docs.rs/cargo-sync-rdme)
<!-- cargo-sync-rdme ]] -->

A badge indicating the documentation build status of the package on docs.rs.

The badge is generated from the `package.name` field in `Cargo.toml`
(see [the cargo documentation](https://doc.rust-lang.org/cargo/reference/manifest.html#the-name-field) for details).

The link target of the badge is set to `https://docs.rs/<package name>`.

Available values:

* `docs-rs = true`: Output a docs.rs badge
* `docs-rs = false`: Do not output a docs.rs badge

#### Rust Version (MSRV) (`badge.{badges,badges-*}.{rust-version,rust-version-*}`)

<!-- cargo-sync-rdme badge:rust-version [[ -->
[![Rust: ^1.96.0](https://img.shields.io/badge/rust-^1.96.0-93450a.svg?logo=rust&style=flat-square)](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field)
<!-- cargo-sync-rdme ]] -->

A badge indicating the minimum supported Rust version (MSRV) of the package.

The badge is generated from the `package.rust-version` field in `Cargo.toml`
(see [the cargo documentation](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field) for details).

The link target of the badge is set to <https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field>.

Available values:

* `rust-version = true`: Output a supported rust version badge
* `rust-version = false`: Do not output a supported rust version badge

#### GitHub Actions (`badge.{badges,badges-*}.{github-actions,github-actions-*}`)

<!-- cargo-sync-rdme badge:github-actions [[ -->
[![GitHub Actions: CD](https://img.shields.io/github/actions/workflow/status/gifnksm/cargo-sync-rdme/cd.yml.svg?label=CD&logo=github&style=flat-square)](https://github.com/gifnksm/cargo-sync-rdme/actions/workflows/cd.yml)
[![GitHub Actions: CI](https://img.shields.io/github/actions/workflow/status/gifnksm/cargo-sync-rdme/ci.yml.svg?label=CI&logo=github&style=flat-square)](https://github.com/gifnksm/cargo-sync-rdme/actions/workflows/ci.yml)
[![GitHub Actions: Deploy Rustdoc to GitHub Pages](https://img.shields.io/github/actions/workflow/status/gifnksm/cargo-sync-rdme/pages.yml.svg?label=Deploy+Rustdoc+to+GitHub+Pages&logo=github&style=flat-square)](https://github.com/gifnksm/cargo-sync-rdme/actions/workflows/pages.yml)
[![GitHub Actions: Security Audit](https://img.shields.io/github/actions/workflow/status/gifnksm/cargo-sync-rdme/audit.yml.svg?label=Security+Audit&logo=github&style=flat-square)](https://github.com/gifnksm/cargo-sync-rdme/actions/workflows/audit.yml)
[![GitHub Actions: Update Dependencies](https://img.shields.io/github/actions/workflow/status/gifnksm/cargo-sync-rdme/update-deps.yml.svg?label=Update+Dependencies&logo=github&style=flat-square)](https://github.com/gifnksm/cargo-sync-rdme/actions/workflows/update-deps.yml)
<!-- cargo-sync-rdme ]] -->

A badge indicating the status of the GitHub Actions workflow.

The badge is generated from the `package.repository` field in `Cargo.toml`
(see [the cargo documentation](https://doc.rust-lang.org/cargo/reference/manifest.html#the-repository-field) for details).

The link target of the badge is set to `<package.repository>/actions/workflows/<file>`.
`<file>` is the name of the file in the `.github/workflows` directory.

Available values:

* `github-actions = { workflows = [ { file = "<file>", name = "<name>" } ] }`:
    Output GitHub Actions status badges.

    The link target of the badge is set to `<package.repository>/actions/workflows/<file>`.

    The array can contain multiple workflow objects.

    `<name>` is used as the badge name.
    If `<name>` is not specified, the name of the workflow defined in the `<file>` is used as the badge name.
* `github-actions = { workflows = [ "<file>" ] }`:
    Same as `github-actions = { workflows = [ { file = "<file>" } ] }`
* `github-actions = { workflows = "<file>" }`:
    Same as `github-actions = { workflows = [ { file = "<file>" } ] }`
* `github-actions = { workflows = [] }`:
    Output GitHub Actions status badges for all workflows in the `.github/workflows` directory.
* `github-actions = true`: Same as `github-actions = { workflows = [] }`
* `github-actions = false`: Do not output a GitHub Actions status badge

#### Codecov (`badge.{badges,badges-*}.{codecov,codecov-*}`)

<!-- cargo-sync-rdme badge:codecov [[ -->
[![Codecov](https://img.shields.io/codecov/c/github/gifnksm/cargo-sync-rdme.svg?label=codecov&logo=codecov&style=flat-square)](https://codecov.io/gh/gifnksm/cargo-sync-rdme)
<!-- cargo-sync-rdme ]] -->

A badge indicating the coverage of the package.

The badge is generated from the `package.repository` field in `Cargo.toml`
(see [the cargo documentation](https://doc.rust-lang.org/cargo/reference/manifest.html#the-repository-field) for details).

The link target of the badge is set to `https://codecov.io/gh/<repository_path>/`.

Available values:

* `codecov = false`: Do not output a Codecov badge
* `codecov = true`: Output a Codecov badge
* `codecov = {}`: Same as `codecov = true`
* `codecov = { ... }`: Output a Codecov badge with additional options

Available options for `codecov = { ... }`:

* `component = "<component>"`: Add the `component=<component>` query parameter to the badge image URL
* `flag = "<flag>"`: Add the `flag=<flag>` query parameter to the badge image URL

<!--
#### Custom badges (`badge.{badges,badges-*}.{custom,custom-*}`)

If you want to use a badge that is not supported by `cargo-sync-rdme`, you can use the `custom` configuration item.

```toml
[package.metadata.cargo-sync-rdme.badge]
badges = {
  custom = { name = "<badge name>", link = "<link>", image = "<image>" },
}
```

You can use template variables in `<badge name>`, `<link>`, and `<image>`.
Available template variables are as follows:

* `{{package_name}}`: The value of `package.name` in `Cargo.toml`
* `{{crate_name}}`: The value of `package.name` with `-` replaced with `_` in `Cargo.toml`
* `{{version}}`: The value of `package.version` in `Cargo.toml`
* `{{repository}}`: The value of `package.repository` in `Cargo.toml`
* `{{rust-version}}`: The value of `package.rust-version` in `Cargo.toml`
-->

### Multiple badge items with the same kind

If you want to use the same kind of badge multiple times, add the `-*` suffix to the configuration item name.

```toml
[package.metadata.cargo-sync-rdme.badge]
badges = {
  github-actions-foo = { workflows = "foo.yml" },
  github-actions-bar = { workflows = "bar.yml" },
}
```

### Badge groups

You can define multiple badge groups and select the badge groups to output using the `badge.badges-<group-name>` configuration item.

```toml
[package.metadata.cargo-sync-rdme.badge]

# foo group definition
badges-foo = {
  license = true,
  maintenance = true,
}

# bar group definition
badges-bar = {
  crates-io = true,
  docs-rs = true,
}
```

You can embed the badge groups in the README using the following syntax:

```markdown
Before sync:
<!-- cargo-sync-rdme badge:<group-name> -->

After sync:
<!-- cargo-sync-rdme badge:<group-name> [[ -->
badges...
<!-- cargo-sync-rdme ]] -->
```

## Rustdoc configuration

You can customize the crate documentation generated by `cargo-sync-rdme` by adding the following section to `Cargo.toml`:

```toml
[package.metadata.cargo-sync-rdme.rustdoc]
html-root-url = "<url>"
mappings = {
  SomeType = "./docs/some-type.md",
}
```

The following configuration items are available for rustdoc:

* `rustdoc.html-root-url`: Set the root URL of the documentation for the packages in the workspace.
   The default value is `https://docs.rs/<package name>/<package version>`.

   If you host the documentation of main/master branch on GitHub Pages, you can set the value to `https://<user>.github.io/<repository>/`.
* `rustdoc.mappings`: Allows you to provide an override for a path to a URL.