📖 Deploy docs from your source tree to the GitHub wiki
🌐 Works across repositories (with a PAT)
📚 Pretty interface for Markdown docs
💻 Supports runs-on: windows-*
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:
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@<version>
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.
contents: write permission! GitHub
recently changed the default permissions granted to jobs for new repositories.
If you're pushing to a wiki that's not the current repository you'll need to
get a GitHub PAT to push to it. The default ${{ secrets.GITHUB_TOKEN }}
won't cut it! You can 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.
- uses: spenserblack/actions-wiki@<version>
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 }}-
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 implicitgithub.comdomain. -
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 isUpdate 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 totrue, we instead print the remote URL and do not push to the remote wiki. The default isfalse. This is useful for testing.
There are quite a few GitHub wiki publishing actions on the GitHub Actions marketplace. There are, however, two that stick out. The
newrelic/wiki-sync-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
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-*.
📚 If you're interested in more discussion of alternatives, check out #4.
This is a GitHub Action, so we inevitably use YAML. 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 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. Happy coding! 👋
![allcontributors[bot] avatar](https://avatars.githubusercontent.com/in/23186?v=4 "allcontributors[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent