diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index a8de1f700..52037bece 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -57,7 +57,7 @@ jobs:
if: github.event_name == 'push' && github.event.ref == 'refs/heads/main'
# We use the `main` branch as ref for GitHub Action
# This is NOT recommended, as it can break your workflows without notice!
- # We recommend specifying a fixed version, i.e. @7.0
+ # We recommend specifying a fixed version, i.e. @8.0.0
# Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions
uses: readmeio/rdme@main
with:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c7f76a345..2f6aa1125 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -40,7 +40,7 @@ Once you've installed `act`, it'll ask you what Docker image size you'd like. Th
-P ubuntu-18.04=ghcr.io/catthehacker/ubuntu:act-18.04
```
-Our GitHub Actions guidance states that Action workflows should have a [`runs-on` value](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) of `ubuntu-latest`. These runners are updated frequently β you can find links to the the latest versions by navigating [here](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#preinstalled-software) and selecting the latest Ubuntu link. Because of this, you'll want to make sure your `ghcr.io/catthehacker/ubuntu` image stays up-to-date by doing a periodic pull:
+Our GitHub Actions guidance states that Action workflows should have a [`runs-on` value](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) of `ubuntu-latest`. These runners are updated frequently β you can find links to the latest versions by navigating [here](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#preinstalled-software) and selecting the latest Ubuntu link. Because of this, you'll want to make sure your `ghcr.io/catthehacker/ubuntu` image stays up-to-date by doing a periodic pull:
```sh
docker pull ghcr.io/catthehacker/ubuntu:act-latest
diff --git a/README.md b/README.md
index 42eac6e07..86759f309 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,82 @@
-> **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).
+[](https://readme.com)
+
+
+ ReadMe's official command-line interface (CLI) and GitHub Action π
+
+
+
+ 
+ 
+ 
+ 
+
+
+With `rdme`, you can manage your API definition (we support [OpenAPI](https://spec.openapis.org/oas/v3.1.0.html) or [Swagger](https://swagger.io/specification/v2/)) and sync it to your API reference docs on ReadMe. You can also access other parts of [ReadMe's RESTful API](https://docs.readme.com/reference), including syncing Markdown documentation with your ReadMe project and managing project versions.
+
+Not using ReadMe for your docs? No worries. `rdme` has a variety of tools to help you identify issues with your API definition β no ReadMe account required.
+
+## Table of Contents
+
+
-[](https://readme.com)
+
-[](https://npm.im/rdme) [](https://github.com/readmeio/rdme)
+- [CLI Configuration](#cli-configuration)
+ - [Setup](#setup)
+ - [Authentication](#authentication)
+- [GitHub Actions Configuration](#github-actions-configuration)
+- [Usage](#usage)
+ - [Common `rdme` Options](#common-rdme-options)
+ - [OpenAPI / Swagger π](#openapi--swagger-)
+ - [Docs (a.k.a. Guides) π](#docs-aka-guides-)
+ - [Changelog π£](#changelog-)
+ - [Custom Pages π](#custom-pages-)
+ - [Versions β³](#versions-)
+ - [Categories πͺ£](#categories-)
+ - [Open Your ReadMe Project in Your Browser](#open-your-readme-project-in-your-browser)
+- [Future](#future)
-`rdme` is [ReadMe](https://readme.com)'s official command-line interface (CLI) and [GitHub Action](#github-actions) wrapper. It allows you to sync [OpenAPI](https://spec.openapis.org/oas/v3.1.0.html) and [Swagger](https://swagger.io/specification/v2/) definitions with projects you create on [ReadMe](https://readme.com/). You can also access other parts of [ReadMe's RESTful API](https://docs.readme.com/reference/intro-to-the-readme-api), including syncing Markdown documentation with your project and managing project versions.
+
-## Configuration
+## CLI Configuration
### Setup
> **Note**
-> These setup instructions are for CLI usage only. For usage in GitHub Actions, see [GitHub Actions](#github-actions) below.
+> These setup instructions are for CLI usage only. For usage in GitHub Actions, see [GitHub Actions Configuration](#github-actions-configuration) below.
+
+
+
+To install the `rdme` CLI, you'll need to have [Node.js](https://nodejs.org) installed. Node.js comes bundled with [the `npm` CLI](https://github.com/npm/cli), which you'll need to install `rdme`. You can see our current Node.js version requirements in the green badge on the right.
+
+#### Installing `rdme` to Your Local Machine
+
+The simplest way to use `rdme` is to install it globally:
+
+```sh
+npm install -g rdme
+```
+
+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).
-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]
@@ -32,15 +86,26 @@ To ensure you're getting the latest features and security updates, we recommend
### 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).
+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.
+
+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 above).
+
+`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`.
+
+## GitHub Actions Configuration
+
+> **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 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.
+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 login
+rdme openapi --github
```
-`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.
+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. πͺ
+
+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).
## Usage
@@ -51,48 +116,43 @@ If you wish to get more information about any command within `rdme`, you can exe
- `--key `: The API key associated with your ReadMe project. Note that most of the commands below require API key authentication, even though the `--key` flag is omitted from the examples. See the [Authentication](#authentication) section above for more information.
- `--version `: Your project version. See [our docs](https://docs.readme.com/docs/versions) for more information.
-### GitHub Actions
+### OpenAPI / Swagger π
-> **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).
+With `rdme`, you have access to a variety of tools to manage your OpenAPI or Swagger definition, most of which don't require an account on ReadMe. These tools include:
-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:
+- [Reduction](#reducing-an-api-definition) π
+- [Syncing](#syncing-an-api-definition-to-readme) π¦
+- [Validation](#validating-an-api-definition) β
-```yml
-- uses: actions/checkout@v3
-- uses: readmeio/rdme@XX
- with:
- rdme: [your command here]
-```
+`rdme` supports [OpenAPI 3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md), [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md), and [Swagger 2.x](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md).
-The command syntax in GitHub Actions is functionally equivalent to the CLI. For example, take the following CLI command:
+The following examples use JSON files, but `rdme` supports API Definitions that are written in either JSON or YAML.
-```sh
-rdme openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID
-```
+#### Syncing an API Definition to ReadMe
-To execute this command via GitHub Actions, the step would look like this:
+`rdme openapi` locates your API definition (if [you don't supply one](#omitting-the-file-path)), validates it, and then syncs it to your API reference on ReadMe.
-```yml
-- uses: readmeio/rdme@XX
- with:
- rdme: openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID
-```
+> **Note**
+> The `rdme openapi` command supports both OpenAPI and Swagger API definitions. The `rdme swagger` command is an alias for `rdme openapi` and is deprecated.
-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).
+If you wish to programmatically access any of this script's results (such as the API defintion ID or the link to the corresponding docs in your dashboard), supply the `--raw` flag and the command will return a JSON output.
-### OpenAPI / Swagger
+This command also has a dry run mode, which can be useful for initial setup and debugging. You can perform a dry run by supplying the `--dryRun` flag.
-ReadMe supports [OpenAPI 3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md), [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md), and [Swagger 2.x](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md).
+##### Omitting the File Path
-The following examples use JSON files, but `rdme` supports API Definitions that are written in either JSON or YAML.
+If you run `rdme` within a directory that contains your OpenAPI or Swagger definition, you can omit the file path. `rdme` will then look for JSON or YAML files (including in sub-directories) that contain a top-level [`openapi`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields) or [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#fixed-fields) property.
-> **Note**
-> The `rdme openapi` command supports both OpenAPI and Swagger API definitions. The `rdme swagger` command is an alias for `rdme openapi` and is deprecated.
+> **Note** `rdme` will not scan anything in the following:
+>
+> - Any `.git/` directories (if they exist)
+> - Any files/directories specified in `.gitignore` files (including any `.gitignore` files in subdirectories, if they exist)
-If you wish to see the raw JSON output of any of the `openapi` command examples below, supply the `--raw` flag.
+```sh
+rdme openapi
+```
-#### Uploading a New API Definition to ReadMe
+##### Uploading a New API Definition to ReadMe
This will upload `path-to-openapi.json` to your project and return an ID and URL for you to later update your file, and view it in the client.
@@ -106,9 +166,7 @@ If you want to bypass the prompt to create or update an API definition, you can
rdme openapi [path-to-file.json] --version={project-version} --create
```
-This command also has a dry run mode, which can be useful for initial setup and debugging. You can perform a dry run by supplying the `--dryRun` flag.
-
-#### Editing (Re-Syncing) an Existing API Definition
+##### Editing (Re-Syncing) an Existing API Definition
This will edit (re-sync) an existing API definition (identified by `--id`) within your ReadMe project. **This is the recommended approach for usage in CI environments.**
@@ -116,7 +174,7 @@ This will edit (re-sync) an existing API definition (identified by `--id`) withi
rdme openapi [path-to-file.json] --id={existing-id}
```
-#### Uploading or Editing an API Definition in a Project Version
+##### Uploading or Editing an API Definition in a Project Version
You can additionally include a version flag, specifying the target version for your file's destination. This approach will provide you with CLI prompts, so we do not recommend this technique in CI environments.
@@ -146,26 +204,7 @@ You can add `--update` to the command so if there's only one API definition for
rdme openapi [path-to-file.json] --version={project-version} --update
```
-This command also has a dry run mode, which can be useful for initial setup and debugging. You can perform a dry run by supplying the `--dryRun` flag.
-
-#### Omitting the File Path
-
-If you run `rdme` within a directory that contains your OpenAPI or Swagger definition, you can omit the file path. `rdme` will then look for JSON or YAML files (including in sub-directories) that contain a top-level [`openapi`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields) or [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#fixed-fields) property.
-
-
-
-> **Note**
-> `rdme` will not scan anything in the following:
->
-> - Any `.git/` directories (if they exist)
-> - Any files/directories specified in `.gitignore` files (including any `.gitignore` files in subdirectories, if they exist)
-
-
-```sh
-rdme openapi
-```
-
-#### Override the Working Directory
+##### Override the Working Directory
By default, `rdme` bundles all [references](https://swagger.io/docs/specification/using-ref/) with paths based on the directory that `rdme` is being run in. You can override the working directory using the `--workingDirectory` option, which can be helpful for bundling certain external references (see [here](__tests__/__fixtures__/relative-ref-oas/petstore.json) for an example file).
@@ -175,7 +214,7 @@ rdme openapi petstore.json --workingDirectory=[path to directory]
#### Validating an API Definition
-You can also perform a local validation of your API definition without uploading it to ReadMe, which can be useful when constructing or editing your API definition.
+You can also perform a local validation of your API definition (no ReadMe account required!), which can be useful when constructing or editing your API definition.
```sh
rdme openapi:validate [path-to-file.json]
@@ -185,7 +224,7 @@ Similar to the `openapi` command, you can also [omit the file path](#omitting-th
#### Reducing an API Definition
-We also offer a tool that allows you to reduce a large API definition down to a specific set of tags or paths. This can be useful if you're debugging a problematic schema somewhere, or if you have a file that is too big to maintain.
+We also offer a tool that allows you to reduce a large API definition down to a specific set of tags or paths (again, no ReadMe account required!). This can be useful if you're debugging a problematic schema somewhere, or if you have a file that is too big to maintain.
```sh
rdme openapi:reduce [path-to-file.json]
@@ -193,7 +232,7 @@ rdme openapi:reduce [path-to-file.json]
The command will ask you a couple questions about how you wish to reduce the file and then do so. And as with the `openapi` command, you can also [omit the file path](#omitting-the-file-path).
-### Docs (a.k.a. Guides)
+### Docs (a.k.a. Guides) π
The Markdown files will require YAML front matter with certain ReadMe documentation attributes. Check out [our docs](https://docs.readme.com/docs/rdme#markdown-file-setup) for more info on setting up your front matter.
@@ -216,7 +255,7 @@ This command also has a dry run mode, which can be useful for initial setup and
If you wish to delete documents from ReadMe that are no longer present in your local directory:
```sh
-rdme docs:prune path-to-directory-of-markdown
+rdme docs:prune [path-to-directory-of-markdown]
```
Run with `--confirm` to bypass the confirmation prompt (useful for CI environments).
@@ -227,7 +266,7 @@ This command also has an alias called `guides:prune`:
rdme guides:prune path-to-directory-of-markdown
```
-### Changelog
+### Changelog π£
The Markdown files will require YAML front matter with certain ReadMe documentation attributes. Check out [our docs](https://docs.readme.com/docs/rdme#markdown-file-setup) for more info on setting up your front matter.
@@ -239,7 +278,7 @@ rdme changelogs [path]
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).
-### Custom Pages
+### Custom Pages π
Custom Pages has support for both Markdown and HTML files. These files will require YAML front matter with certain ReadMe documentation attributes. Check out [our docs](https://docs.readme.com/docs/rdme#markdown-file-setup) for more info on setting up your front matter.
@@ -251,7 +290,7 @@ rdme custompages [path]
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).
-### Versions
+### Versions β³
#### Get All Versions Associated With Your Project
@@ -273,8 +312,6 @@ If you wish to see the raw JSON output from our API in this response, supply the
rdme versions:create
```
-##### Create a New Version
-
If you wish to automate the process of creating a new project version, and not have the CLI prompt you for input, you can do so by supplying the necessary flags to `versions:create`.
For example:
@@ -301,7 +338,7 @@ You can remove a specific version from your project, as well as all of the attac
rdme versions:delete
```
-### Categories
+### Categories πͺ£
#### Get All Categories Associated to Your Project Version
diff --git a/documentation/github-actions-docs-example.md b/documentation/github-actions-docs-example.md
new file mode 100644
index 000000000..5fc5b4fc4
--- /dev/null
+++ b/documentation/github-actions-docs-example.md
@@ -0,0 +1,68 @@
+---
+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.
+
+> π Keeping `rdme` up-to-date
+>
+> Note that `@RDME_VERSION` (used in the above example) is the latest version of `rdme`. 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).
diff --git a/documentation/github-actions-openapi-example.md b/documentation/github-actions-openapi-example.md
new file mode 100644
index 000000000..e0268c2cc
--- /dev/null
+++ b/documentation/github-actions-openapi-example.md
@@ -0,0 +1,115 @@
+---
+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.
+
+
+Uploading a file
+
+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):
+
+
+
+
+
+Using the rdme CLI
+
+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= --id=API_DEFINITION_ID
+```
+
+
+
+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:
+
+
+
+[block:html]
+{
+"html": ""
+}
+[/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.
+
+> π Keeping `rdme` up-to-date
+>
+> Note that `@RDME_VERSION` (used in the above example) is the latest version of `rdme`. 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).
diff --git a/documentation/legacy-github-action.md b/documentation/legacy-github-action.md
index 568103020..47888a9ff 100644
--- a/documentation/legacy-github-action.md
+++ b/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).
diff --git a/documentation/rdme.md b/documentation/rdme.md
index a9f011c41..16d8e4d49 100644
--- a/documentation/rdme.md
+++ b/documentation/rdme.md
@@ -8,8 +8,7 @@ category: 5f7ce9e3a5504d0414d024c2
Hello curious raw Markdown reader! π
This Markdown page is syncing to ReadMe via the `rdme` GitHub Action π¦
-Check out the "Syncing Markdown Docs" example below,
-and peep the resulting page in our docs: https://docs.readme.com/docs/rdme
+Peep the resulting page in our docs: https://docs.readme.com/docs/rdme
We also do some fancy little find-and-replace action to swap out every instance
of `RDME_VERSION` below with the latest version of rdme.
@@ -17,9 +16,20 @@ Check out `.github/workflows/docs.yml` for more info on this!
-->
-If you're anything like us, your documentation process may be a part of a broader CI/CD process. For example, you may want to automatically update your ReadMe guides or API reference every time you've ship new code. Enter `rdme`: ReadMe's official command-line interface (CLI) and GitHub Action!
+[](https://readme.com)
-[](https://npm.im/rdme) [](https://github.com/readmeio/rdme)
+
+ ReadMe's official command-line interface (CLI) and GitHub Action π
+
+
+
+
+
+
+
+
+
+If you're anything like us, your documentation process may be a part of a broader CI/CD process. For example, you may want to automatically update your Guides or API reference on ReadMe every time you've ship new code. Enter `rdme`: ReadMe's official command-line interface (CLI) and GitHub Action!
With `rdme`, you can create workflows for a variety of use cases, including:
@@ -41,7 +51,7 @@ To see detailed CLI setup instructions and all available commands, check out [th
> - There are slight variations in the YAML front matter attributes for each respective section of your documentation. For example, Changelog has a `type` attribute which you can set to `added`. See [Specifying Other Attributes](#specifying-other-attributes) for more information.
> - In addition to Markdown, Custom Pages also supports HTML files. If you pass an HTML file into the `custompages` commands, the page will have the `htmlmode` flag set to `true` and it will conversely be set to `false` for Markdown files. You can override this in the YAML front matter.
-In order to sync a directory of Markdown files to your guides, your Changelog, or your Custom Pages, you'll need to add certain attributes to the top of each page via a [YAML front matter block](https://jekyllrb.com/docs/front-matter/). See below for an example (using the page you're currently reading!):
+In order to sync Markdown files to your Guides, your Changelog, or your Custom Pages, you'll need to add certain attributes to the top of each page via a [YAML front matter block](https://jekyllrb.com/docs/front-matter/). See below for an example (using the page you're currently reading!):
```markdown
---
@@ -81,9 +91,9 @@ You can also specify several other page attributes in your YAML front matter, su
If you're setting up new pages or if you're generally unsure if you've set up your page attributes correctly, each command has a dry run mode. This will allow you preview the changes without actually creating/updating any docs in ReadMe, which can be extremely useful for initial setup (oh, and we have [comprehensive debugging options](#troubleshooting) available as well!). To enable dry run mode, use the `--dryRun` flag:
```sh
-rdme docs path-to-markdown-files --version={project-version} --dryRun
-rdme changelogs path-to-markdown-files --dryRun
-rdme custompages path-to-markdown-files --dryRun
+rdme docs [path] --version={project-version} --dryRun
+rdme changelogs [path] --dryRun
+rdme custompages [path] --dryRun
```
The command output will indicate whether each page is being created or updated alongside all processed page attributes.
@@ -92,164 +102,96 @@ The command output will indicate whether each page is being created or updated a
With [GitHub Actions](https://docs.github.com/actions), you can automatically execute workflows when certain events take place in your GitHub repository (e.g. code is pushed to the default branch, a new pull request is opened, etc.).
-While there are [dozens of event options available](https://docs.github.com/actions/using-workflows/events-that-trigger-workflows), you'll typically want to sync your OpenAPI definition and Markdown docs to ReadMe [when a new build is deployed](https://docs.github.com/actions/using-workflows/events-that-trigger-workflows#deployment) or [when a new release is created](https://docs.github.com/actions/using-workflows/events-that-trigger-workflows#release). If you're not using either of those features then you can sync to ReadMe [when code is pushed to the default branch](https://docs.github.com/actions/using-workflows/events-that-trigger-workflows#push).
+While there are [dozens of event options available](https://docs.github.com/actions/using-workflows/events-that-trigger-workflows), you'll typically want to sync your OpenAPI definition and Markdown docs to ReadMe when one of the following events takes place:
+
+- [Code is pushed to the default branch](https://docs.github.com/actions/using-workflows/events-that-trigger-workflows#push) π΄
+- [A build is deployed](https://docs.github.com/actions/using-workflows/events-that-trigger-workflows#deployment) π
+- [A release is created](https://docs.github.com/actions/using-workflows/events-that-trigger-workflows#release) π
> π Keeping `rdme` up-to-date
>
-> Note that the `@RDME_VERSION` in the below examples is the latest version of `rdme`. 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 `@RDME_VERSION` (used in the examples on this page) is the latest version of `rdme`. 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).
-For usage in GitHub 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:
+### Quick Start
-```yml
-- uses: actions/checkout@v3
-- uses: readmeio/rdme@RDME_VERSION
- with:
- rdme: [your command here]
-```
+The fastest way to create a GitHub Actions workflow file is by doing the following:
-The command syntax in GitHub Actions is functionally equivalent to the CLI. For example, take the following CLI command:
+1. Download `rdme` to your local machine (see [our setup instructions](https://github.com/readmeio/rdme#setup))
+2. Open your command line at the root of your GitHub repository
+3. Run the command you wish to automate on your local machine with the `--github` flag tacked on at the end. For example:
```sh
-rdme openapi [path-to-file.json] --key=<> --id=API_DEFINITION_ID
+rdme openapi --github
```
-To execute this command via GitHub Actions, the step would look like this:
+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. πͺ
-```yml
-- uses: readmeio/rdme@RDME_VERSION
- with:
- rdme: openapi [path-to-file.json] --key=<> --id=API_DEFINITION_ID
-```
-
-We'll dive into several full GitHub Workflow file examples (including a video demo) below!
-
-### Example: Syncing an OpenAPI Definition
-
-
-
-[block:html]
-{
-"html": ""
-}
-[/block]
-
-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.
-
-
-Uploading a file
-
-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):
-
-
-
-
-
-Using the rdme CLI
+> π Did you know?
+>
+> 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 Actions 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) β
-Alternatively, you can obtain the API definition ID by running the following `rdme` CLI command on your local machine:
+### Securely Using Your API Key
-```sh
-rdme openapi [path-to-file.json]
-```
+> π§ Secretly store your ReadMe API Key!
+>
+> GitHub Actions has [secrets](https://docs.github.com/actions/security-guides/encrypted-secrets) to securely store sensitive information so it isn't publicly visible. We **strongly** recommend using these for storing your ReadMe API Key and any other secret keysβwhether your repository is public or private. You can read more about setting these up [in their documentation](https://docs.github.com/actions/security-guides/encrypted-secrets).
-Once you follow the prompts and upload your OpenAPI definition, you'll receive a confirmation message that looks something like this:
+To use sensitive information (like your ReadMe API key) in your `rdme` GitHub Action, first [create a new repository secret](https://docs.github.com/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository). Let's say you create a new secret key called `README_API_KEY`. The usage in the `rdme` step will look something like this:
+```yml
+- uses: readmeio/rdme@RDME_VERSION
+ with:
+ rdme: openapi [path-to-file.json] --key=${{ secrets.README_API_KEY }} --id=API_DEFINITION_ID
```
-You've successfully updated an OpenAPI file on your ReadMe project!
- http://dash.readme.com/project/{your_project}/v1.0/refs/pet
+### Manually Configuring a GitHub Actions Workflow
-To update your OpenAPI definition, run the following:
+We recommend using the [quick start](#quick-start) to get started with GitHub Actions. But if you are familiar with the [workflow syntax](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) and wish to manually configure a workflow, follow these steps:
- rdme openapi [path-to-file.json] --key=<> --id=API_DEFINITION_ID
-```
+1. Create a new [GitHub Actions workflow file](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) in the `.github/workflows` directory of your repository (or use an existing workflow file)
-
+1. Configure the [`on`](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#on) property, which determines what triggers the execution of the workflow.
-Once you've obtained your API definition ID, your full GitHub Workflow file will look something like this:
+1. Add the following two [steps](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) to your workflow:
```yml
-name: Sync OpenAPI definition to ReadMe
-
-# Run workflow for every push to the `main` branch
-on:
- push:
- branches:
- - main
+# Required in order for the GitHub Action to access your repo's contents
+- uses: actions/checkout@v3
-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=<> --id=API_DEFINITION_ID
+# Runs the `rdme` command on your repo's contents
+- uses: readmeio/rdme@RDME_VERSION
+ with:
+ rdme: [your command here]
```
-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 command syntax in GitHub Actions is functionally equivalent to the CLI. For example, take the following CLI command:
-- [The Markdown source file for the page you're reading](https://github.com/readmeio/rdme/blob/main/documentation/rdme.md) π
-- [The GitHub Actions 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) β
+```sh
+rdme validate [path-to-file.json]
+```
-To recreate this magic in your repository, your GitHub Workflow file will look something like this:
+To execute this command via GitHub Actions, the step would look 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/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=<> --version=2.0
+- uses: readmeio/rdme@RDME_VERSION
+ with:
+ rdme: validate [path-to-file.json]
```
-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.
+The following section has links to full GitHub Actions workflow file examples.
-### Example: Using GitHub Secrets
+### GitHub Actions Examples
-> π§ Secretly store your ReadMe API Key!
->
-> GitHub Actions has [secrets](https://docs.github.com/actions/security-guides/encrypted-secrets) to securely store sensitive information so it isn't publicly visible. We **strongly** recommend using these for storing your ReadMe API Key, your API definition ID, and any other secret keysβwhether your repository is public or private. You can read more about setting these up [in their documentation](https://docs.github.com/actions/security-guides/encrypted-secrets).
+Want to start syncing? We have several example workflow files available:
-To use a GitHub secret in your `rdme` GitHub Action, first [create a new repository secret](https://docs.github.com/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository). Let's say you create a new secret key called `README_API_KEY`. The usage in the `rdme` step will look something like this:
-
-```yml
-- uses: readmeio/rdme@RDME_VERSION
- with:
- rdme: openapi [path-to-file.json] --key=${{ secrets.README_API_KEY }} --id=${{ secrets.README_API_DEFINITION_ID }}
-```
+- [Syncing an OpenAPI definition](https://docs.readme.com/docs/github-actions-openapi-example)
+- [Syncing a directory of Markdown files](https://docs.readme.com/docs/github-actions-docs-example)
## Usage in Other CI Environments
@@ -270,7 +212,19 @@ pipelines:
default:
- step:
script:
- - npx rdme@RDME_VERSION openapi [path-to-file.json] --key=<> --id=API_DEFINITION_ID
+ - npx rdme@RDME_VERSION openapi [path-to-file.json] --key=$README_API_KEY --id=API_DEFINITION_ID
+```
+```yml CircleCI (.circleci/config.yml)
+version: 2.1
+jobs:
+ sync-via-rdme:
+ docker:
+ # Official framework image. Look for the different tagged releases at:
+ # https://hub.docker.com/r/library/node/tags/
+ - image: node:NODE_VERSION
+ steps:
+ - run:
+ command: npx rdme@RDME_VERSION openapi [path-to-file.json] --key=$README_API_KEY --id=API_DEFINITION_ID
```
```yml GitLab CI (rdme-sync.gitlab-ci.yml)
# Official framework image. Look for the different tagged releases at:
@@ -279,10 +233,29 @@ image: node:NODE_VERSION
sync-via-rdme:
script:
- - npx rdme@RDME_VERSION openapi [path-to-file.json] --key=<> --id=API_DEFINITION_ID
+ - npx rdme@RDME_VERSION openapi [path-to-file.json] --key=$README_API_KEY --id=API_DEFINITION_ID
+```
+```yml Travis CI (.travis.yml)
+# https://docs.travis-ci.com/user/languages/javascript-with-nodejs/#specifying-nodejs-versions
+language: node_js
+node_js:
+ - NODE_VERSION
+
+script: npx rdme@RDME_VERSION openapi [path-to-file.json] --key=$README_API_KEY --id=API_DEFINITION_ID
```
+If you notice any issues with any of these examples, please open up an issue on [the `rdme` repository on GitHub](https://github.com/readmeio/rdme).
+
+> π§ Secretly store your ReadMe API Key!
+>
+> Nearly every CI service has a way to securely add secrets so that they're not exposed in your scripts and build logs. We strongly recommend using such a feature for storing your ReadMe API key. The examples above use `$README_API_KEY`, which is how you typically load such variables in your scripts. We've included some links below on how to configure these for the respective examples:
+>
+> - [Bitbucket Pipelines](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/#Secured-variables)
+> - [CircleCI](https://circleci.com/docs/env-vars/)
+> - [GitLab CI](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project)
+> - [Travis CI](https://docs.travis-ci.com/user/environment-variables)
+
## Troubleshooting
If you're running into unexpected behavior with `rdme` and need to troubleshoot the issue, you have several debug logging options available. We may ask for these logs (as well as a copy of your OpenAPI definition) when you contact our support team.
@@ -305,7 +278,7 @@ If you're troubleshooting issues in a GitHub Actions environment, you can enable
> π§ Debug Logs May Contain Sensitive Information
>
-> Enabling step debug logs will produce comprehensive logging for **all** of your GitHub Actions workflow steps. While GitHub automatically masks any sensitive information you load in with [secrets](#example-using-github-secrets), there might be other sensitive information that's exposed. Anybody with read access to the repository will be able to see these logs.
+> Enabling step debug logs will produce comprehensive logging for **all** of your GitHub Actions workflow steps. While GitHub automatically masks any sensitive information you load in with [secrets](#securely-using-your-api-key), there might be other sensitive information that's exposed. Anybody with read access to the repository will be able to see these logs.
>
> We **strongly recommend** that you only enable step debug logs in private repositories. If working in a public repository, we suggest recreating your GitHub workflow setup (e.g. with your GitHub workflow files, OpenAPI definitions, and anything else you need for syncing to ReadMe) in a separate private repository for testing purposes before enabling this setting.
>
diff --git a/package.json b/package.json
index 4ea431f82..674b0735f 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
{
"name": "rdme",
"version": "8.0.0-beta.9",
- "description": "ReadMe's official CLI and GitHub Action wrapper.",
+ "description": "ReadMe's official CLI and GitHub Action.",
"license": "MIT",
"author": "ReadMe (https://readme.com)",
"engines": {