https://github.com/spenserblack/actions-wiki
:open_book: Deploy docs from your source tree to a GitHub wiki
https://github.com/spenserblack/actions-wiki
action actions github github-actions github-wiki wiki
Last synced: 10 months ago
JSON representation
:open_book: Deploy docs from your source tree to a GitHub wiki
- Host: GitHub
- URL: https://github.com/spenserblack/actions-wiki
- Owner: spenserblack
- License: mit
- Created: 2023-01-10T18:18:11.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-06-14T14:03:04.000Z (over 2 years ago)
- Last Synced: 2025-04-04T04:01:37.919Z (10 months ago)
- Topics: action, actions, github, github-actions, github-wiki, wiki
- Language: TypeScript
- Homepage: https://github.com/marketplace/actions/wiki-update
- Size: 104 KB
- Stars: 11
- Watchers: 2
- Forks: 2
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Publish to GitHub wiki action
[](https://github.com/spenserblack/actions-wiki/actions/workflows/ci.yml)
[](https://github.com/spenserblack/actions-wiki/actions/workflows/dogfood.yml)
[](https://github.com/spenserblack/actions-wiki/actions/workflows/check-dist.yml)
[](https://codecov.io/gh/spenserblack/actions-wiki)
📖 Deploy docs from your source tree to the GitHub wiki
🌐 Works across repositories (with a [PAT][pat]) \
📚 Pretty interface for Markdown docs \
⤴️ Lets you open PRs for wiki docs \
💻 Supports `runs-on: windows-*`
## Usage
Getting started is easy! Just create a GitHub Actions workflow file that uses
spenserblack/actions-wiki and you're good to go! 🚀 Here's a ready-made example
to help you blast off:
```yml
name: Publish wiki
on:
push:
branches: [main]
paths: [wiki/**, .github/workflows/publish-wiki.yml]
concurrency:
group: wiki
cancel-in-progress: true
permissions:
contents: write
jobs:
wiki:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: spenserblack/actions-wiki@
with:
# Whatever directory you choose will be mirrored to the GitHub
# .wiki.git. The default is .github/wiki.
path: wiki
```
❗ Make sure you turn on the GitHub wiki feature in your repo's settings menu.
You'll also need to _manually_ create a dummy page to initialize the git repo
that powers the GitHub wiki. If you don't, when we push to `your-repo.wiki.git`,
your workflow will fail because the wiki doesn't exist.
⚠️ You'll need to remember to enable the `contents: write` permission! GitHub
recently [changed the default permissions granted to jobs][default-permissions-update] for new repositories.
### Publishing to a different repository
If you're pushing to a wiki that's **not the current repository** you'll need to
get a [GitHub PAT][pat] to push to it. The default `${{ secrets.GITHUB_TOKEN }}`
won't cut it! You can [generate a PAT][generate-a-pat] in your GitHub Settings.
For example, if you created octocat/gigantic-mega-project-wiki to hold the wiki
and you want to publish it to the GitHub wiki that belongs to _another
repository_ like octocat/gigantic-mega-project, you'd use a step like this in
one of your GitHub Actions workflows.
```yml
- uses: spenserblack/actions-wiki@
with:
path: .
# Notice that we use a github.com/ prefix here to support enterprise GitHub
# deployments on other domains.
repository: github.com/octocat/gigantic-mega-project
# Make sure this token has the appropriate push permissions!
token: ${{ secrets.GIGANTIC_MEGA_PROJECT_GITHUB_TOKEN }}
```
### Options
- **`repository`:** The repository housing the wiki. Use this if you're
publishing to a wiki that's not the current repository. You _can include a
domain prefix_ if you have a hosted GitHub instance that you want to push to.
Default is `${{ github.repository }}` with the implicit `github.com` domain.
- **`token`:** `${{ github.token }}` is the default. This token is used when
cloning and pushing wiki changes.
- **`path`:** The directory to use for your wiki contents. Default:
`.github/wiki`.
- **`commit-message`:** The message to use when committing new content. Default
is `Update wiki ${{ github.sha }}`. You probably don't need to change this,
since this only applies if you look _really closely_ in your wiki.
- **`dry-run`:** Whether or not to actually attempt to push changes back to the
wiki itself. If this is set to `true`, we instead print the remote URL and do
not push to the remote wiki. The default is `false`. This is useful for
testing.
## Alternatives
There are quite a few GitHub wiki publishing actions on the [GitHub Actions marketplace][actions-marketplace]. There are, however, two that stick out. The
[newrelic/wiki-sync-action][newrelic-action] is a good choice for if you need bidirectional
synchronization when someone edits the live wiki. This can be beneficial for
less-technical contributors. There's also [Andrew-Chen-Wang/github-wiki-action][andrew-chen-wang-action]
which is a direct competitor to this project. It offers more automatic features,
but has more complex configuration. It also [doesn't support `runs-on: windows-*`](https://github.com/Andrew-Chen-Wang/github-wiki-action/discussions/28).
📚 If you're interested in more discussion of alternatives, check out [#4][issue-4].
## Development
This is a GitHub Action, so we inevitably use [YAML][yaml-notes]. Make sure you quote the
right things! To test 🧪 the action, the current workflow is to open a PR and
then have the [`test.yml`](https://github.com/spenserblack/actions-wiki/blob/main/.github/workflows/test.yml) workflow run a `dry-run: true` iteration to
(hopefully) spot any flaws.
To get a better handle on the contribution process, check out our handy
[contributing guide][contributing]. Happy coding! 👋
[newrelic-action]: https://github.com/newrelic/wiki-sync-action#readme
[andrew-chen-wang-action]: https://github.com/Andrew-Chen-Wang/github-wiki-action#readme
[issue-4]: https://github.com/spenserblack/actions-wiki/issues/4
[pat]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
[default-permissions-update]: https://github.blog/changelog/2023-02-02-github-actions-updating-the-default-github_token-permissions-to-read-only/
[actions-marketplace]: https://github.com/marketplace?type=actions
[generate-a-pat]: https://github.com/settings/tokens?type=beta
[contributing]: https://github.com/spenserblack/actions-wiki/blob/main/CONTRIBUTING.md
[yaml-notes]: https://earthly.dev/blog/intercal-yaml-and-other-horrible-programming-languages/