From 73e212ce35e343c2d046dc69e46d3aecb7901a38 Mon Sep 17 00:00:00 2001 From: Lars Kappert Date: Mon, 21 Oct 2024 11:29:49 +0200 Subject: [PATCH] Format docs --- README.md | 130 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 76 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index f6eea00..1e29999 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ npm install --save-dev @release-it/conventional-changelog ## Configuration -In the [release-it](https://github.com/release-it/release-it) config, for example: +In the [release-it][1] config, for example: ```json "plugins": { @@ -21,27 +21,25 @@ In the [release-it](https://github.com/release-it/release-it) config, for exampl } ``` -The plugin is a wrapper around conventional-changelog packages -[conventional-recommended-bump](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-recommended-bump#readme), -[conventional-changelog-core](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core#api) -and more. +The plugin is a wrapper around conventional-changelog packages [conventional-recommended-bump][2], +[conventional-changelog-core][3] and more. ## Contents -- [`preset`](#preset) +- [`preset`][4] - Bump - - [`commitsOpts`](#commitsopts) - - [`tagOpts`](#tagopts) - - [`whatBump`](#whatbump) - - [`ignoreRecommendedBump`](#ignorerecommendedbump) - - [`strictSemVer`](#strictsemver) + - [`commitsOpts`][5] + - [`tagOpts`][6] + - [`whatBump`][7] + - [`ignoreRecommendedBump`][8] + - [`strictSemVer`][9] - Changelog - - [`infile`](#infile) - - [`header`](#header) - - [`context`](#context) - - [`gitRawCommitsOpts`](#gitrawcommitsopts) - - [`parserOpts`](#parseropts) - - [`writerOpts`](#writeropts) + - [`infile`][10] + - [`header`][11] + - [`context`][12] + - [`gitRawCommitsOpts`][13] + - [`parserOpts`][14] + - [`writerOpts`][15] ### `preset` @@ -82,34 +80,27 @@ Use an object with `name` and `types` to use a custom preset: } ``` -This is passed as the first argument to -[`bumper.loadPreset`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/README.md#api) -(in both bumper and changelog writer). +This is passed as the first argument to [`bumper.loadPreset`][16] (in both bumper and changelog writer). -See the -[Conventional Changelog Configuration Spec (v2.1.0)](https://github.com/conventional-changelog/conventional-changelog-config-spec/blob/master/versions/2.1.0/README.md) -for the configuration object to pass as `preset`. +See the [Conventional Changelog Configuration Spec (v2.1.0)][17] for the configuration object to pass as `preset`. ## Bump ### `tagOpts` -- This option will be passed as the first argument to - [`bumper.tag`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/README.md#api) -- [Type definition for `tagOpts` → look for `GetSemverTagsParams`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/git-client/src/types.ts) +- This option will be passed as the first argument to [`bumper.tag`][16] +- [Type definition for `tagOpts` → look for `GetSemverTagsParams`][18] ### `commitsOpts` -- This option will be passed as the first argument to - [`bumper.commits`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/README.md#api) -- [Type definition for `commitsOpts` → look for `GetCommitsParams`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/git-client/src/types.ts) +- This option will be passed as the first argument to [`bumper.commits`][16] +- [Type definition for `commitsOpts` → look for `GetCommitsParams`][18] ### `whatBump` -- This option will be passed as the first argument to - [`bumper.bump`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/README.md#api) -- [Type definition for `whatBump` → look for `Preset['whatBump']`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/src/types.ts) -- Use the `false` Boolean value to skip releasing a new version. +- This option will be passed as the first argument to [`bumper.bump`][16] +- [Type definition for `whatBump` → look for `Preset['whatBump']`][19] +- Use `false` to skip releasing a new version: ```json { @@ -149,8 +140,8 @@ Default value: `undefined` - Set a filename as `infile` to write the changelog to. If this file does not exist yet, it's created with the full history. -- When `infile` is not set, the changelog generated by this plugin will still be used as release notes for e.g. - [GitHub Releases](https://github.com/release-it/release-it/blob/master/docs/github-releases.md). +- When `infile` is not set, the changelog generated by this plugin will still be used as release notes for e.g. [GitHub + Releases][20]. - Set `infile: false` to disable the changelog writing (and only use the recommended bump for the next version). ### `header` @@ -175,9 +166,7 @@ Set the main header for the changelog document: Default value: `undefined` -This option will be passed as the second argument (`context`) to -[conventional-changelog-core](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core#context), -for example: +This option will be passed as the second argument (`context`) to [conventional-changelog-core][21], for example: ```json "plugins": { @@ -193,9 +182,8 @@ for example: Default value: `undefined` -Options for -[`git-raw-commits`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/git-raw-commits#api). -For example, you can use the following option to include merge commits into changelog: +Options for [`git-raw-commits`][22]. For example, you can use the following option to include merge commits into +changelog: ```json { @@ -212,11 +200,9 @@ For example, you can use the following option to include merge commits into chan ### `parserOpts` - Default value: `undefined` -- Options for - [`conventional-commits-parser`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#api) -- This option will also be passed as the second argument to - [`bumper.parserOptions`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/README.md#api) -- [Type definition for `parserOpts` → look for `ParserOptions`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-commits-parser/src/types.ts) +- Options for [`conventional-commits-parser`][23] +- This option will also be passed as the second argument to [`bumper.parserOptions`][16] +- [Type definition for `parserOpts` → look for `ParserOptions`][24] For example, you can use the following option to set the merge pattern during parsing the commit message: @@ -235,9 +221,8 @@ For example, you can use the following option to set the merge pattern during pa ### `writerOpts` - Default value: `undefined` -- Options for - [`conventional-changelog-writer`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#api) -- [Type definition for `writerOpts` → look for `Options`](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-writer/src/types/options.ts) +- Options for [`conventional-changelog-writer`][25] +- [Type definition for `writerOpts` → look for `Options`][26] For example, you can use the following option to group the commits by 'scope' instead of 'type' by default. @@ -289,8 +274,45 @@ Depending on your shell or OS this may differ. ## GitHub Actions -When using this plugin in a GitHub Action, make sure to set -[`fetch-depth: 0`](https://github.com/actions/checkout#fetch-all-history-for-all-tags-and-branches) so the history is -available to determine the correct recommended bump and changelog. - -Also see https://github.com/release-it/release-it/blob/master/docs/ci.md#github-actions +When using this plugin in a GitHub Action, make sure to set [`fetch-depth: 0`][27] so the history is available to +determine the correct recommended bump and changelog. + +Also see [https://github.com/release-it/release-it/blob/master/docs/ci.md#github-actions][28] + +[1]: https://github.com/release-it/release-it +[2]: + https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-recommended-bump#readme +[3]: + https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core#api +[4]: #preset +[5]: #commitsopts +[6]: #tagopts +[7]: #whatbump +[8]: #ignorerecommendedbump +[9]: #strictsemver +[10]: #infile +[11]: #header +[12]: #context +[13]: #gitrawcommitsopts +[14]: #parseropts +[15]: #writeropts +[16]: + https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/README.md#api +[17]: https://github.com/conventional-changelog/conventional-changelog-config-spec/blob/master/versions/2.1.0/README.md +[18]: https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/git-client/src/types.ts +[19]: + https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/src/types.ts +[20]: https://github.com/release-it/release-it/blob/master/docs/github-releases.md +[21]: + https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core#context +[22]: https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/git-raw-commits#api +[23]: + https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#api +[24]: + https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-commits-parser/src/types.ts +[25]: + https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#api +[26]: + https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-writer/src/types/options.ts +[27]: https://github.com/actions/checkout#fetch-all-history-for-all-tags-and-branches +[28]: https://github.com/release-it/release-it/blob/master/docs/ci.md#github-actions