Improve readme

README.md

@@ -1,53 +1,88 @@
-# Wiki
+# Publish to GitHub wiki action
 
-This action takes the contents of a provided directory and synchronizes it with your
-repository's wiki. This allows, for example, pull requests for the wiki.
+📖 Deploy docs from your source tree to the GitHub wiki
 
-The goal is to expose the wiki to PRs, so that potential contributors who aren't
-collaborators can contribute to the wiki and go through a review process. Alternatively,
-one can disabled the "Restrict editing to collaborators only" setting for their wiki,
-but this allows the community to make unreviewed, potentially unwanted, changes.
+## Features
 
-By default, it will use the `.github/wiki` directory.
+🌐 Works across repositories (with a [PAT]) \
+📚 Pretty interface for Markdown docs \
+⤴️ Lets you open PRs for wiki docs
 
-## Before using this action
+## Usage
+
+❗ 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.
+
+<div align="center">
 
-You probably want to commit your wiki in its initial state before using this action.
-This is because this action will commit *all* differences between the wiki and the
-`.github/wiki` (or other specified directory) contents.
+![](https://user-images.githubusercontent.com/61068799/225441831-d3587ceb-0462-4591-bf00-ee56b040fe00.png)
 
-```bash
-git clone https://github.com/octocat/my-repo.wiki.git .github/wiki
-rm -rf .github/wiki/.git
-git add .github/wiki
-git commit -m "Add wiki to repo"
+</div>
+
+Create a workflow file named something like `.github/workflows/wiki.yml` and add
+a job that uses this action to it! 🎉
+
+```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/[email protected]
 ```
 
-## Usage
+⚠️ Make sure you enable the `content: write` permission! GitHub recently
+[changed the default permissions granted to jobs] for new repositories.
 
-Unfortunately, `${{ github.token }}` does not have access to updating wiki
-repositories, so it is necessary to create a new PAT.
+☁️ 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.
 
-Start by creating a classic token. If your repository is public, you only need the
-`public_repo` scope. Otherwise, you must grant the full `repo` scope. Then, add
-the token to your repository secrets so that it can be used in your workflow.
+### Options
 
-Simple example usage can be found in [this workflow file](./.github/workflows/update-wiki.yml).
+- **`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.
+
+- **`wiki-directory`:** 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.
 
 ## Alternatives
 
-There are numerous GitHub wiki publishing actions on the GitHub Actions
-marketplace. There are, however, two that stick out. The
-[newrelic/wiki-sync-action][newrelic-wiki-sync-action] is a good choice for a
-GitHub wiki action if you need bidirectional synchronization when someone edits
-the live wiki. This can be beneficial for non-technical contributors. There's also
-[Andrew-Chen-Wang/github-wiki-action][andrew-chen-wang-github-wiki-action]
-which is a direct competitor to this project. The tradeoff that it makes is using a
-Docker image which may not work with Windows-based jobs.
-
-For more information about other alternatives, you can check out [Issue #4][issue-4]
-which has a longer list of alternatives.
-
-[newrelic-wiki-sync-action]: https://github.com/newrelic/wiki-sync-action#readme
-[andrew-chen-wang-github-wiki-action]: https://github.com/Andrew-Chen-Wang/github-wiki-action#readme
-[issue-4]: https://github.com/spenserblack/actions-wiki/issues/4
+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. Specifically, it offers more
+automagic ✨ features in exchange for more complexity.
+
+📚 If you're interested in more discussion of alternatives, check out [#4].
+
+<!-- prettier-ignore-start -->
+[newrelic/wiki-sync-action]: https://github.com/newrelic/wiki-sync-action#readme
+[Andrew-Chen-Wang/github-wiki-action]: https://github.com/Andrew-Chen-Wang/github-wiki-action#readme
+[#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
+[GitHub PAT]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
+[changed the default permissions granted to jobs]: https://github.blog/changelog/2023-02-02-github-actions-updating-the-default-github_token-permissions-to-read-only/
+<!-- prettier-ignore-end -->