docs(GHA): small updates (#468)

* chore: rearrange GHA examples * docs: fix link, expand version usage * docs: fix frontmatter examples to reflect the latest * docs: language tweaks, link fixes, emojis * chore: grammar fix * revert: use `main` branch for docs links instead After thinking about it a little bit more, I think it makes more sense for the user to view the docs on `main`, versus on the latest tag. Our docs sync with every push to `main` and we should probably version them so they're better tied to version tags (i.e. they're only published when we bump versions), but I think this is the more intuitive solution for now.
readmeio · Mar 7, 2022 · f05d8f1 · f05d8f1
1 parent 0c7e364
commit f05d8f1
Show file tree

Hide file tree

Showing 3 changed files with 44 additions and 44 deletions.
diff --git a/README.md b/README.md
@@ -49,7 +49,7 @@ If you wish to get more information about any command within `rdme`, you can exe
 
 ### GitHub Actions
 
-> For a full GitHub Workflow file example and additional information on GitHub Actions usage, check out [our docs](https://docs.readme.com/docs/rdme).
+> For a full GitHub Workflow file example and additional information on GitHub Actions usage, check out [our docs](https://docs.readme.com/docs/rdme#github-actions-usage).
 
 For usage in [GitHub Actions](https://docs.github.com/actions), create [a new GitHub Workflow file](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) in the `.github/workflows` directory of your repository and add the following [steps](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) to your workflow:
 
@@ -74,7 +74,7 @@ To execute this command via GitHub Actions, the step would look like this:
     rdme: openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID
 ```
 
-Note that the `@XX` in the above examples refers to the version of `rdme` (e.g. `@7.0`). We recommend [configuring Dependabot to keep your actions up-to-date](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot).
+Note that the `@XX` in the above examples refers to the version of `rdme`. You can see examples featuring the latest version in [our docs](https://docs.readme.com/docs/rdme#example-syncing-an-openapi-definition). We recommend pointing to a fixed version, as opposed to pointing to something like the `main` branch, which could unexpectedly break your workflows. We also recommend [configuring Dependabot to keep your actions up-to-date](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot).
 
 ### OpenAPI / Swagger
 

diff --git a/documentation/legacy-github-action.md b/documentation/legacy-github-action.md
@@ -57,7 +57,7 @@ With [GitHub Actions](https://github.com/features/actions), it's super easy to a
 
 > ❗️Deprecated workflow instructions below
 >
-> Just as a reminder, the `readmeio/github-readme-sync` GitHub Action that's described below is now deprecated. The instructions are preserved for posterity. We strongly recommend all new and existing workflows to use our newest GitHub Action: [`rdme`](https://docs.readme.com/docs/rdme)!
+> Just as a reminder, the `readmeio/github-readme-sync` GitHub Action that's described below is now deprecated. The instructions are preserved for posterity. We strongly recommend all new and existing workflows use our newest GitHub Action: [`rdme`](https://docs.readme.com/docs/rdme)!
 
 Just create a new file in your GitHub repository called `.github/workflows/readme-github-sync.yml` and populate it with the template below. You only fill in one parameter from the ReadMe Dashboard and you'll be good to go!
 

diff --git a/documentation/rdme.md b/documentation/rdme.md
@@ -37,8 +37,8 @@ In order to sync a directory of Markdown files to your guides, you'll need to ad
 
 ```markdown
 ---
-title: CLI + GitHub Action Usage
-excerpt: Learn more about `rdme`, ReadMe's official CLI and GitHub Action!
+title: Syncing Docs via CLI / GitHub
+excerpt: Update your docs automatically with `rdme`, ReadMe's official CLI and GitHub Action!
 category: 5f7ce9e3a5504d0414d024c2
 ---
 
@@ -51,8 +51,8 @@ We automatically derive the page's slug via the file name (e.g. the file name `r
 
 ```markdown
 ---
-title: CLI + GitHub Action Usage
-excerpt: Learn more about `rdme`, ReadMe's official CLI and GitHub Action!
+title: Syncing Docs via CLI / GitHub
+excerpt: Update your docs automatically with `rdme`, ReadMe's official CLI and GitHub Action!
 category: 5f7ce9e3a5504d0414d024c2
 slug: an-alternative-page-slug-example
 ---
@@ -93,43 +93,6 @@ To execute this command via GitHub Actions, the step would look like this:
 
 We'll dive into several full GitHub Workflow file examples below!
 
-### Example: Syncing Markdown Docs
-
-Not to get too meta on you, but... the page that you're currently reading is actually being synced from the `rdme` GitHub repository via the `rdme` GitHub Action! Here are a few links to the relevant files:
-
-- [The Markdown source file for the page you're reading](https://github.com/readmeio/rdme/tree/main/documentation/rdme.md)
-- [The full GitHub Action workflow file that we use to sync the file to docs.readme.com](https://github.com/readmeio/rdme/blob/main/.github/workflows/docs.yml)
-- And finally... [the workflow run results](https://github.com/readmeio/rdme/actions/workflows/docs.yml)!
-
-To recreate this magic in your repository, your GitHub Workflow file will look something like this:
-
-```yml
-name: Sync `documentation` directory to ReadMe
-
-# Run workflow for every push to the `main` branch
-on:
-  push:
-    branches:
-      - main
-
-jobs:
-  sync:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout this repo
-        uses: actions/[email protected]
-
-      # Run GitHub Action to sync docs in `documentation` directory
-      - name: GitHub Action
-        # We recommend specifying a fixed version, i.e. @RDME_VERSION
-        # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions
-        uses: readmeio/rdme@RDME_VERSION
-        with:
-          rdme: docs ./documentation --key=API_KEY --version=2.0
-```
-
-In the example above, every push to the `main` branch will check out your repository's contents and sync the contents of the `documentation` directory with your ReadMe project.
-
 ### Example: Syncing an OpenAPI Definition
 
 To sync an OpenAPI or Swagger definition, you'll first want to obtain a unique API definition ID from ReadMe so we know which definition you want to update on subsequent re-syncs. You can obtain this API definition ID in one of several ways, but we'll dive into two below: uploading a file directly into the ReadMe dashboard and using the `rdme` CLI locally.
@@ -194,6 +157,43 @@ jobs:
 
 In the example above, every push to the `main` branch will check out your repository's contents and sync the OpenAPI file located at `./path-to-file.json` with your ReadMe project.
 
+### Example: Syncing Markdown Docs
+
+Not to get too meta on you, but... the page that you're currently reading is actually being synced from the `rdme` GitHub repository via the `rdme` GitHub Action! Here are the relevant files on GitHub:
+
+- [The Markdown source file for the page you're reading](https://github.com/readmeio/rdme/blob/main/documentation/rdme.md) 📜
+- [The GitHub Action workflow file that syncs the Markdown to docs.readme.com](https://github.com/readmeio/rdme/blob/main/.github/workflows/docs.yml) 🔄
+- And finally... [the workflow run results](https://github.com/readmeio/rdme/actions/workflows/docs.yml) ✅
+
+To recreate this magic in your repository, your GitHub Workflow file will look something like this:
+
+```yml
+name: Sync `documentation` directory to ReadMe
+
+# Run workflow for every push to the `main` branch
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout this repo
+        uses: actions/[email protected]
+
+      # Run GitHub Action to sync docs in `documentation` directory
+      - name: GitHub Action
+        # We recommend specifying a fixed version, i.e. @RDME_VERSION
+        # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions
+        uses: readmeio/rdme@RDME_VERSION
+        with:
+          rdme: docs ./documentation --key=API_KEY --version=2.0
+```
+
+In the example above, every push to the `main` branch will check out your repository's contents and sync the contents of the `documentation` directory with your ReadMe project.
+
 ### Example: Using GitHub Secrets
 
 > 🚧 Secretly store your ReadMe API Key!