@qiwi/semantic-release-gh-pages-plugin
Version:
gh-pages publishing plugin for semantic-release
99 lines (81 loc) • 7 kB
Markdown
# @qiwi/semantic-release-gh-pages-plugin
[](https://github.com/qiwi/semantic-release-gh-pages-plugin/actions)
[](https://codeclimate.com/github/qiwi/semantic-release-gh-pages-plugin/test_coverage)
[](https://codeclimate.com/github/qiwi/semantic-release-gh-pages-plugin/maintainability)
[](https://www.npmjs.com/package/@qiwi/semantic-release-gh-pages-plugin)
gh-pages publishing plugin for [semantic-release](https://github.com/semantic-release/semantic-release)
| Step | Description |
|--------------------|------------------------------------------------------------------------------------------------|
| `verifyConditions` | Verify the presence of the `GH_TOKEN` set via [environment variables](#environment-variables). |
| `publish` | Pushes commit to the [documentation branch](#options) |
## Install
```bash
# yarn
yarn add @qiwi/semantic-release-gh-pages-plugin --dev
# npm
npm i @qiwi/semantic-release-gh-pages-plugin -D
```
## Usage
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)
```json
{
"release": {
"branch": "master",
"verifyConditions": [
"@semantic-release/changelog",
"@semantic-release/npm",
"@semantic-release/git",
"@qiwi/semantic-release-gh-pages-plugin"
],
"publish": [
"@semantic-release/npm",
"@semantic-release/github",
[
"@qiwi/semantic-release-gh-pages-plugin",
{
"msg": "updated",
"branch": "docs"
}
]
]
}
}
```
or even shorter if default settings are used:
```json
{
"release": {
"branch": "master",
"plugins": [
"@semantic-release/release-notes-generator",
"@semantic-release/changelog",
"@semantic-release/git",
"@semantic-release/github",
"@semantic-release/npm",
"@qiwi/semantic-release-gh-pages-plugin"
]
}
}
```
## Configuration
### Environment variables
| Variable | Description |
|------------------------------|-----------------------------------------------------------|
| `GH_TOKEN` or `GITHUB_TOKEN` | **Required.** The token used to authenticate with GitHub. |
### Options
| Option | Description | Default |
|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `msg` | Commit message template | `docs updated <%= nextRelease.gitTag %>` |
| `src` | Documentation directory. Used as gh-pages [dir](https://github.com/tschaub/gh-pages?tab=readme-ov-file#dir) | `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 |
| `dst` | Destination directory. gh-pages [dest](https://github.com/tschaub/gh-pages?tab=readme-ov-file#optionsdest) | `.` (root) |
| `branch` | Docs branch to push | `gh-pages` |
| `branches` | Optional list of src-to-target branches association. If defined it suppresses `branch` option. For example, `[['master', 'gh-pages'], ['beta', beta-docs]]` | undefined |
| `repositoryUrl` | Repository url | inherited from .git |
| `enterprise` | Disables host assertion for GitHub Enterprise domains | `false` |
| `pullTagsBranch` | Target branch for tags fetching hook. If '' empty string, skips this action | `globalConfig.branch` \|\| `master` |
| `dotfiles` | gh-pages [dotfiles](https://github.com/tschaub/gh-pages#optionsdotfiles) option | `false` |
| `add` | gh-pages [add](https://github.com/tschaub/gh-pages#optionsadd) option | `false` |
| `pattern` | gh-pages [src](https://github.com/tschaub/gh-pages#optionssrc) option. Use `:` to separate several values `**/*.md:**/*.png` | `**/*` |
## License
[MIT](./LICENSE)