Get started with the Reunite editor

The Reunite editor is a built-in cloud platform tool that you can use to add and edit content in your project. This guide is to help you get started with a Redocly project using the Reunite editor.

Before you begin

Make sure you have the following before you begin:

• A project created in your organization in Reunite.

  See Create a project for instructions on creating a project.

Go to the editor

From the Overview screen, select the project to edit.

Create a branch

Before you make any changes to your project, you should create a new branch. This new branch is a place where you can make changes without affecting the published site until you are ready. After you have iterated on your changes based on reviews by your team and the updates have been approved, you can merge your changes into the published site.

To create a new branch:

1. Go to the project editor.

2. Click the name of the current branch.

   

3. Enter the name for your new branch and select Create Branch.

Add content to the landing page

By default, the landing page for each directory in your project is index.md. New projects in Reunite come with an index.md file.

For this step, replace the content in the current index.md file with new content. You can either add your own content, or add the following sample Markdown to your index.md file:

# Start something new

There's a real excitement to starting something new.

- A blank page
- A fresh opportunity
- Limitless potential

## Good for writers

Writers need strong tooling so they can deliver a lot of content in a short time.
Efficiency is key, so this platform supports [Markdoc](https://markdoc.dev/) format (it's a lot like Markdown, but with added niceness).

Build-in link checking and branch previews lets writers move quickly and safely when creating content or managing updates.

## Good for readers

Clean layout and a visible table of contents makes good content a pleasure to read and process.

Now that you have added some content to your landing page, you can preview your project.

Preview your changes

Reunite includes a live preview pane where you can view your changes as you make them in the editor.

You can also preview how all of your changes will look in a sample build before you push your changes to the production build.

In the live preview pane

The Webview live preview pane allows you to view formatting updates to be sure they render as you expect before you publish.

Also, you can change the view to meet your needs. For instance, if you want to see how the main landing page renders on mobile screens. See Use the Webview to learn more about the options you have when using this live preview pane.

In the deployment preview

Reunite creates deployment previews for all branches that have an open pull request. The deployment preview includes all changes you have committed to your branch.

To see a preview build of your project:

1. Commit your updates.

   Steps to commit

   1. Click the Commit button, or the commit icon.

      

   2. Review the diff by clicking on the modified file.

      

      When you are finished reviewing the diff, you can close the tab on the (changes) file.

   3. (Optional) you can deselect the files you want to exclude from the commit.

   4. Enter a commit message describing your updates. For example, "Update index.md"

   5. Click Commit.

2. After you commit changes to the branch, open a pull request.

   Steps to open a pull request

   1. Click the Create pull request icon, or the Create pull request button on the Commit tab.

      

   2. (Optional) In the page that opens:

      • Edit the Title to your preference, By default, Reunite uses the name of your branch.
      • Provide a short description for the pull request.

   3. Click the Create pull request button.

      

3. Click the View project dropdown menu in the top right corner of the page. You might need to wait until the deployment completes before you can access the preview branch build.

4. Select Preview branch.

A deployment preview of the project with your changes opens in a separate browser window.

Add more pages

Now that you have updated the index.md page and seen a deployment preview, let's return to the editor to make some more changes to your project. To return to the editor, click Editor in the navigation pane on the left side of the page. If you only see icons, you may need to click the "greater than" symbol to expand the navigation pane.

Since a single Markdown page isn't very exciting, we should add a few more. Using the following steps, create the following two new files:

• style-guide.md
• about.md

To create a new Markdown file:

1. Click the + icon in the top right corner of the file tree in your editor.

   

2. Select New file.

3. Enter the file name into the text field and press return or enter on your keyboard.

Now that you have two empty Markdown files, either add your own content, or use the following example content:

# Style guide

10-second style guide:

- Please write in sentences.
- Use bullet lists, tables, and subheadings to break up the text.
- Every page needs links to other interesting pages.
- Never use future tense.

# About

This is an _excellent_ project.
You will learn **all** the things.

Customize the sidebar navigation

When you add more files to your project, a link to those files is automatically added to the generated sidebar navigation menu. This generated sidebar is based on the file structure of your project and requires an index.md file at the root of your project, in other words, not in a folder.

To customize the sidebar navigation for your project, you need to add and configure a new file named sidebars.yaml to the root of your project.

Add a sidebars.yaml file

The sidebars.yaml file gives you control over the sidebar navigation menu. You add it as you would any new file. It must be named sidebars.yaml.

To add a sidebars.yaml file to your project:

1. Click the + icon in the top right corner of the file tree in your editor.
   
2. Select New file.
3. Enter the sidebars.yaml as the file name into the text field and press return or enter on your keyboard.

Now that you have added a sidebars.yaml file to your project, you can configure it.

Configure the sidebars.yaml file

After you have added a sidebars.yaml file to your project, you need to add to it the pages and links you want included in your sidebar navigation using YAML syntax.

Add the following sample configuration to your sidebars.yaml file:

- page: index.md
  label: Home
- page: style-guide.md
- page: about.md
- group: Museum API
  items:
    - page: ./openapi.yaml

The sample configuration adds the index page, with the link text "Home", your new Markdown pages, using the first heading as the link text, and the Museum API reference documentation, generated from the OpenAPI file.

Now that you have more pages and a sidebar to customize the navigation for those pages, let's update the look and feel of your project to better reflect your brand.

Add a logo

One way to customize your project to better reflect your brand is by updating the logo. To update the logo, you need to create an images folder, add a logo to the images folder, and add a logo configuration to the redocly.yaml file.

Create an images folder

Images should be stored in images folders close to the content where they are referenced. You can have multiple images folders in your project. For this task, we need an images folder at the root of the project.

To create an images folder at the root of your project:

1. Click the + icon in the top right corner of the file tree in your editor.

   

2. Select New folder.

3. Enter images into the text field and press return or enter on your keyboard.

You should now have an images folder in your file tree.

Add a logo to the images folder

After you have created the images folder, you can add your logo image to it.

For the following steps, you can use your own image or download the following sample logo image:

To add a logo to the images folder:

1. Right-click on the images folder.
2. Select Upload files.
3. Select the logo file you want to use in your local directory.
4. Click Open.

You should see the logo file in the images folder in your project's file tree.

Add a logo configuration

Now that you have your logo added to the images folder in your project, you can configure the logo option under theme in the redocly.yaml configuration file.

To add a logo configuration:

1. Select the redocly.yaml configuration file in the file tree.

2. Copy and paste the following configuration into the file using the editor:

   redocly.yaml

   logo:
     image: ./images/logo.png
     link: /
   

   If you used a different image or updated the logo name - update the file path in the configuration to reflect your changes.

You should see the logo update immediately in the live preview pane. If you don't see your changes, try refreshing the live preview pane by clicking the Reload button. You can also commit your update to view it in the preview build.

The project is starting to look more like yours, but the colors could use some adjusting.

Update styles

You have come so far! Already you have new content, including a new logo and a sidebar. But, there's one more thing you will want to update, the styles. Your project uses CSS variables for most of the styling. So, to update the styles, you reassign the variable to whatever you want it to be.

Let's try reassigning variables on our sample project by updating the headings color.

To update the styles for your project, you need to create a @theme folder, add a styles.css file to the @theme folder, and update the CSS variable value in the styles.css file.

Create a @theme folder

First, you need to create a @theme folder. This time, let's create the folder a different way. The editor includes a drag and drop functionality. You can add folders by dragging them and dropping them into the file tree.

To add a folder using drag and drop:

1. Create a @theme folder on your computer.
2. Select the folder and drag it to the file tree.

When you release the button on your mouse, the folder should appear in the file tree where you placed it.

Create a styles.css file

You now know two different ways to create items in your project. Use one of the ways to create a styles.css file.

• Create the file using the + menu in the file tree
• Create the file in the @theme folder by right-clicking on it

Make sure the styles.css file is in the @theme folder, then you can update the CSS variable value.

Update the CSS variable in the styles.css file

To update the headings color variable, copy and paste the following configuration into the file:

:root {
   --heading-text-color: red;
}

You can add colors using hexadecimal and rgba numbers as well as HTML color names. You can also use the color picker tool by hovering over the color square next to the color and selecting a different color.

You should see the headings' color update immediately in the live preview pane. If you don't see your changes, try restarting Webview by selecting the Reload menu button and selecting Restart Webview. You can also commit your update to view it in the preview build.

Next steps

Now that you have started using the editor, check out the other ways you can customize your project with new content, configurations, or styles.

• Learn more about Markdoc and how you can use it to add interactive elements to your Markdown documents in the Markdown overview for technical writers.
• Checkout Configure sidebar groups for details on configuring sidebars.yaml with nested items.
• Find more CSS variables in the CSS variables dictionary reference documentation.
• Explore the different configuration options available in the redocly.yaml file in the Configure Redocly reference documentation.