Syncing Docs via CLI / GitHub

Update your docs automatically with rdme, ReadMe's official 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 ReadMe guides or API reference every time you've ship new code. Enter rdme: ReadMe's official command-line interface (CLI) and GitHub Action!

npmnpm BuildBuild

With rdme, you can create workflows for a variety of use cases, including:

  • Syncing OpenAPI/Swagger definitions (with support for bundling external references) πŸ“¦
  • Pre-upload validation (including OpenAPI 3.1) βœ…
  • Syncing directories of Markdown files πŸ“–

General Setup and Usage

To see detailed CLI setup instructions and all available commands, check out the rdme GitHub repository.

Markdown File Setup

In order to sync a directory of Markdown files to your guides, you'll need to add certain attributes to the top of each page via a YAML front matter block. See below for an example (using the page you're currently reading!):

---
title: Syncing Docs via CLI / GitHub
excerpt: Update your docs automatically with `rdme`, ReadMe's official CLI and GitHub Action!
category: 5f7ce9e3a5504d0414d024c2
---

If you're anything like us...

The only required attributes are the title and category. To determine what your category value should be, you can use the Get all categories endpoint and grab the id value from the response.

Specifying Page Slugs

By default, we automatically derive the page's slug via the file name (e.g. the file name rdme.md would become /docs/rdme in your ReadMe project). Note that our API uses slugify to automatically handle certain characters (e.g. spaces), which may lead to unexpected syncing behavior if your file names don't match your page slugs. If you prefer to keep your page slugs different from your file names, you can manually set the slug value in the YAML front matter:

---
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
---

Specifying Other Attributes

You can also specify several other page attributes in your YAML front matter, such as hidden (a boolean which denotes whether your page is published or unpublished). Any attributes you omit will remain unchanged on rdme runs. To view the full list of attributes, check out our Create doc endpoint documentation.

Dry Run Mode

If you're setting up new docs or if you're generally unsure if you've set up your page attributes correctly, the docs 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 available as well!). To enable dry run mode, use the --dryRun flag:

rdme docs path-to-markdown-files --version={project-version} --dryRun

The command output will indicate whether each page is being created or updated alongside all processed page attributes.

GitHub Actions Usage

With GitHub 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, you'll typically want to sync your OpenAPI definition and Markdown docs to ReadMe when a new build is deployed or when a new release is created. If you're not using either of those features then you can sync to ReadMe when code is pushed to the default branch.

πŸ“˜

Keeping rdme up-to-date

Note that the @7.2.0 in the below examples is the latest version of rdme. We recommend configuring Dependabot to keep your actions up-to-date.

For usage in GitHub Actions, create a new GitHub Workflow file in the .github/workflows directory of your repository and add the following steps to your workflow:

- uses: actions/[email protected]
- uses: readmeio/[email protected]
  with:
    rdme: [your command here]

The command syntax in GitHub Actions is functionally equivalent to the CLI. For example, take the following CLI command:

rdme openapi [path-to-file.json] --key=<<user>> --id=API_DEFINITION_ID

To execute this command via GitHub Actions, the step would look like this:

- uses: readmeio/[email protected]
  with:
    rdme: openapi [path-to-file.json] --key=<<user>> --id=API_DEFINITION_ID

We'll dive into several full GitHub Workflow file examples (including a video demo) below!

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.

Uploading a file

Follow these instructions 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:

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=<<user>> --id=API_DEFINITION_ID

Once you've obtained your API definition ID, your full GitHub Workflow file will look something like this:

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/[email protected]

      # Run GitHub Action to sync OpenAPI file at [path-to-file.json]
      - name: GitHub Action
        # We recommend specifying a fixed version, i.e. @7.2.0
        # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions
        uses: readmeio/[email protected]
        with:
          rdme: openapi [path-to-file.json] --key=<<user>> --id=API_DEFINITION_ID

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:

To recreate this magic in your repository, your GitHub Workflow file will look something like this:

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. @7.2.0
        # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions
        uses: readmeio/[email protected]
        with:
          rdme: docs ./documentation --key=<<user>> --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!

GitHub Actions has 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.

To use a GitHub secret in your rdme GitHub Action, first create a new repository secret. Let's say you create a new secret key called README_API_KEY. The usage in the rdme step will look something like this:

- uses: readmeio/[email protected]
  with:
    rdme: openapi [path-to-file.json] --key=${{ secrets.README_API_KEY }} --id=${{ secrets.README_API_DEFINITION_ID }}

Usage in Other CI Environments

Since rdme is a command-line tool at its core, you can use rdme to sync your documentation from virtually any CI/CD environment that runs shell commandsβ€”Bitbucket Pipelines, GitLab CI/CD, you name it! You can do this by invoking rdme with npx -y [email protected] in a Node.js environment. See below for several examples.

# Official framework image. Look for the different tagged releases at:
# https://hub.docker.com/r/library/node/tags/
image: node:14
pipelines:
  default:
    - step:
        script:
          - npx -y [email protected] openapi [path-to-file.json] --key=<<user>> --id=API_DEFINITION_ID
# Official framework image. Look for the different tagged releases at:
# https://hub.docker.com/r/library/node/tags/
image: node:14

sync-via-rdme:
  script:
    - npx -y [email protected] openapi [path-to-file.json] --key=<<user>> --id=API_DEFINITION_ID

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.

If you're working with the docs command specifically, we recommend using dry run mode first so your docs don't get overwritten. If you're still seeing unexpected results (or are running into issues with any other command), check out the debugging options described below.

Troubleshooting CLI

If you're troubleshooting issues with the CLI (or in some non-GitHub Actions environment), you can use the DEBUG environmental variable to print helpful debugging info to the console:

DEBUG=rdme* rdme openapi [path-to-file.json]

Note that this should only be used for development/debugging purposes and should not be enabled in production environments.

Troubleshooting GitHub Actions

If you're troubleshooting issues in a GitHub Actions environment, you can enable step debug logs in your GitHub Actions workflow by setting the repository secret ACTIONS_STEP_DEBUG to true. For more information on accessing, downloading, and deleting logs, check out GitHub's documentation.

🚧

Debug Logs May Contain Sensitive Information

Enabling step debug logs will produce comprehensive logging for all of your GitHub Action workflow steps. While GitHub automatically masks any sensitive information you load in with secrets, 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.

If you do enable step debug logs in your repository and your logs produce sensitive information, here are GitHub's docs on deleting logs.


Did this page help you?