docs: v8 docs

README.md

@@ -1,9 +1,6 @@
-> **Note**
-> These docs are for [the forthcoming `v8` release](https://github.com/readmeio/rdme/milestone/3). You can view the docs for the current release (`v7.5.0`) [here](https://github.com/readmeio/rdme/tree/7.5.0#readme).
-
 # 📖 rdme
 
-[![](https://d3vv6lp55qjaqc.cloudfront.net/items/1M3C3j0I0s0j3T362344/Untitled-2.png)](https://readme.com)
+[![](https://user-images.githubusercontent.com/8854718/195465739-0f0f83d5-2e18-4e6c-96ae-944e3bb6880a.png)](https://readme.com)
 
 [![npm](https://img.shields.io/npm/v/rdme)](https://npm.im/rdme) [![Build](https://github.com/readmeio/rdme/workflows/CI/badge.svg)](https://github.com/readmeio/rdme)
 
@@ -16,31 +13,39 @@
 > **Note**
 > These setup instructions are for CLI usage only. For usage in GitHub Actions, see [GitHub Actions](#github-actions) below.
 
-We recommend installing `rdme` in your project rather than doing a global installation so you don't run into unexpected behavior with mismatching versions. We also suggest using the `--save-dev` flag since `rdme` is typically used as part of a CI process and is unlikely to be running in your production application:
+#### Installing `rdme` to a Project
+
+The recommended approach for shared projects is to install `rdme` in your project's dependencies. That way you don't run into unexpected behavior with mismatching versions of `rdme`. We also suggest using the `--save-dev` flag since `rdme` is typically used as part of a CI process and is unlikely to be running in your production application:
 
 ```sh
 npm install rdme --save-dev
 ```
 
-Once installed in your project, we recommend using `npx` (which is included if you have `npm` installed) to prefix all of your CLI commands. For example:
+Once installed in your project, you can use the `npx` prefix (which is included if you have `npm` installed) to run your CLI commands locally. For example:
 
 ```sh
 npx rdme openapi:validate [file]
 ```
 
 To ensure you're getting the latest features and security updates, we recommend using a tool like [Dependabot](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates) to keep `rdme` (and your other dependencies) up-to-date.
 
-### Authentication
-
-For usage in CI environments (GitHub Actions, CircleCI, Travis CI, etc.) or if you're working with multiple ReadMe projects, we recommend providing your project API key via the `--key` option (instead of the configuration file authentication described below).
+#### Installing `rdme` to Your Local Machine
 
-For local CLI usage with a single project, you can authenticate `rdme` to your ReadMe project. This will save your API key to a local configuration file (`~/.config/configstore/rdme-production.json`) so you will not have to provide the `--key` option to commands that require it.
+The simplest way to use `rdme` is to install it globally:
 
 ```sh
-rdme login
+npm install -g rdme
 ```
 
-`rdme whoami` is also available to you to determine who you are logged in as, and to what project, as well as `rdme logout` for logging out of that account.
+With a global installation, you'll be able to run `rdme` within any directory on your local machine. If you log in once, you can quickly access your project without having to remember your API key (see the [Authentication](#authentication) section below).
+
+### Authentication
+
+For usage in CI environments (GitHub Actions, CircleCI, Travis CI, etc.) or if you're working with multiple ReadMe projects, we recommend providing a project API key via the `--key` option (instead of the configuration file authentication described below).
+
+For local CLI usage with a single project, you can authenticate `rdme` to your ReadMe project using `rdme login`. Once you follow the prompts and are successfully authenticated, your API key will be saved to a local configuration file (`~/.config/configstore/rdme-production.json`) and you won't have to provide the `--key` option to commands that require it.
+
+`rdme whoami` is also available to you to determine who is logged in, and to what project. You can clear your stored credentials with `rdme logout`.
 
 ## Usage
 
@@ -56,30 +61,15 @@ If you wish to get more information about any command within `rdme`, you can exe
 > **Note**
 > 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:
-
-```yml
-- uses: actions/checkout@v3
-- uses: readmeio/rdme@XX
-  with:
-    rdme: [your command here]
-```
-
-The command syntax in GitHub Actions is functionally equivalent to the CLI. For example, take the following CLI command:
+For usage in [GitHub Actions](https://docs.github.com/actions), you can create a new GitHub Actions workflow file by including the `--github` flag with the command you wish to run in GitHub Actions. For example:
 
 ```sh
-rdme openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID
+rdme openapi --github
 ```
 
-To execute this command via GitHub Actions, the step would look like this:
-
-```yml
-- uses: readmeio/rdme@XX
-  with:
-    rdme: openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID
-```
+This will run through the `openapi` command, ask you a few quick questions, and then automatically create a fully functional GitHub Actions workflow file for you 🪄
 
-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).
+You can see examples featuring the latest version in [our docs](https://docs.readme.com/docs/rdme#github-actions-examples). 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).
 
 ### OpenAPI / Swagger
 
@@ -202,7 +192,7 @@ The Markdown files will require YAML front matter with certain ReadMe documentat
 Passing in a path to a directory will also sync any Markdown files that are located in subdirectories.
 
 ```sh
-rdme docs path-to-markdown-files --version={project-version}
+rdme docs [path-to-directory-of-markdown] --version={project-version}
 ```
 
 This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode [in our docs](https://docs.readme.com/docs/rdme#dry-run-mode).
@@ -220,7 +210,7 @@ rdme docs:edit <slug> --version={project-version}
 #### Syncing a Single Markdown File to ReadMe
 
 ```sh
-rdme docs:single path-to-markdown-file --version={project-version}
+rdme docs:single [path-to-file.md] --version={project-version}
 ```
 
 ### Changelogs
@@ -232,15 +222,15 @@ The Markdown files will require YAML front matter with certain ReadMe documentat
 Passing in a path to a directory will also sync any Markdown files that are located in subdirectories.
 
 ```sh
-rdme changelogs path-to-markdown-files
+rdme changelogs [path-to-directory-of-markdown]
 ```
 
 This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode [in our docs](https://docs.readme.com/docs/rdme#dry-run-mode).
 
 #### Syncing a Single Markdown File to ReadMe
 
 ```sh
-rdme changelogs:single path-to-markdown-file
+rdme changelogs:single [path-to-file.md]
 ```
 
 ### Custom Pages
@@ -252,15 +242,15 @@ Custom Pages has support for both Markdown and HTML files. These files will requ
 Passing in a path to a directory will also sync any HTML/Markdown files that are located in subdirectories.
 
 ```sh
-rdme custompages path-to-markdown-files
+rdme custompages [path-to-directory-of-markdown]
 ```
 
 This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode [in our docs](https://docs.readme.com/docs/rdme#dry-run-mode).
 
 #### Syncing a Single Custom Page to ReadMe
 
 ```sh
-rdme custompages:single path-to-markdown-file
+rdme custompages:single [path-to-file.md]
 ```
 
 ### Versions

documentation/github-actions-docs-example.md

@@ -0,0 +1,51 @@
+---
+title: 'GitHub Action Example: Syncing Markdown'
+category: 5f7ce9e3a5504d0414d024c2
+---
+
+Do you have Markdown files stored on GitHub? With [the `rdme` GitHub Action](https://docs.readme.com/docs/rdme), you can sync them to ReadMe every time they're updated in GitHub. Let's go over how to set this up!
+
+## "Automagical" Workflow File Generation 🪄
+
+To set up a GitHub Actions workflow for syncing a directory of Markdown docs, the fastest and easiest way to do so is by running the following command on your local machine:
+
+```sh
+rdme docs [path-to-directory-of-markdown] --github
+```
+
+This will scan the directory for Markdown files, sync them to ReadMe, and then create your GitHub Actions workflow file. Once that's done, create your [repository secret](url), push your workflow file to GitHub, and get syncing! 🎊
+
+## Constructing a GitHub Actions Workflow File By Hand 🔨
+
+> 🚧 Wait — there’s an easier way to do this!
+>
+> The information below is useful if you have experience using GitHub Actions, but for most folks, we recommend using the steps [detailed above](#automagical-workflow-file-generation-🪄). The `rdme` CLI will ask you a few questions before automatically creating the GitHub Actions workflow file for you, complete with every parameter you need to get syncing.
+
+In order to construct the file by hand, you'll first want to grab a project version to ensure that your docs sync to the right place in your developer hub. That version will be passed via the `--version` flag. See below for a full example:
+
+```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/checkout@v3
+
+      # 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=${{ secrets.README_API_KEY }} --version=2.0
+```
+
+In the example above, every push to the `main` branch will sync the Markdown contents of the `documentation` directory to version 2.0 of your ReadMe project.

documentation/github-actions-openapi-example.md

@@ -0,0 +1,99 @@
+---
+title: 'GitHub Action Example: Syncing OpenAPI'
+category: 5f7ce9e3a5504d0414d024c2
+---
+
+Is your OpenAPI definition stored on GitHub? With [the `rdme` GitHub Action](https://docs.readme.com/docs/rdme), you can sync it to ReadMe every time it's updated in GitHub. Let's go over how to set this up!
+
+## "Automagical" Workflow File Generation 🪄
+
+To set up a GitHub Actions workflow for syncing an OpenAPI or Swagger definition, the fastest and easiest way to do so is by running the following command on your local machine:
+
+```sh
+rdme openapi --github
+```
+
+This will locate your OpenAPI definition, sync it to ReadMe, and then create your GitHub Actions workflow file. Once that's done, create your [repository secret](url), push your workflow file to GitHub, and get syncing! 🎊
+
+## Constructing a GitHub Actions Workflow File By Hand 🔨
+
+> 🚧 Wait — there’s an easier way to do this!
+>
+> The information below is useful if you have experience using GitHub Actions, but for most folks, we recommend using the steps [detailed above](#automagical-workflow-file-generation-🪄). The `rdme` CLI will ask you a few questions before automatically creating the GitHub Actions workflow file for you, complete with every parameter you need to get syncing.
+
+In order to construct the file by hand, 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.
+
+<details>
+<summary>Uploading a file</summary>
+
+Follow [these instructions](https://docs.readme.com/docs/openapi#file-upload) on uploading a new OpenAPI file in the dashboard. Once the file is uploaded, you'll see the following in the API Reference settings of your dashboard (the red outline is where you'll find your API definition ID):
+
+![](https://files.readme.io/d57b7c8-Screen_Shot_2022-02-23_at_11.54.21_AM.png)
+
+</details>
+<details>
+<summary>Using the <code>rdme</code> CLI</summary>
+
+Alternatively, you can obtain the API definition ID by running the following `rdme` CLI command on your local machine:
+
+```sh
+rdme openapi [path-to-file.json]
+```
+
+Once you follow the prompts and upload your OpenAPI definition, you'll receive a confirmation message that looks something like this:
+
+```
+You've successfully updated an OpenAPI file on your ReadMe project!
+
+        http://dash.readme.com/project/{your_project}/v1.0/refs/pet
+
+To update your OpenAPI definition, run the following:
+
+        rdme openapi [path-to-file.json] --key=<key> --id=API_DEFINITION_ID
+```
+
+</details>
+
+We have a walkthrough video available which goes over the whole end-to-end process of obtaining the API definition ID and constructing the GitHub Actions workflow file:
+
+<!--
+This is a custom HTML block that we use in ReadMe.
+We'll need this to render an iframe of the Loom video demo.
+Using our embedly-powered embed block renders an iframe that's way too tall, hence we're using HTML.
+You can see the video here: https://www.loom.com/share/e32c20a9dc2f4eeeab42d0c18ba24478
+-->
+
+[block:html]
+{
+"html": "<div style=\"position: relative; padding-bottom: 62.5%; height: 0;\"><iframe src=\"https://www.loom.com/embed/e32c20a9dc2f4eeeab42d0c18ba24478\" frameborder=\"0\" webkitallowfullscreen mozallowfullscreen allowfullscreen style=\"position: absolute; top: 0; left: 0; width: 100%; height: 100%;\"></iframe></div>"
+}
+[/block]
+
+Once you've obtained your API definition ID (let's call it `API_DEFINITION_ID`), your full GitHub Workflow file will look something like this:
+
+```yml
+name: Sync OpenAPI definition 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/checkout@v3
+
+      # Run GitHub Action to sync OpenAPI file at [path-to-file.json]
+      - 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: openapi [path-to-file.json] --key=${{ secrets.README_API_KEY }} --id=API_DEFINITION_ID
+```
+
+In the example above, every push to the `main` branch will sync the OpenAPI file located at `./path-to-file.json` to the API specification `API_DEFINITION_ID` in your ReadMe project.

documentation/legacy-github-action.md

@@ -45,7 +45,7 @@ There are a few things to note:
 
 1. This workflow will infer the `api-version` based on the `API_DEFINITION_ID` parameter that you pass in, so the API version parameter is no longer needed here.
 2. `@RDME_VERSION` is the latest version of `rdme`. To ensure you're getting the latest features and security updates, we strongly recommend setting up [Dependabot](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot) to keep this package up-to-date.
-3. If you used secrets to encrypt the `readme-oas-key` value, you'll have to split this value out into two separate secrets—one for the API key and one for the API definition ID. You can see an example of this [here](https://docs.readme.com/docs/rdme#example-using-github-secrets).
+3. If you used secrets to encrypt the `readme-oas-key` value, you'll have to split this value out into two separate secrets—one for the API key and one for the API definition ID. You can see an example of this [here](https://docs.readme.com/docs/github-actions-openapi-example).
 
 <details>