Welcome to the editor
Last updated

Welcome to the editor

Changed by Adam.

You can use the Reunite editor to customize your project by adding Markdown documents and updating the side navigation. You can also update styles by adding a styles.css file and reuse content by adding partial Markdown files.

This welcome document guides you through some of the basics of what you can alter in the Markdown documents.

Check out the Config file documentation for more information about the redocly.yaml file for even more ways you can customize your project including adding the following:

  • RBAC configurations
  • redirects
  • custom themes
  • API catalog
  • search
  • scripts, links, and SEO
  • and more

Add Markdown documents

Adding Markdown documents means you can write use cases, step-by-step tutorials, or conceptual content that you can then include with your API reference pages. We have also integrated Markdoc and Mermaid, which provide you additional formatting options for your Markdown.

Markdoc components

Realm uses Markdoc tags to add custom components to the CommonMark Markdown specification.

These tags extend the limited formatting ability of standard Markdown content.

Our integration with Markdoc also means you can add your own custom tags.

Admonitions

Admonitions are helpful for calling your users' attention to a specific piece of information as a warning, informational note, or an indication of success. The following are examples of how you could use the admonitions we have provided; however, they can be customized by changing the names or even the background color in your styles document.

Warning

This is a Warning message

Success

This is a Success message

Attention

This is an Attention message

Danger

This is a Danger message

HTML

You can paste HTML in your Markdown files. Useful for pasting iframe components such as a YouTube video.

<iframe width="560" 
height="315" 
src="https://www.youtube.com/embed/NcEHOlnAY6A" 
frameborder="0" 
allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Tabs

Tabs are useful for offering readers different options in code blocks or even in regular content. You can even next tabs.

The following example includes a code block tab nested within a content tab that includes a numbered list:

Create a widget by making the following HTTP request to the API:

  curl -i -X POST http://{HOSTNAME}:8000/widgets

Mermaid

You can also create Mermaid diagrams and embed them into your Markdown.

Read more about which Mermaid diagram types and review examples in our Mermaid docs. TODO: https://github.com/Redocly/redocly/issues/7810

three
one
c2
c1
two
b2
b1
a2
a1

Styles

The Redocly developer portal uses CSS variables for styling the look and feel of the portal. So, you can customize many of the styles used in the developer portal by updating the value of the CSS variable.

To update the CSS variable's value:

  1. Add a @theme folder to your project if you do not already have one.
  2. Add a styles.css file to the new @theme folder if you do not already have one.
  3. Determine the variable for what you want to update, using your browser's developer tools to inspect the element. Or find the item in the CSS variables dictionary in the documentation.
  4. Add the variable to your styles.css file with the updated value.

As an example, you can change the color of the top navigation pane to green by adding the following CSS to your styles.css file:

:root {
    --navbar-background-color: green;
}

Side navigation

The Redocly developer portal automatically creates a list of side navigation links based on the files and folders you have in your project. However, creating a sidebars.yaml file allows you to customize the side navigation in the following ways:

  • exclude certain files or folders
  • control the order of the files and folders
  • create multiple side navigation menus

If a sidebars.yaml file is in your project, your side navigation displays what is listed in it. If you place a sidebars.yaml file within a folder in your project, you can create multiple side navigation menus.

For example, the following example sidebars.yaml file placed in the root of your project displays only the markdoc.md file, even if you have other files in the root of your project:

- page: markdoc.md
  label: Welcome

Notice the label underneath the page location, which determines the title that is listed in the side navigation. If you do not include a label, the first heading is used instead.

To create multiple side navigation menus:

  1. If you haven't already, add a sidebars.yaml file to the root of your project.
  2. Create a folder and add some Markdown pages and a sidebars.yaml file to it.
  3. List the Markdown pages in the folder in the sidebars.yaml file.
  4. Add a link to one of the Markdown pages in the folder to a page listed in the root sidebars.yaml file.
  5. Click the link to go to the page and change the side navigation to the one in the folder.

Read more about configuring sidebar navigation and sidebar groups.

Content reuse

If you need to use the same exact content in multiple places in your documentation, best practice is to write the content in a single file and insert it programmatically, instead of copying and pasting the content manually. Otherwise, it can be very difficult to keep all the places the content exists consistently accurate.

You can add partial files to your project and reference them in Markdown files using the partial component. Partial files can be located anywhere in your project.

Read more:

You can also insert variables into partials, depending on the page that references them. See Mardoc Partials documentation for more information.

Running the project locally

Run the project locally to test content updates before pushing them up for others to view.

Prerequisites

Start development server

npx @redocly/cli preview
 
Next page