docs: v8 docs (#637)

* docs: updated setup/auth instructions * chore: drop v8 callout * docs: first pass at content reorg * chore: link fixes, more cleanup and language alignment * docs: update cover image s/o @jaclynchao 🥳 * chore: remove heading, add alt text Co-Authored-By: Jon Ursenbach <[email protected]> * chore: fix a few duplicated headers * docs: rework headers * docs(openapi): update heading hierarchy, content updates * chore: c'mon dude * docs(openapi): content reorg, better intro * docs(GHA): cleanup * chore: update comments * docs: add CircleCI + Travis examples CircleCI code sample source: https://circleci.com/blog/next-testing/ CircleCI config reference: https://circleci.com/docs/configuration-reference/ Travis CI lifecycle reference: https://docs.travis-ci.com/user/job-lifecycle/ Travis CI Node.js reference: https://docs.travis-ci.com/user/languages/javascript-with-nodejs/#specifying-nodejs-versions Co-Authored-By: Ryan Park <[email protected]> * docs: add setup language on node.js also rearranged the installation steps so global installation is first Co-Authored-By: Ryan Park <[email protected]> * docs: periods Co-Authored-By: Jon Ursenbach <[email protected]> * docs: sentence flow fix Co-Authored-By: Jon Ursenbach <[email protected]> * docs: add TOC (😭) thanks i hate it s/o https://github.com/jonschlinkert/markdown-toc * chore: removing emojis in headings * docs: better dependabot callouts per feedback from spang * chore: move callout per feedback from spang * docs: reworked intro per feedback from marketing sync * docs: rearranging sections/headers, link fixes per feedback from spang * chore: rearrange event examples * chore: small language rework * docs: try emojis in headers, do these work? * fix: remove encoded emojis from TOC have i mentioned how i hate manually updated TOCs * chore: add comment about how to generate TOC * chore: "guides", docs example usage * chore: swap emoji * chore: fix TOC * chore: use our reducer people * fix: add emoji instead of period * chore: update package description Co-authored-by: Jon Ursenbach <[email protected]> Co-authored-by: Ryan Park <[email protected]>
readmeio · Oct 31, 2022 · 757981e · 757981e
1 parent 34aa184
commit 757981e
Show file tree

Hide file tree

Showing 8 changed files with 407 additions and 214 deletions.
diff --git 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
@@ -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
diff --git a/documentation/github-actions-docs-example.md b/documentation/github-actions-docs-example.md
@@ -0,0 +1,68 @@
+---
+title: 'GitHub Action Example: Syncing Markdown'
+category: 5f7ce9e3a5504d0414d024c2
+---
+
+<!--
+
+Hello curious raw Markdown reader! 👋
+This Markdown page is syncing to ReadMe via the `rdme` GitHub Action 🦉
+Check out the full example below,
+and peep the resulting page in our docs: https://docs.readme.com/docs/github-actions-docs-example
+
+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.
+Check out `.github/workflows/docs.yml` for more info on this!
+
+-->
+
+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
@@ -0,0 +1,115 @@
+---
+title: 'GitHub Action Example: Syncing OpenAPI'
+category: 5f7ce9e3a5504d0414d024c2
+---
+
+<!--
+
+Hello curious raw Markdown reader! 👋
+This Markdown page is syncing to ReadMe via the `rdme` GitHub Action 🦉
+Peep the resulting page in our docs: https://docs.readme.com/docs/github-actions-openapi-example
+
+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.
+Check out `.github/workflows/docs.yml` for more info on this!
+
+-->
+
+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.
+
+> 📘 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
@@ -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>