docs(recipes): moved recipes to sub-directories to align with gitbook…

… expectations (#2246)

CONTRIBUTING.md

@@ -20,7 +20,7 @@ Help us keep **semantic-release** open and inclusive. Please read and follow our
 
 ### Improve documentation
 
-As a **semantic-release** user, you are the perfect candidate to help us improve our documentation: typo corrections, clarifications, more examples, new [recipes](docs/recipes/README.md), etc. Take a look at the [documentation issues that need help](https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Asemantic-release+archived%3Afalse+label%3A%22help+wanted%22+label%3Adocs+).
+As a **semantic-release** user, you are the perfect candidate to help us improve our documentation: typo corrections, clarifications, more examples, new [recipes](docs/recipes), etc. Take a look at the [documentation issues that need help](https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Asemantic-release+archived%3Afalse+label%3A%22help+wanted%22+label%3Adocs+).
 
 Please follow the [Documentation guidelines](#documentation).
 

README.md

@@ -37,9 +37,9 @@ This removes the immediate connection between human emotions and version numbers
 - Notify maintainers and users of new releases
 - Use formalized commit message convention to document changes in the codebase
 - Publish on different distribution channels (such as [npm dist-tags](https://docs.npmjs.com/cli/dist-tag)) based on git merges
-- Integrate with your [continuous integration workflow](docs/recipes/README.md#ci-configurations)
+- Integrate with your [continuous integration workflow](docs/recipes/release-workflow/README.md#ci-configurations)
 - Avoid potential errors associated with manual releases
-- Support any [package managers and languages](docs/recipes/README.md#package-managers-and-languages) via [plugins](docs/usage/plugins.md)
+- Support any [package managers and languages](docs/recipes/release-workflow/README.md#package-managers-and-languages) via [plugins](docs/usage/plugins.md)
 - Simple and reusable configuration via [shareable configurations](docs/usage/shareable-configurations.md)
 
 ## How does it work?
@@ -74,9 +74,9 @@ For each new commit added to one of the release branches (for example: `master`,
 **semantic-release** offers various ways to control the timing, the content and the audience of published releases.
 See example workflows in the following recipes:
 
-- [Using distribution channels](docs/recipes/distribution-channels.md#publishing-on-distribution-channels)
-- [Maintenance releases](docs/recipes/maintenance-releases.md#publishing-maintenance-releases)
-- [Pre-releases](docs/recipes/pre-releases.md#publishing-pre-releases)
+- [Using distribution channels](docs/recipes/release-workflow/distribution-channels.md#publishing-on-distribution-channels)
+- [Maintenance releases](docs/recipes/release-workflow/maintenance-releases.md#publishing-maintenance-releases)
+- [Pre-releases](docs/recipes/release-workflow/pre-releases.md#publishing-pre-releases)
 
 ### Release steps
 
@@ -117,10 +117,10 @@ In order to use **semantic-release** you need:
   - [Plugins](docs/extending/plugins-list.md)
   - [Shareable configuration](docs/extending/shareable-configurations-list.md)
 - Recipes
-  - [CI configurations](docs/recipes/README.md)
-  - [Git hosted services](docs/recipes/README.md)
-  - [Release workflow](docs/recipes/README.md)
-  - [Package managers and languages](docs/recipes/README.md)
+  - [CI configurations](docs/recipes/release-workflow/README.md)
+  - [Git hosted services](docs/recipes/release-workflow/README.md)
+  - [Release workflow](docs/recipes/release-workflow/README.md)
+  - [Package managers and languages](docs/recipes/release-workflow/README.md)
 - Developer guide
   - [JavaScript API](docs/developer-guide/js-api.md)
   - [Plugins development](docs/developer-guide/plugin.md)

SUMMARY.md

@@ -14,18 +14,18 @@
 - [Shareable configuration](docs/extending/shareable-configurations-list.md)
 
 ## Recipes
-- [CI configurations](docs/recipes/README.md#ci-configurations)
-  - [CircleCI 2.0](docs/recipes/circleci-workflows.md)
-  - [Travis CI](docs/recipes/travis.md)
-  - [GitLab CI](docs/recipes/gitlab-ci.md)
-  - [GitHub Actions](docs/recipes/github-actions.md)
-  - [Jenkins CI](docs/recipes/jenkins-ci.md)
-- [Git hosted services](docs/recipes/README.md#git-hosted-services)
-  - [Git authentication with SSH keys](docs/recipes/git-auth-ssh-keys.md)
-- [Release Workflow](docs/recipes/README.md#release-workflow)
-  - [Publishing on distribution channels](docs/recipes/distribution-channels.md)
-  - [Publishing maintenance releases](docs/recipes/maintenance-releases.md)
-  - [Publishing pre-releases](docs/recipes/pre-releases.md)
+- [CI configurations](docs/recipes/ci-configurations/README.md)
+  - [CircleCI 2.0](docs/recipes/ci-configurations/circleci-workflows.md)
+  - [Travis CI](docs/recipes/ci-configurations/travis.md)
+  - [GitLab CI](docs/recipes/ci-configurations/gitlab-ci.md)
+  - [GitHub Actions](docs/recipes/ci-configurations/github-actions.md)
+  - [Jenkins CI](docs/recipes/ci-configurations/jenkins-ci.md)
+- [Git hosted services](docs/recipes/git-hosted-services/README.md)
+  - [Git authentication with SSH keys](docs/recipes/git-hosted-services/git-auth-ssh-keys.md)
+- [Release Workflow](docs/recipes/release-workflow/README.md)
+  - [Publishing on distribution channels](docs/recipes/release-workflow/distribution-channels.md)
+  - [Publishing maintenance releases](docs/recipes/release-workflow/maintenance-releases.md)
+  - [Publishing pre-releases](docs/recipes/release-workflow/pre-releases.md)
 
 ## Developer guide
 - [JavaScript API](docs/developer-guide/js-api.md)

docs/README.md

@@ -2,6 +2,6 @@
 
 - [Usage](usage/README.md) - **semantic-release** installation and configuration
 - [Extending](extending/README.md) - Extending **semantic-release** with plugins and shareable configurations
-- [Recipes](recipes/README.md) - Community written recipes for common **semantic-release** use-cases
+- [Recipes](recipes/release-workflow/README.md) - Community written recipes for common **semantic-release** use-cases
 - [Developer Guide](developer-guide/README.md) - The essentials of writing a **semantic-release** plugin or shareable configurations
 - [Support](support/README.md) - FAQ and troubleshooting

docs/recipes/ci-configurations/README.md

@@ -0,0 +1,6 @@
+# CI configurations
+- [CircleCI 2.0 workflows](circleci-workflows.md)
+- [Travis CI](travis.md)
+- [GitLab CI](gitlab-ci.md)
+- [GitHub Actions](github-actions.md)
+- [Jenkins CI](jenkins-ci.md)

docs/recipes/circleci-workflows.md → docs/recipes/ci-configurations/circleci-workflows.md

@@ -2,9 +2,9 @@
 
 ## Environment variables
 
-The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured in [CircleCi Project Settings](https://circleci.com/docs/2.0/env-vars/#adding-environment-variables-in-the-app)..
+The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured in [CircleCi Project Settings](https://circleci.com/docs/2.0/env-vars/#adding-environment-variables-in-the-app)..
 
-Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/getting-started.md#getting-started).
+Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../../usage/getting-started.md#getting-started).
 
 ## Multiple Node jobs configuration
 

docs/recipes/github-actions.md → docs/recipes/ci-configurations/github-actions.md

@@ -2,15 +2,15 @@
 
 ## Environment variables
 
-The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured with [Secret Variables](https://docs.github.com/en/actions/reference/encrypted-secrets).
+The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured with [Secret Variables](https://docs.github.com/en/actions/reference/encrypted-secrets).
 
 In this example a publish type [`NPM_TOKEN`](https://docs.npmjs.com/creating-and-viewing-authentication-tokens) is required to publish a package to the npm registry. GitHub Actions [automatically populate](https://help.github.com/en/articles/virtual-environments-for-github-actions#github_token-secret) a [`GITHUB_TOKEN`](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) environment variable which can be used in Workflows.
 
 ## Node project configuration
 
 [GitHub Actions](https://github.com/features/actions) support [Workflows](https://help.github.com/en/articles/configuring-workflows), allowing to run tests on multiple Node versions and publish a release only when all test pass.
 
-**Note**: The publish pipeline must run on a [Node version that meets our version requirement](../support/node-version.md).
+**Note**: The publish pipeline must run on a [Node version that meets our version requirement](../../support/node-version.md).
 
 ### `.github/workflows/release.yml` configuration for Node projects
 

docs/recipes/gitlab-ci.md → docs/recipes/ci-configurations/gitlab-ci.md

@@ -2,21 +2,21 @@
 
 ## Environment variables
 
-The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured with [Protected variables](https://docs.gitlab.com/ce/ci/variables/README.html#protected-environment-variables).
+The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured with [Protected variables](https://docs.gitlab.com/ce/ci/variables/README.html#protected-environment-variables).
 
 **Note**: Make sure to configure your release branch as [protected](https://docs.gitlab.com/ce/user/project/protected_branches.html) in order for the CI/CD build to access the protected variables.
 
 ## Node project configuration
 
 GitLab CI supports [Pipelines](https://docs.gitlab.com/ee/ci/pipelines.html) allowing to test on multiple Node versions and publishing a release only when all test pass.
 
-**Note**: The publish pipeline must run a [Node version that meets our version requirement](../support/node-version.md).
+**Note**: The publish pipeline must run a [Node version that meets our version requirement](../../support/node-version.md).
 
 ### `.gitlab-ci.yml` configuration for Node projects
 
 This example is a minimal configuration for **semantic-release** with a build running Node 10 and 12. See [GitLab CI - Configuration of your jobs with .gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/README.html) for additional configuration options.
 
-**Note**: The`semantic-release` execution command varies depending on whether you are using a [local](../usage/installation.md#local-installation) or [global](../usage/installation.md#global-installation) **semantic-release** installation.
+**Note**: The`semantic-release` execution command varies depending on whether you are using a [local](../../usage/installation.md#local-installation) or [global](../../usage/installation.md#global-installation) **semantic-release** installation.
 
 ```yaml
 # The release pipeline will run only if all jobs in the test pipeline are successful
@@ -50,7 +50,7 @@ publish:
 
 This example is a minimal configuration for **semantic-release** with a build running Node 10 and 12. See [GitLab CI - Configuration of your jobs with .gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/README.html) for additional configuration options.
 
-**Note**: The`semantic-release` execution command varies depending if you are using a [local](../usage/installation.md#local-installation) or [global](../usage/installation.md#global-installation) **semantic-release** installation.
+**Note**: The`semantic-release` execution command varies depending if you are using a [local](../../usage/installation.md#local-installation) or [global](../../usage/installation.md#global-installation) **semantic-release** installation.
 
 
 ```yaml
@@ -83,7 +83,7 @@ release:
 
 ### `package.json` configuration
 
-A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
+A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation.
 
 ```json
 {

docs/recipes/jenkins-ci.md → docs/recipes/ci-configurations/jenkins-ci.md

@@ -2,15 +2,15 @@
 
 ## Environment variables
 
-The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured in [Jenkins Project Settings](https://www.jenkins.io/doc/pipeline/tour/environment/)..
+The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured in [Jenkins Project Settings](https://www.jenkins.io/doc/pipeline/tour/environment/)..
 
-Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/getting-started.md#getting-started).
+Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../../usage/getting-started.md#getting-started).
 
 ## Node.js project configuration
 
 ### `Jenkinsfile (Declarative Pipeline)` configuration for a Node.js job
 
-**Note**: The publish pipeline must run a Node version that [meets our requirement](../support/node-version.md).
+**Note**: The publish pipeline must run a Node version that [meets our requirement](../../support/node-version.md).
 
 This example is a minimal configuration for **semantic-release** with a build running a version of Node labelled as "node LTS".
 Since versions of Node are manually downloaded and labelled, we recommend keeping the version used for the release steps up-to-date with the latest LTS version.
@@ -50,7 +50,7 @@ pipeline {
 
 ### `package.json` configuration for a Node job
 
-A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
+A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation.
 
 ```json
 {

docs/recipes/travis.md → docs/recipes/ci-configurations/travis.md

@@ -2,17 +2,17 @@
 
 ## Environment variables
 
-The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured in [Travis Repository Settings](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-Settings) or with the [travis env set CLI](https://github.com/travis-ci/travis.rb#env).
+The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured in [Travis Repository Settings](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-Settings) or with the [travis env set CLI](https://github.com/travis-ci/travis.rb#env).
 
-Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/getting-started.md#getting-started).
+Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../../usage/getting-started.md#getting-started).
 
 ## Node.js projects configuration
 
 ### `.travis.yml` configuration for multiple Node.js jobs
 
 This example is a minimal configuration for **semantic-release** with a build running Node 14 and 16. See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options.
 
-This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
+This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
 
 It's recommended to run the `semantic-release` command in the [Travis `deploy` step](https://docs.travis-ci.com/user/customizing-the-build/#The-Build-Lifecycle) so if an error occurs the build will fail and Travis will send a notification.
 
@@ -43,7 +43,7 @@ jobs:
 
 ### `package.json` configuration for multiple Node jobs
 
-A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
+A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation.
 
 ```json
 {
@@ -57,13 +57,13 @@ A `package.json` is required only for [local](../usage/installation.md#local-ins
 
 For projects that require to be tested with one or multiple version of a Non-JavaScript [language](https://docs.travis-ci.com/user/languages), optionally on multiple [Operating Systems](https://docs.travis-ci.com/user/multi-os).
 
-This recipe cover the Travis specifics only. See [Non JavaScript projects recipe](../support/FAQ.md#can-i-use-semantic-release-to-publish-non-javascript-packages) for more information on the **semantic-release** configuration.
+This recipe cover the Travis specifics only. See [Non JavaScript projects recipe](../../support/FAQ.md#can-i-use-semantic-release-to-publish-non-javascript-packages) for more information on the **semantic-release** configuration.
 
 ### `.travis.yml` configuration for non-JavaScript projects
 
 This example is a minimal configuration for **semantic-release** with a build running [Go 1.6 and 1.7](https://docs.travis-ci.com/user/languages/go). See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options.
 
-This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
+This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
 
 It's recommended to run the `semantic-release` command in the [Travis `deploy` step](https://docs.travis-ci.com/user/customizing-the-build/#The-Build-Lifecycle) so if an error occurs the build will fail and Travis will send a notification.
 

docs/recipes/git-hosted-services/README.md

@@ -0,0 +1,2 @@
+# Git hosted services
+- [Git authentication with SSH keys](git-auth-ssh-keys.md)

docs/recipes/git-auth-ssh-keys.md → docs/recipes/git-hosted-services/git-auth-ssh-keys.md

@@ -1,6 +1,6 @@
 # Git authentication with SSH keys
 
-When using [environment variables](../usage/ci-configuration.md#authentication) to set up the Git authentication, the remote Git repository will automatically be accessed via [https](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_http_protocols), independently of the [`repositoryUrl`](../usage/configuration.md#repositoryurl) format configured in the **semantic-release** [Configuration](../usage/configuration.md#configuration) (the format will be automatically converted as needed).
+When using [environment variables](../../usage/ci-configuration.md#authentication) to set up the Git authentication, the remote Git repository will automatically be accessed via [https](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_http_protocols), independently of the [`repositoryUrl`](../../usage/configuration.md#repositoryurl) format configured in the **semantic-release** [Configuration](../../usage/configuration.md#configuration) (the format will be automatically converted as needed).
 
 Alternatively the Git repository can be accessed via [SSH](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_ssh_protocol) by creating SSH keys, adding the public one to your Git hosted account and making the private one available on the CI environment.
 

docs/recipes/release-workflow/README.md

@@ -0,0 +1,4 @@
+# Release workflow
+- [Publishing on distribution channels](distribution-channels.md)
+- [Publishing maintenance releases](maintenance-releases.md)
+- [Publishing pre-releases](pre-releases.md)