| 1 | # @qiwi/semantic-release-gh-pages-plugin
|
| 2 |
|
| 3 | [](https://github.com/qiwi/semantic-release-gh-pages-plugin/actions)
|
| 4 | [](https://codeclimate.com/github/qiwi/semantic-release-gh-pages-plugin/test_coverage)
|
| 5 | [](https://codeclimate.com/github/qiwi/semantic-release-gh-pages-plugin/maintainability)
|
| 6 | [](https://www.npmjs.com/package/@qiwi/semantic-release-gh-pages-plugin)
|
| 7 |
|
| 8 | gh-pages publishing plugin for [semantic-release](https://github.com/semantic-release/semantic-release)
|
| 9 |
|
| 10 | | Step | Description |
|
| 11 | |--------------------|-------------|
|
| 12 | | `verifyConditions` | Verify the presence of the `GH_TOKEN` set via [environment variables](#environment-variables). |
|
| 13 | | `publish` | Pushes commit to the [documentation branch](#options) |
|
| 14 |
|
| 15 | ### Install
|
| 16 | ```bash
|
| 17 | # yarn
|
| 18 | yarn add @qiwi/semantic-release-gh-pages-plugin --dev
|
| 19 | # npm
|
| 20 | npm i @qiwi/semantic-release-gh-pages-plugin -D
|
| 21 | ```
|
| 22 |
|
| 23 | ### Usage
|
| 24 | Describe plugin configuration in [package.json / .releaserc.js](https://github.com/semantic-release/semantic-release/blob/master/docs/01-usage/plugins.md#plugins-configuration-options)
|
| 25 | ```json
|
| 26 | {
|
| 27 | "release": {
|
| 28 | "branch": "master",
|
| 29 | "verifyConditions": [
|
| 30 | "@semantic-release/changelog",
|
| 31 | "@semantic-release/npm",
|
| 32 | "@semantic-release/git",
|
| 33 | "@qiwi/semantic-release-gh-pages-plugin"
|
| 34 | ],
|
| 35 | "publish": [
|
| 36 | "@semantic-release/npm",
|
| 37 | "@semantic-release/github",
|
| 38 | [
|
| 39 | "@qiwi/semantic-release-gh-pages-plugin",
|
| 40 | {
|
| 41 | "msg": "updated",
|
| 42 | "branch": "docs"
|
| 43 | }
|
| 44 | ]
|
| 45 | ]
|
| 46 | }
|
| 47 | }
|
| 48 | ```
|
| 49 | or even shorter if default settings are used:
|
| 50 | ```json
|
| 51 | {
|
| 52 | "release": {
|
| 53 | "branch": "master",
|
| 54 | "plugins": [
|
| 55 | "@semantic-release/release-notes-generator",
|
| 56 | "@semantic-release/changelog",
|
| 57 | "@semantic-release/git",
|
| 58 | "@semantic-release/github",
|
| 59 | "@semantic-release/npm",
|
| 60 | "@qiwi/semantic-release-gh-pages-plugin"
|
| 61 | ]
|
| 62 | }
|
| 63 | }
|
| 64 | ```
|
| 65 |
|
| 66 | ### Configuration
|
| 67 | ##### Environment variables
|
| 68 |
|
| 69 | | Variable | Description |
|
| 70 | |------------------------------| --------------------------------------------------------- |
|
| 71 | | `GH_TOKEN` or `GITHUB_TOKEN` | **Required.** The token used to authenticate with GitHub. |
|
| 72 |
|
| 73 | ##### Options
|
| 74 |
|
| 75 | | Option | Description | Default |
|
| 76 | |-----------------|---------------------------------------------------------| --------|
|
| 77 | | `msg` | Commit message template | `docs updated <%= nextRelease.gitTag %>` |
|
| 78 | | `src` | Documentation directory | `docs`<br/><br/>**NOTE** don't forget to run docs builder (`yarn docs`, `yarn typedoc`, etc) as a part of your build step or any other way|
|
| 79 | | `dst` | Destination directory | `.` (root) |
|
| 80 | | `branch` | Docs branch to push | `gh-pages` |
|
| 81 | | `branches` | Optional list of src-to-target branches association. If defined it suppresses `branch` option. For example, `[['master', 'gh-pages'], ['beta', beta-docs]]` | undefined |
|
| 82 | | `repositoryUrl` | Repository url | inherited from .git |
|
| 83 | | `enterprise` | Disables host assertion for GitHub Enterprise domains | false |
|
| 84 | | `pullTagsBranch`| Target branch for tags fetching hook. If '' empty string, skips this action | `globalConfig.branch` \|\| `master` |
|
| 85 | | `dotfiles` | gh-pages [dotfiles](https://github.com/tschaub/gh-pages#optionsdotfiles) option | `false` |
|
| 86 | | `add` | gh-pages [add](https://github.com/tschaub/gh-pages#optionsadd) option | `false` |
|
| 87 |
|
| 88 | ### License
|
| 89 | [MIT](./LICENSE)
|