# Configuration

See [Configuration](https://gifnksm.github.io/cargo-sync-rdme/cargo_sync_rdme/config/index.html) for details.

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"

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

[package.metadata.cargo-sync-rdme.rustdoc]
html-root-url = "https://gifnksm.github.io/cargo-sync-rdme/"
```

## 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` (`package.metadata.cargo-sync-rdme.extra-targets`)

The `extra-targets` option specifies the paths to the files that are also updated when `cargo sync-rdme` is executed.

String or array of strings can be specified.

```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"

[package.metadata.cargo-sync-rdme.badge.badges]
maintenance = true
license = true
```

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

Output README file is as follows:

```markdown
<!-- cargo-sync-rdme badge [[ -->
[![Maintenance: actively-developed](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg)](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)](#license)
<!-- cargo-sync-rdme ]] -->
```

### `style` (`package.metadata.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 (`package.metadata.cargo-sync-rdme.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 (`package.metadata.cargo-sync-rdme.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 (`package.metadata.cargo-sync-rdme.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 (`package.metadata.cargo-sync-rdme.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) (`package.metadata.cargo-sync-rdme.badge.{badges,badges-*}.{rust-version,rust-version-*}`)

<!-- cargo-sync-rdme badge:rust-version [[ -->
[![Rust: ^1.74.0](https://img.shields.io/badge/rust-^1.74.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.metadata.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 (`package.metadata.cargo-sync-rdme.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)
<!-- 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 a GitHub Actions status badges.

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

    `<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 a GitHub Actions status badge 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 (`package.metadata.cargo-sync-rdme.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 = true` : Output a Codecov badge
* `codecov = false` : Do not output a Codecov badge

<!--
#### Custom badges

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.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 following:

* `{{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.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 be output using the `package.metadata.sync-rdme.badge.badges-<group-name>` section.

```toml
[package.metadata.sync-rdme.badge.badges-foo]
# foo group definition
license = true
maintenance = true

[package.metadata.sync-rdme.badge.badges-bar]
# bar group definition
crates-io = true
docs-rs = true
```

You can embed the badge groups in the `README.md` 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>"
```

The following configuration items are available for 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>/`.