Standard Readme

Generate Standard Readme-compatible READMEs

Standard Readme is a standard style for writing READMEs created by @RichardLitt. He himself had implemented a Yeoman generator for creating standardized READMEs just like this one. This tool is heavily inspired by Richard's generator. I just wanted to write an implementation that can be distributed as a single statically linked binary. This implementation supports every feature the original one does and should generate near-identical READMEs.

See the Standard Readme repo for more information on Standard Readmes.

Table of Contents

• Install
• Usage
• Publishing standard-readme
• Maintainers
• Contributing
• License

Install

You can download the correct version for your operating system and architecture using the download.ps1 script. Don't let the name fool you, the script works with Bash/ZSH on Linux or macOS too!

On Linux or macOS run:

curl -s https://raw.githubusercontent.com/kfkonrad/generator-standard-readme-rust/main/download.ps1 | bash
# OR
wget -qO- https://raw.githubusercontent.com/kfkonrad/generator-standard-readme-rust/main/download.ps1 | bash

On Windows run:

Invoke-Expression ((Invoke-WebRequest -Uri "https://raw.githubusercontent.com/kfkonrad/generator-standard-readme-rust/main/download.ps1").Content)

If you don't like running scripts from the internet you can find and download the application in the releases section of this repo as well.

You can also install from source using cargo:

cargo install standard-readme

Usage

Simply run standard-readme:

standard-readme

You will be asked interactively for any additional information necessary to generate the README.

Publishing standard-readme

To publish a new version of standard-readme on crates.io you can run cargo publish like with any other Rust project (assuming you have sufficient access to the crate).

To publish a new version of standard-readme as a GitHub release you can run ./release.sh (again assuming you have sufficient privileges). The release.sh script performs several steps:

1. Install cross and git-cliff if necessary
2. Check for the GitHub CLI gh
3. If running on macOS: Install the rustup targets aarch64-apple-darwin and x86_64-apple-darwin if necessary
4. Compile standard-readme for all configured targets. macOS binaries will only be created if run on a Mac. Linux and Windows binaries are cross-compiles with cross
5. Compress and collect the binaries for each platform
6. Create and push a git tag based on the version found in Cargo.toml
7. Create a GitHub release for that version. The changelog gets generated using git-cliff and the compressed binaries are uploaded automatically

release.sh will detect a dirty git state (such as unstaged or uncommitted changes) and skip creating a tag or release.

It also supports a dry-run mode that performs all the builds but skips the git tag and GitHub release steps as well. To perform a dry run exectute ./release.sh --dry-run. This is the only supported argument, all other arguments will be ignored.

release.sh is compatible with both the BSD and GNU variants of all tools used. Other than the Rust toolchain only the GitHub CLI gh needs to be installed for release.sh to be able to run.

Maintainers

@kfkonrad

Contributing

PRs accepted.

Small note: If editing the README, please conform to the standard-readme specification.

License

MIT © 2024 Kevin F. Konrad