diff --git a/README.md b/README.md index 0879270..9ce8823 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,10 @@ This action allows you to create badges for your README.md with [shields.io](https://shields.io) which may change with every commit. To do this, this action does not need to push anything to your repository! This action supports all [configuration options of shields.io/endpoint](https://shields.io/endpoint) and can be used in various ways: -* Show custom CI statistics from GitHub actions, such as code coverage or detailed test results. -* Show metadata of your repository such as [lines of code, comment line percentage](https://schneegans.github.io/tutorials/2022/04/18/badges), ... -* Basically anything which may change from commit to commit! + +- Show custom CI statistics from GitHub actions, such as code coverage or detailed test results. +- Show metadata of your repository such as [lines of code, comment line percentage](https://schneegans.github.io/tutorials/2022/04/18/badges), ... +- Basically anything which may change from commit to commit! ## How Does It Work? @@ -25,7 +26,7 @@ This JSON object may look like this: } ``` -This JSON object is then uploaded as a file to a *gist* ([click here for an example](https://gist.github.com/Schneegans/2ab8f1d386f13aaebccbd87dac94068d)) and can be transformed to a badge like [![badge](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/schneegans/2ab8f1d386f13aaebccbd87dac94068d/raw/hello-world.json)](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/schneegans/2ab8f1d386f13aaebccbd87dac94068d/raw/hello-world.json) with the **shields.io/endpoint**. Here is the URL of this example badge: +This JSON object is then uploaded as a file to a _gist_ ([click here for an example](https://gist.github.com/Schneegans/2ab8f1d386f13aaebccbd87dac94068d)) and can be transformed to a badge like [![badge](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/schneegans/2ab8f1d386f13aaebccbd87dac94068d/raw/hello-world.json)](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/schneegans/2ab8f1d386f13aaebccbd87dac94068d/raw/hello-world.json) with the **shields.io/endpoint**. Here is the URL of this example badge: ``` https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/schneegans/2ab8f1d386f13aaebccbd87dac94068d/raw/hello-world.json @@ -34,9 +35,10 @@ https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/schneegan ## Configuration 1. Head over to [gist.github.com](https://gist.github.com/) and create a new gist. You can name the file `test.json`, but this can be changed later as well. You will need the ID of the gist (this is the long alphanumerical part of its URL) later. -2. Navigate to [github.com/settings/tokens](https://github.com/settings/tokens) and create a new token with the *gist* scope. -3. Go to the *Secrets* page of the settings of your repository (Settings > Secrets > Actions) and add this token as a new secret. You can give it any name, for example `GIST_SECRET`. **If you use Dependabot to automatically update dependencies of your repository, you also have to add this secret to Dependabot's secrets (Settings > Secrets > Dependabot).** +2. Navigate to [github.com/settings/tokens](https://github.com/settings/tokens) and create a new token with the _gist_ scope. +3. Go to the _Secrets_ page of the settings of your repository (Settings > Secrets > Actions) and add this token as a new secret. You can give it any name, for example `GIST_SECRET`. **If you use Dependabot to automatically update dependencies of your repository, you also have to add this secret to Dependabot's secrets (Settings > Secrets > Dependabot).** 4. Add something like the following to your workflow: + ```yml - name: Create Awesome Badge uses: schneegans/dynamic-badges-action@v1.6.0 @@ -60,39 +62,37 @@ Embed the badge with: ### Required Input Parameters -Parameter | Description -----------|------------ -`auth` | A secret token with the *gist* scope. -`gistID` | The ID of the target gist. Something like `8f6459c2417de7534f64d98360dde866`. -`filename` | The target filename - each gist may contain several files. This should have the `.json` extension. - +| Parameter | Description | +| ---------- | -------------------------------------------------------------------------------------------------- | +| `auth` | A secret token with the _gist_ scope. | +| `gistID` | The ID of the target gist. Something like `8f6459c2417de7534f64d98360dde866`. | +| `filename` | The target filename - each gist may contain several files. This should have the `.json` extension. | ### Optional Input Parameters -Parameter | Description -----------|------------ -`forceUpdate` | Default is `false`. If set to `true`, the gist will be updated even if the content did not change. - +| Parameter | Description | +| ------------- | -------------------------------------------------------------------------------------------------- | +| `forceUpdate` | Default is `false`. If set to `true`, the gist will be updated even if the content did not change. | ### Shields.io Parameters (optional) All these parameters are optional. They are directly passed to [shields.io](https://shields.io). See the [official documentation](https://shields.io/endpoint) for more detailed explanations. -Parameter | Description -----------|------------ -`label` | Required. The left text of the badge. -`message` | Required. The right text of the badge. -`labelColor` | The left color of the badge. -`color` | The right color of the badge. For custom colors wrap color string in quotes `"#bf155b"`. This parameter is ignored if the `valColorRange`, `maxColorRange`, and `minColorRange` are set. -`isError` | The color will be red and cannot be overridden. -`namedLogo` | A logo name from [simpleicons.org](http://simpleicons.org/). -`logoSvg` | An svg-string to be used as logo. -`logoColor` | The color for the logo. -`logoWidth` | The space allocated for the logo. -`logoPosition` | The position of the logo. -`style` | The style like "flat" or "social". -`cacheSeconds` | The cache lifetime in seconds (must be greater than 300). +| Parameter | Description | Supported in SVG Mode | +| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| `label` | Required. The left text of the badge. | +| `message` | Required. The right text of the badge. | +| `labelColor` | The left color of the badge. | +| `color` | The right color of the badge. For custom colors wrap color string in quotes `"#bf155b"`. This parameter is ignored if the `valColorRange`, `maxColorRange`, and `minColorRange` are set. | +| `isError` | The color will be red and cannot be overridden. | +| `namedLogo` | A logo name from [simpleicons.org](http://simpleicons.org/). | +| `logoSvg` | An svg-string to be used as logo. | +| `logoColor` | The color for the logo. | +| `logoWidth` | The space allocated for the logo. | +| `logoPosition` | The position of the logo. | +| `style` | The style like "flat" or "social". | +| `cacheSeconds` | The cache lifetime in seconds (must be greater than 300). | ### Color Range Parameters (optional) @@ -112,15 +112,14 @@ Starting with version 1.3.0 of this action, the color of the right side of the b For this, the following parameters can be used. -Parameter | Description -----------|------------ -`valColorRange` | A numerical value used to define the message color. Usually this should be between `maxColorRange` and `minColorRange`. This is required if you want to use the color range feature. -`maxColorRange` | If `valColorRange` assumes this value, the badge will be green. This is required if you want to use the color range feature. -`minColorRange` | If `valColorRange` assumes this value, the badge will be red. This is required if you want to use the color range feature. -`invertColorRange` | If the range should be inverted, causing a smaller value to have green color. Defaults to `false`. -`colorRangeSaturation` | Saturation used by the color range feature. Defaults to 100. -`colorRangeLightness` | Lightness used by the color range feature. Defaults to 40. - +| Parameter | Description | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `valColorRange` | A numerical value used to define the message color. Usually this should be between `maxColorRange` and `minColorRange`. This is required if you want to use the color range feature. | +| `maxColorRange` | If `valColorRange` assumes this value, the badge will be green. This is required if you want to use the color range feature. | +| `minColorRange` | If `valColorRange` assumes this value, the badge will be red. This is required if you want to use the color range feature. | +| `invertColorRange` | If the range should be inverted, causing a smaller value to have green color. Defaults to `false`. | +| `colorRangeSaturation` | Saturation used by the color range feature. Defaults to 100. | +| `colorRangeLightness` | Lightness used by the color range feature. Defaults to 40. | ### Using Environment Variables as Parameters [![badge](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/schneegans/2ab8f1d386f13aaebccbd87dac94068d/raw/answer.json)](https://gist.githubusercontent.com/schneegans/2ab8f1d386f13aaebccbd87dac94068d) @@ -148,7 +147,7 @@ For all values in between, the color will be interpolated. ## Contributing to Dynamic Badges Action -Whenever you encounter a :beetle: **bug** or have :tada: **feature request**, +Whenever you encounter a :beetle: **bug** or have :tada: **feature request**, report this via [Github issues](https://github.com/schneegans/dynamic-badges-action/issues). We are happy to receive contributions in the form of **pull requests** via Github. @@ -156,22 +155,22 @@ Feel free to fork the repository, implement your changes and create a merge requ ### Git Commit Messages -Commits should start with a Capital letter and should be written in present tense (e.g. __:tada: Add cool new feature__ instead of __:tada: Added cool new feature__). +Commits should start with a Capital letter and should be written in present tense (e.g. **:tada: Add cool new feature** instead of **:tada: Added cool new feature**). You should also start your commit message with **one** applicable emoji. This does not only look great but also makes you rethink what to add to a commit. Make many but small commits! -Emoji | Description -------|------------ -:tada: `:tada:` | When you added a cool new feature. -:wrench: `:wrench:` | When you refactored / improved a small piece of code. -:hammer: `:hammer:` | When you refactored / improved large parts of the code. -:sparkles: `:sparkles:` | When you applied clang-format. -:art: `:art:` | When you improved / added assets like themes. -:rocket: `:rocket:` | When you improved performance. -:memo: `:memo:` | When you wrote documentation. -:beetle: `:beetle:` | When you fixed a bug. -:twisted_rightwards_arrows: `:twisted_rightwards_arrows:` | When you merged a branch. -:fire: `:fire:` | When you removed something. -:truck: `:truck:` | When you moved / renamed something. +| Emoji | Description | +| --------------------------------------------------------- | ------------------------------------------------------- | +| :tada: `:tada:` | When you added a cool new feature. | +| :wrench: `:wrench:` | When you refactored / improved a small piece of code. | +| :hammer: `:hammer:` | When you refactored / improved large parts of the code. | +| :sparkles: `:sparkles:` | When you applied clang-format. | +| :art: `:art:` | When you improved / added assets like themes. | +| :rocket: `:rocket:` | When you improved performance. | +| :memo: `:memo:` | When you wrote documentation. | +| :beetle: `:beetle:` | When you fixed a bug. | +| :twisted_rightwards_arrows: `:twisted_rightwards_arrows:` | When you merged a branch. | +| :fire: `:fire:` | When you removed something. | +| :truck: `:truck:` | When you moved / renamed something. | ### Version Numbers