# Templates
## Placeholders
Templates are git repositories whose files can contain placeholders. A placeholder can be seen as
a variable that is substituted by another value upon expansion of the template.
`cargo-generate` supports both builtin variables/placeholders and custom defined ones.
Additionally, **all filters and tags** of the liquid template language are supported.
For more information, check out the [Liquid Documentation on `Tags` and `Filters`][liquid].
[liquid]: https://shopify.github.io/liquid
You can use those placeholders in the file and directory names of the generated project.
For example, for a project named `awesome`, the filename `{{project-name}}/{{project-name}}.rs` will be transformed to `awesome/awesome.rs` during generation.
Only files that are **not** listed in the exclude settings will be templated.
> ⚠️ NOTE: invalid characters for a filename or directory name will be sanitized after template substitution. Invalid is e.g. `/` or `\`.
> ⚠️ **Deprecated** in favor of using [ignore in `cargo-generate.toml`](https://cargo-generate.github.io/cargo-generate/templates/ignoring.html)
>
> You can also add a `.genignore` file to your template. The files listed in the `.genignore` file
> will be removed from the local machine when `cargo-generate` is run on the end user's machine.
> The `.genignore` file is always ignored, so there is no need to list it in the `.genignore` file.
### Additional `liquid` filters
Following are filters that `cargo-generate` expands the `liquid` language with.
* **`rhai`**
Tries to run the argument as a `rhai` script. Whatever the script returns will be the output of
the filter.
Example Liquid:
```liquid
Here we try to run a rhai script: {{"script_name.rhai" | rhai}}
```
> ⚠️ NOTE: `Liquid` does not support failing filters, thus if the script fails for any reason,
> `cargo-generate` will simply print a warning message to stderr, and `Liquid` will leave
> the substitution in its original form.
* **`kebab_case`**
`"We are going to inherit the earth."` => `"we-are-going-to-inherit-the-earth"`
* **`lower_camel_case`**
`"It is we who built these palaces and cities."` => `"itIsWeWhoBuiltThesePalacesAndCities"`
* **`pascal_case`**
Same as `upper_camel_case`
* **`shouty_kebab_case`**
`"We are going to inherit the earth."` => `"WE-ARE-GOING-TO-INHERIT-THE-EARTH"`
* **`shouty_snake_case`**
`"That world is growing in this minute."` => `"THAT_WORLD_IS_GROWING_IN_THIS_MINUTE"`
* **`snake_case`**
`"We carry a new world here, in our hearts."` => `"we_carry_a_new_world_here_in_our_hearts"`
* **`title_case`**
`"We have always lived in slums and holes in the wall."` => `"We Have Always Lived In Slums And Holes In The Wall"`
* **`upper_camel_case`**
`"We are not in the least afraid of ruins."` => `"WeAreNotInTheLeastAfraidOfRuins"`
## Templates by the community
It's encouraged to classify your template repository [with a GitHub topic](https://docs.github.com/en/github/administering-a-repository/managing-repository-settings/classifying-your-repository-with-topics) labeled `cargo-generate`.
So that every developer can find the template via [cargo-generate topic on GitHub](https://github.com/topics/cargo-generate).
If you have a great template, please tag your repository with the topic [and tweet about it](https://twitter.com/intent/tweet?text=See%20my%20new%20%23cargogenerate%20%23template%20%0A%0A%3E%20your%20link%20goes%20here) by including the hashtag [`#cargogenerate`](https://twitter.com/search?q=%23cargogenerate&src=typed_query) (since twitter does not support hashtags with `-`).
> ⚠️ Note: the list of [currently available templates](https://github.com/cargo-generate/cargo-generate/blob/main/TEMPLATES.md) is still available, but is now deprecated.
### Example for `--bin` and `--lib`
A template could be prepared in a way to act as a binary or a library. For example the `Cargo.toml` might look like:
```toml
[package]
# the usual stuff
[dependencies]
{% if crate_type == "bin" %}
structopt = "0.3.21"
{% endif %}
# other general dependencies
{% if crate_type == "bin" %}
[[bin]]
path = "src/main.rs"
name = "{{crate_name}}-cli"
{% endif %}
```
Now a user of this template could decide weather they want the binary version by passing `--bin`
or use only the library version by passing `--lib` as a command line argument.