docs: big restructure of existing documentation

.github/workflows/ci.yml

@@ -85,22 +85,6 @@ jobs:
         if: matrix.os == 'ubuntu-latest'
         run: task lint
 
-      - name: misspell
-        if: matrix.os == 'ubuntu-latest'
-        uses: reviewdog/action-misspell@v1
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          locale: "UK"
-          exclude: |
-            ./go.mod
-            ./go.sum
-            *.css
-            ./docs/yarn.lock
-            ./docs/tailwind.config.js
-            ./.goreleaser.yml
-            ./.github/**
-            ./internal/git/utils.go
-
       - name: Code Coverage
         if: matrix.os == 'ubuntu-latest'
         uses: codecov/codecov-action@v3

.github/workflows/docker-description.yml

@@ -21,9 +21,8 @@
 name: docker-description
 on:
   push:
-    branches:
-      - main
-  workflow_dispatch:
+    tags:
+      - "v*.*.*"
 
 jobs:
   goreleaser:

.github/workflows/docs.yml

@@ -20,31 +20,57 @@
 
 name: docs
 on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
   push:
     branches:
       - main
+    tags:
+      - "v*.*.*"
     paths:
       - "docs/**"
-  # Allow the workflow to be triggered manually
+      - "mkdocs.yml"
   workflow_dispatch:
 jobs:
-  docs:
+  build-docs:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v2
-      - name: Deploy GH Pages
-        uses: mhausenblas/mkdocs-deploy-gh-pages@master
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          CONFIG_FILE: docs/mkdocs.yml
-      - name: Set Custom Domain
-        uses: octokit/request-action@v2.x
-        id: pages_domain
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - run: docker pull squidfunk/mkdocs-material
+
+      - name: Build
+        run: docker run --rm -v ${PWD}:/docs squidfunk/mkdocs-material build
+
+      - name: HTML Test
+        uses: wjdp/htmltest-action@master
         with:
-          route: PUT /repos/{owner}/{repo}/pages
-          owner: gembaadvantage
-          repo: uplift
-          cname: upliftci.dev
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          path: site
+          config: htmltest.yml
+
+      - name: Patch mkdocs.yml Site URL
+        if: startsWith(github.ref, 'refs/tags/v') || ${{ github.event_name == 'workflow_dispatch' }}
+        uses: jacobtomlinson/gha-find-replace@v2
+        with:
+          find: 'site_url: ""'
+          replace: 'site_url: "https://upliftci.dev"'
+          regex: false
+          include: mkdocs.yml
+
+      - name: Patch mkdocs.yml Edit URI
+        if: startsWith(github.ref, 'refs/tags/v') || ${{ github.event_name == 'workflow_dispatch' }}
+        uses: jacobtomlinson/gha-find-replace@v2
+        with:
+          find: 'edit_uri: ""'
+          replace: 'edit_uri: "edit/main/docs"'
+          regex: false
+          include: mkdocs.yml
+
+      - name: Deploy documentation
+        if: startsWith(github.ref, 'refs/tags/v') || ${{ github.event_name == 'workflow_dispatch' }}
+        run: docker run --rm -v ${PWD}:/docs squidfunk/mkdocs-material gh-deploy --force

.gitignore

@@ -24,5 +24,8 @@ uplift
 dist/
 
 # Mkdocs related
-docs/site
-.DS_store
+site/
+.DS_store
+
+# VSCode
+.vscode/

README.md

@@ -5,7 +5,11 @@
   <h1>Uplift</h1>
 </div>
 
-Semantic versioning the easy way. Automatic tagging and version bumping of files in your repositories based on your commit messages. Powered by [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). Easy to include in your CI.
+By harnessing the power of [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), Uplift simplifies the release management of your project through your use of commit messages.
+
+Built for Continuous Integration (CI), Uplift is incredibly simple to use, and its modular design allows you to choose which release cycle features you want to incorporate into your workflow. It adheres to the Semantic Versioning specification and plays nicely with other tools.
+
+And it's built using Go so that you can install it anywhere!
 
 ## Documentation
 

docs/CNAME

@@ -0,0 +1 @@
+upliftci.dev

docs/bumping-files.md

@@ -0,0 +1,41 @@
+# Bumping your Files
+
+If you only need to bump the semantic version within specific files, Uplift has you covered. A `.uplift.yml` configuration file is required for this to work. Bumping files using JSON Paths and Regex are currently supported.
+
+```yaml linenums="1"
+# .uplift.yml
+
+bumps:
+  - file: package.json
+    json:
+      - path: "version"
+        semver: true
+
+  - file: chart/my-chart/Chart.yaml
+    regex:
+      - pattern: "version: $VERSION"
+        semver: true
+        count: 1
+```
+
+```sh
+uplift bump
+```
+
+Please review our comprehensive [guide](./reference/config.md#bumps) on configuring file bumps.
+
+❤️ to the [github.com/tidwall/sjson](https://github.com/tidwall/sjson) library.
+
+## The $VERSION Token
+
+Writing a regex can be challenging at most times, so Uplift provides the `$VERSION` token for matching a semantic version with an optional `v` prefix. You can include this in any pattern you define within your config.
+
+## Prerelease Support
+
+:octicons-beaker-24: Experimental
+
+Uplift has early support for bumping files with prerelease metadata. You will need to calculate this upfront.
+
+```sh
+uplift bump --prerelease beta.1+20220930
+```

docs/changelog.md

@@ -0,0 +1,41 @@
+# Generating a Changelog
+
+Uplift can generate or amend a changelog (`CHANGELOG.md`) for your repository based on the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
+
+```sh
+uplift changelog
+```
+
+## Excluding Commits
+
+You can exclude commits from the changelog by specifying a list of commit prefixes.
+
+```sh
+uplift changelog --exclude chore,ci,test
+```
+
+## Changing the Commit Order
+
+Commits are written to a changelog in descending order, reflecting the behaviour of `git log`. Change this order by specifying `asc` (case insensitive).
+
+```sh
+uplift changelog --sort asc
+```
+
+## Output the Changelog Diff
+
+You can output the calculated changelog difference (_diff_) to `stdout` without modifying the local repository.
+
+```sh
+uplift changelog --diff-only
+```
+
+## Migrate an Existing Repository
+
+:octicons-beaker-24: Experimental
+
+If your repository does not contain a `CHANGELOG.md` file, you can generate one that spans its entire history. A word of warning, this does require a tagging structure to be in place.
+
+```sh
+uplift changelog --all
+```

docs/content/ci/awscodebuild.md → docs/ci/awscodebuild.md

@@ -1,8 +1,8 @@
 # AWS CodeBuild
 
-AWS CodeBuild can be used as a standalone service when running uplift. This guide assumes CodeBuild was configured manually through the AWS Console and only focuses on the gotchas[^1].
+AWS CodeBuild can be used as a standalone service when running Uplift. This guide assumes CodeBuild was configured manually through the AWS Console and focuses on the gotchas[^1].
 
-CodeBuild will always receive a git clone with a detached HEAD. By default, uplift will [error](../faq/gitdetached.md) in this scenario. When performing a release, this will need to be resolved through a `git checkout`. The `CODEBUILD_SOURCE_VERSION` variable contains the necessary git reference.
+CodeBuild will always receive a git clone with a detached HEAD. By default, Uplift will [error](../faq/gitdetached.md) in this scenario. When performing a release, this will need to be resolved through a `git checkout`. The `CODEBUILD_SOURCE_VERSION` variable contains the necessary git reference.
 
 ## IAM
 
@@ -60,7 +60,7 @@ phases:
       - uplift release
 ```
 
-1. Without this uplift will lack any [credentials](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.git-credential-helper) when attempting to push code back to the source SCM.
+1. Without this Uplift will lack any [credentials](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.git-credential-helper) when attempting to push code back to the source SCM.
 2. This can be simplified to `git checkout $CODEBUILD_SOURCE_VERSION` when cloning from GitHub directly
 
 ### Official Uplift Image

docs/content/ci/awscodepipeline.md → docs/ci/awscodepipeline.md

@@ -4,13 +4,13 @@ AWS provides two developer services for building code, `AWS CodePipeline` and `A
 
 ## CodePipeline
 
-By default, CodePipeline clones a repository to S3 without the `.git` metadata folder. A [full clone](https://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials-codecommit-gitclone.html)[^2] is needed for uplift to run.
+By default, CodePipeline clones a repository to S3 without the `.git` metadata folder. A [full clone](https://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials-codecommit-gitclone.html)[^2] is needed for Uplift to run.
 
 ![CodePipeline Artefact Format](../static/codepipeline-fullclone.png){ align=left }
 
 ## CodeBuild
 
-CodeBuild will always receive a git clone with a detached HEAD. By default, uplift will [error](../faq/gitdetached.md) in this scenario. If performing a release, this will need to be resolved through a `git checkout`. However, the branch name is not exposed to CodeBuild by default. CodePipeline provides a [variable](https://docs.aws.amazon.com/codepipeline/latest/userguide/reference-variables.html) `#{SourceVariables.BranchName}` that can be mapped to CodeBuild as an environment variable:
+CodeBuild will always receive a git clone with a detached HEAD. By default, Uplift will [error](../faq/gitdetached.md) in this scenario. If performing a release, this will need to be resolved through a `git checkout`. However, the branch name is not exposed to CodeBuild by default. CodePipeline provides a [variable](https://docs.aws.amazon.com/codepipeline/latest/userguide/reference-variables.html) `#{SourceVariables.BranchName}` that can be mapped to CodeBuild as an environment variable:
 
 ![CodeBuild Branch Environment Variable](../static/codebuild-env.png){ align=left }
 
@@ -84,7 +84,7 @@ phases:
       - uplift release
 ```
 
-1. Without this uplift will lack any [credentials](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.git-credential-helper) when attempting to push code back to the source SCM.
+1. Without this Uplift will lack any [credentials](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.git-credential-helper) when attempting to push code back to the source SCM.
 2. The `BRANCH_NAME` environment variable can be referenced directly within the buildspec, once mapped.
 
 #### Official Uplift Image

docs/ci/circleci.md

@@ -0,0 +1,33 @@
+# CircleCI
+
+An example YAML file for configuring Uplift to run on [CircleCI](https://circleci.com). As Uplift is designed to push changes back to your GitHub repository, you will need to ensure CircleCI is granted [write access](https://circleci.com/docs/2.0/gh-bb-integration) to your repository.
+
+```{ .yaml .annotate linenums="1" }
+# .circleci/config.yml
+
+version: 2.1
+workflows:
+  main:
+    jobs:
+      - release:
+          filters:
+            branches:
+              # Only trigger on the main branch
+              only: main
+jobs:
+  release:
+    docker:
+      # Can use whatever base image you like
+      - image: cimg/go:1.18
+    steps:
+      # Configure an SSH key that provides write access to your GitHub repository
+      - add_ssh_keys:
+          fingerprints:
+            - "3b:c7:44:c9:34:ab:a4:fd:6c:33:4e:a7:7a:97:79:55" # (1)
+      - checkout
+      # Additional actions specified here
+      - run: curl https://raw.githubusercontent.com/gembaadvantage/uplift/main/scripts/install | bash
+      - run: uplift release
+```
+
+1. By default, CircleCI will only have read-only access to your repository. For Uplift to work, write access is required. This can be achieved by accessing a repository as a [machine-user](https://circleci.com/docs/2.0/gh-bb-integration/#controlling-access-via-a-machine-user) and then loading its [SSH key](https://circleci.com/docs/2.0/configuration-reference/#add-ssh-keys) into the pipeline by its fingerprint

docs/content/ci/cirrusci.md → docs/ci/cirrusci.md

@@ -1,6 +1,6 @@
 # Cirrus CI
 
-An example YAML file for configuring uplift to run on [Cirrus CI](https://cirrus-ci.org/). Access to GitHub is managed through their dedicated [GitHub Application](https://cirrus-ci.org/guide/quick-start/?installation_id=25016880&setup_action=install). As uplift requires write permissions to your repository, a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) needs to be configured with the `public_repo` permission and added to Cirrus CI as an [encrypted variable](https://cirrus-ci.org/guide/writing-tasks/#encrypted-variables).
+An example YAML file for configuring Uplift to run on [Cirrus CI](https://cirrus-ci.org/). Access to GitHub is managed through their dedicated [GitHub Application](https://cirrus-ci.org/guide/quick-start/?installation_id=25016880&setup_action=install). As Uplift requires write permissions to your repository, a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) needs to be configured with the `public_repo` permission and added to Cirrus CI as an [encrypted variable](https://cirrus-ci.org/guide/writing-tasks/#encrypted-variables).
 
 ```{ .yaml .annotate linenums="1" }
 # .cirrus.yml
@@ -20,8 +20,8 @@ task:
     GITHUB_TOKEN: ENCRYPTED[!ID!] # (2)
 ```
 
-1. As Cirrus CI uses [go-git](https://github.com/go-git/go-git) for cloning repositories from GitHub, by default it doesn't fetch tags. Using the `--fetch-all` flag with uplift ensures all tags are pulled before attempting a release
-2. `!ID!` should be replaced with the internal ID generated by Cirrus CI. `GITHUB_TOKEN` can be replaced with any chosen variable name, and must be reflected in the remote URL. `environment` and `env` are interchangeable.
+1. As Cirrus CI uses [go-git](https://github.com/go-git/go-git) for cloning repositories from GitHub, by default, it doesn't fetch tags. Using the `--fetch-all` flag with Uplift ensures all tags are pulled before attempting a release
+2. `!ID!` should be replaced with the internal ID generated by Cirrus CI. `GITHUB_TOKEN` can be replaced with any chosen variable name and must be reflected in the remote URL. `environment` and `env` are interchangeable.
 
 Uplift publishes docker images that support both amd64 and arm64 architectures, Cirrus CI can be configured to use [arm64](https://cirrus-ci.org/guide/linux/#linux-containers):
 
@@ -43,4 +43,4 @@ task:
     GITHUB_TOKEN: ENCRYPTED[!ID!]
 ```
 
-1. Cirrus CI will seamlessly download the arm64 image from either [DockerHub](https://hub.docker.com/r/gembaadvantage/uplift) or [GHCR](https://github.com/gembaadvantage/uplift/pkgs/container/uplift) though the use of the `--platform` flag.
+1. Cirrus CI will seamlessly download the arm64 image from either [DockerHub](https://hub.docker.com/r/gembaadvantage/uplift) or [GHCR](https://github.com/gembaadvantage/uplift/pkgs/container/uplift) through the use of the `--platform` flag.

docs/content/ci/codefresh.md → docs/ci/codefresh.md

@@ -1,6 +1,6 @@
 # Codefresh
 
-An example YAML file for configuring uplift to run on [Codefresh](https://g.codefresh.io/welcome). To ensure uplift can push changes back to your repository, you will need to store your Personal Access Token as a [shared configuration](https://codefresh.io/docs/docs/configure-ci-cd-pipeline/shared-configuration/) and [expose](https://codefresh.io/docs/docs/configure-ci-cd-pipeline/shared-configuration/#using-shared-environment-variables) it to your pipeline as an environment variable. Which in this example is `GH_UPLIFT`.
+An example YAML file for configuring Uplift to run on [Codefresh](https://g.codefresh.io/welcome). To ensure Uplift can push changes back to your repository, you will need to store your Personal Access Token as a [shared configuration](https://codefresh.io/docs/docs/configure-ci-cd-pipeline/shared-configuration/) and [expose](https://codefresh.io/docs/docs/configure-ci-cd-pipeline/shared-configuration/#using-shared-environment-variables) it to your pipeline as an environment variable, which in this example is `GH_UPLIFT`.
 
 ```{ .yaml .annotate linenums="1" }
 # codefresh.yml

docs/content/ci/drone.md → docs/ci/drone.md

@@ -1,6 +1,6 @@
 # Drone
 
-An example YAML file for configuring uplift to run on [Drone](https://www.drone.io/)[^1]. Instructions for deploying a self-hosted instance of drone can be found [here](https://docs.drone.io/server/provider/github/). As uplift requires write permissions to your repository, a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) needs to be configured with the `public_repo` permission and added to Drone as an [encrypted secret](https://docs.drone.io/secret/encrypted/).
+An example YAML file for configuring Uplift to run on [Drone](https://www.drone.io/)[^1]. Instructions for deploying a self-hosted instance of drone can be found [here](https://docs.drone.io/server/provider/github/). Uplift requires write permissions to your repository. A [Personal Access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) needs to be configured with the `public_repo` permission and added to Drone as an [encrypted secret](https://docs.drone.io/secret/encrypted/).
 
 ```{ .yaml .annotate linenums="1" }
 # .drone.yml

docs/content/ci/github.md → docs/ci/github.md

@@ -1,6 +1,6 @@
 # GitHub Action
 
-The official [GitHub Action](https://github.com/gembaadvantage/uplift-action) can be used to configure uplift within your workflow. As uplift is designed to push changes back to your repository, you will need to provide it with an access token[^1]. This is by [design](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow).
+The official [GitHub Action](https://github.com/gembaadvantage/uplift-action) can be used to configure Uplift within your workflow. As Uplift is designed to push changes back to your repository, you will need to provide it with an access token[^1]. This is by [design](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow).
 
 ```{ .yaml .annotate linenums="1" }
 # .github/workflows/ci.yml
@@ -29,12 +29,12 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # (2)
 ```
 
-1. Setting a `fetch-depth` of 0 will ensure all tags are retrieved which is required by uplift to determine the next semantic version
+1. Setting a `fetch-depth` of 0 will ensure all tags are retrieved, which is required by Uplift to determine the next semantic version
 2. When you use the repository's `GITHUB_TOKEN` to perform tasks, events triggered by the `GITHUB_TOKEN` will not create a new workflow run.
 
 ## Triggering another Workflow
 
-To ensure uplift triggers another workflow run when tagging the repository, a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) should be created and stored as a [secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets). This will then replace the default `GITHUB_TOKEN` as follows:
+To ensure Uplift triggers another workflow run when tagging the repository, a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) should be created and stored as a [secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets). This will then replace the default `GITHUB_TOKEN` as follows:
 
 ```{ .yaml .annotate linenums="1" hl_lines="24" }
 # .github/workflows/ci.yml