Last updated

Reunite

Reunite is Redocly's cloud platform for creating, editing, previewing, and deploying API documentation projects using a Git-based version control system. You can use the editor to add, edit, and delete content and files in your project using a Git-based workflow to track and manage changes.

Cloud meets docs-as-code

You can also use Reunite with a Git hosting provider of your choice and a docs-as-code workflow by connecting a git content source. This article is about using the cloud platform.

Editor

Reunite includes an Editor page where you can add and delete files, edit content within files, and view live previews of your changes as you make them.

The editor includes the following panes that can be minimized:

  • A file tree pane where you can view all files included in your project, even remote and static files.
  • An editor pane where you can edit content using Markdown and Markdoc syntax.
  • A Webview live preview pane where you can view your formatting updates as you add them.

The changes you make in the editor are introduced to your published project using a Git-based workflow. Git is a version control system for tracking and managing changes that is integrated into Reunite.

Version control

Reunite uses Git for version control, either with a connected remote provider or a Redocly provided repository. The inclusion of Git for version control means that the changes you make in the Reunite editor are introduced to your published project using a Git-based workflow.

What is a Git-based workflow?

A Reunite Git-based workflow includes the following steps:

  • Before making changes in your project, create a new development branch.
  • After making updates, commit your changes to save them to your branch.
  • Open a pull request to have your committed changes reviewed by others.
  • When the pull request has been approved, it can be merged to the main project.

Branches and commits

Before making updates to your project, create a new development branch. Do this before each set of changes that you make. You can make changes to the project on a development branch without affecting the production project, or main branch.

All new branches in Reunite are based on the main branch. You can switch between branches if you have changes on multiple branches.

To include changes in your development branch in a preview deployment, you must commit those changes. You can choose to include all of your changes, or only select some of your changes. You can also revert all or any number of your changes, before committing.

After your first commit to a new development branch, you can open a draft pull request. All subsequent commits to that branch are added to the pull request until it is closed or merged.

When a pull request is merged, the branch is automatically deleted from Reunite.

Pull requests

The Pull requests page in Reunite is where you can manage your open and closed pull requests.

Pull requests are the first step in merging updates from a development branch with the main, or production, branch. If you want changes from a development branch to be added to the production project, you must merge the pull request with those changes.

On the Pull requests page, you can view, make comments, invite reviewers, request changes, or approve pull requests. You can also check the build status to see if your pull request has any issues like broken links or syntax issues.

Deploys

Reunite automatically deploys the following two types of builds:

  • Preview builds for each new version of a branch when you commit updates.
  • Production builds each time you merge a pull request with the main branch.

You can view these builds using the View projects dropdown in the top right corner of the Editor page. You can also view a list of all deploys (both production and preview), and trigger a deploy manually from the Deploys page.

Remote content

In the editor, you can add content to your project from external sources like hosted Git repositories, CI/CD platforms, or URLs. This content is represented in the file tree of the editor with a cloud icon to indicate it is connected to a remote source. You can view, edit, or sync the remote content in your project on the Remote content page.

Feedback

By default, every page of your published project includes a feedback mechanism that can be used to collect data from your users. Also, all code snippets by default include a report icon that users can click to report an error or issue with the code sample. These feedback mechanisms can be configured in your redocly.yaml file and the data they collect can be viewed and exported on the Feedback page.

API registry

The API registry is a list of all the API descriptions you have included in an API catalog. API catalogs are an organized way to present many APIs that can be filtered and searched. You can add an API catalog by organizing your API descriptions and adding a configuration to your redocly.yaml file. You can view the Scorecard status, metadata, custom fields, and logs for each API description included in your catalog on the API registry page.

Project settings

Most aspects of your project are configured in your redocly.yaml configuration file, but a few things are configured in Reunite on the Settings page. From the Settings page, you can view your Project ID, edit your Project name, and delete a project. You can also set a custom domain, add environment variables, and connect a Git repository from a remote provider like GitHub, GitLab, or Azure DevOps.

Resources

  • Learn more about the Remote content feature, including what the mount folder path is, and the difference between auto-sync and auto-merge.
  • To deploy regardless of link checker or Markdoc errors, see the reunite configuration option reference page.
  • Discover the different kinds of feedback mechanisms you can choose from and the different options that can be configured for each one in your redocly.yaml file.
 
Next page