# cargo-doc2readme  [](https://crates.io/crates/cargo-doc2readme) [](https://codeberg.org/msrd0/cargo-doc2readme) [](https://github.com/rust-lang/rust/releases/tag/1.85.0)
`cargo doc2readme` is a cargo subcommand to create a readme file to display on
[Codeberg][__link0], [GitHub][__link1] or [crates.io][__link2],
containing the rustdoc comments from your code.
## Installation
### AlpineLinux
On AlpineLinux 3.23 and newer, you can install cargo-doc2readme using apk:
```bash
apk add cargo-doc2readme
```
### ArchLinux
If you are using ArchLinux, you can install cargo-doc2readme from the AUR:
```bash
yay -S cargo-doc2readme
```
### Other
On other Operating Systems, make sure you have Rust installed (preferrably using your
distributions package manager, but you can also use [rustup][__link3]) and
then run the following command:
```bash
cargo install --locked cargo-doc2readme
```
## Usage
To generate your readme, simply run
```bash
cargo doc2readme
```
This will output the readme to a file called `README.md`, using `README.j2` or the
built-in template.
### Custom template
`cargo doc2readme` comes with a builtin template for your readme. You can view this
template [here][__link4].
You can also provide your own template, either by placing a file called `README.j2`
next to your readme, by using the command line flag, or by using the config file.
The template is in Jinja 2 format and will be parsed by [`minijinja`][__link5].
Please see [`TemplateContext`][__link6] for a list of all available placeholders.
### Usage in CI
If you want to run this using Forgejo or GitHub Actions, you can use the pre-built
docker image:
```yaml
readme:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: docker://codeberg.org/msrd0/cargo-doc2readme
with:
entrypoint: cargo
args: doc2readme --check
```
This will use the latest stable Rust version available when the latest release of
cargo doc2readme was created. If you need a newer/nightly Rust compiler, use the
`codeberg.io/msrd0/cargo-doc2readme:nightly` docker image instead.
## Features
* parse markdown from your rustdoc comments and embed it into your readme
* use existing crates to parse Rust and Markdown
* support your `[CustomType]` rustdoc links
* default, minimalistic readme template with some useful badges
* custom readme templates
## Non-Goals
The following list may or may not describe the current functionality of
`cargo doc2readme`. However, there is explicitly no guarantee for that in the future
nor will it be considered a bug if they stop describing the current state.
* verbatim copy of your markdown
* easy readability of the generated markdown source code
## Similar tools
[`cargo readme`][__link7] is a similar tool. However, it brings its own Rust code
parser that only covers the 95% use case. Also, it does not support Rust path links
introduced in Rust 1.48, making your readme ugly since the unsupported links are shown
as raw markdown, and being less convenient for the reader that has to search [docs.rs][__link8]
instead of clicking on a link.
[`cargo rdme`][__link9] is another tool which places your rustdoc into your readme.
However, it does not come with template support, which is helpful for bigger repositories
that contain multiple crates, and has only very basic support for Rust path links. All
links not starting with `crate::` or `::std` are unsupported by `cargo rdme`.
## Why not just `#![doc = include_str!("../README.md")]`?
For simple cases, doing the above will work just fine. However, this approach has
several drawbacks:
1. No intra-doc links (which was the main motivation behind writing
`cargo doc2readme` in the first place).
1. There is no possibility to add content to the git-repo’s or crates.io’s readme
that is not shown by rustdoc.
Some projects may choose to add content to their
readme that is only relevant to developers and/or people looking at the source
code (for example, explaining the folder structure, or the contribution process).
Those information is not relevant for the docs.rs page.
1. There is no possibility to inject information from the environment.
Some projects may, for example, choose to give you a line or two of content for
your `Cargo.toml`. I’ve seen too many projects tell you to write `foo = "*"`.
Please don’t do that. Either use
```rust
#![doc = concat!(env!("CARGO_PKG_NAME"), " = \"", env!("CARGO_PKG_VERSION"), "\"")]
```
if you want it to show up on docs.rs, or use
```jinja2
{{ crate }} = "{{ crate_version }}"
```
in the readme template.
See [`TemplateContext`][__link10] for a list of all available placeholders, and
[The Cargo Book][__link11]
for a list of all environment variables set by cargo at compile time.
1. There is no way to hide code from the example codeblocks in your readme.
In order for the doc tests to be able to verify that your code compiles, you often
need setup code. This code is likely not relevant for the example, and should
therefore be hidden. In rustdoc, you can prefix those lines with a sharp (`#`)
to hide them. `cargo doc2readme` knows this and does not add those lines to your
readme.
1. If you create a codeblock with a flag, for example <code>\`\`\`edition2021</code>,
your markdown previewer will interpret that as the language of the codeblock.
rustdoc and `cargo doc2readme` remove those flags, and add `rust` as the language
to all codeblocks.
1. rustfmt will not format your example code. If you use nightly rustfmt and set
`format_code_in_doc_comments = true` (which I highly recommend), rustfmt will
format all example code in Rust before it gets written by `cargo doc2readme`
into your readme.
## Stability Guarantees
This project adheres to semantic versioning. All versions will be tested against the
latest stable rust version at the time of the release. All non-bugfix changes to the
rustdoc input processing and markdown output or the default readme template are
considered breaking changes, as well as any non-backwards-compatible changes to the
command-line arguments or to these stability guarantees. All other changes, including
any changes to the Rust code, or bumping the MSRV, are not considered breaking changes.
[__cargo_doc2readme_dependencies_info]: ggGmYW0CYXZlMC43LjJhdIQb2o_SNWoR6AAb3_T-k0ODPHwbnQW7uS_D2XsbjVFFtK-lC3BhYvVhcoQbHysRTQGI5UQbasIDIWVPGqcbBCP0y07ezVQbJVZv6w-4AYJhZIKDcGNhcmdvLWRvYzJyZWFkbWVlMC43LjJwY2FyZ29fZG9jMnJlYWRtZYJpbWluaWppbmphZjIuMTcuMQ
[__link0]: https://codeberg.org
[__link1]: https://github.com
[__link10]: https://docs.rs/cargo-doc2readme/0.7.2/cargo_doc2readme/?search=TemplateContext
[__link11]: https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates
[__link2]: https://crates.io
[__link3]: https://rustup.rs/
[__link4]: https://codeberg.org/msrd0/cargo-doc2readme/src/branch/main/src/README.j2
[__link5]: https://crates.io/crates/minijinja/2.17.1
[__link6]: https://docs.rs/cargo-doc2readme/0.7.2/cargo_doc2readme/?search=TemplateContext
[__link7]: https://github.com/webern/cargo-readme
[__link8]: https://docs.rs
[__link9]: https://github.com/orium/cargo-rdme