New Markdown Editor Overview


We're Rolling Out the New Editor in Stages!

As of October 13, 2022, all new ReadMe projects are equipped with our new Markdown editor 🎉

If you received early access to the beta version of our Markdown editor, you've now been automatically transitioned onto our new editor.

If your editor looks different that means you're on our legacy editor! Over the next few months we'll be transitioning everyone from our legacy editor onto our new Markdown editor so stay tuned!


API documentation is a key reason why most customers come to ReadMe, and in order to provide developers with that documentation you need to well, write it. In order to write said documentation, you need an editor to make that happen. We’ve been hard at work for the last year building a fully redesigned version of our Markdown editor that combines the best of Markdown syntax with the ease of a WYSIWYG editor. We’re excited to be releasing it in beta and to start sharing it with you!

Getting Started with the Editor

When you open a new page in the editor you’ll notice a new Getting Started Guide on your righthand side—that’s Owlbert, ReadMe’s mascot, welcoming you to the new editor experience and providing some helpful onboarding tips! Owlbert’s Getting Started Guide will appear on every page in your Guides, API Reference, Changelog, and Custom Pages in case you have any questions while creating documentation using the new editor.

Creating Content in the New Editor

You may notice that the drag-and-drop blocks and widgets that formerly lived on the right side of our documentation pages are no longer there. Now they live in a handy slash command menu that can be accessed at any time by typing “/”.

Inserting a New Block

To insert a new block, type “/” and the full, scrollable slash command menu of block and embed options will appear. You can also type additional text for example, “/call” and the menu will auto-filter so that only the callout options appear.

These are the blocks that the beta version of the editor supports:

  • All Core Markdown
  • Links
  • Blockquotes
  • Callouts - Info, Error, Success, and Warning
  • Bulleted, Check, and Numbered Lists
  • Code Block
  • Divider
  • Image Block
  • Recipes
  • Tables
  • Embeds - YouTube, GitHub Gist, PDF, and JSFiddle
  • Custom HTML

Block Actions Menu

When you hover over any block, three lines will appear. If you drag the selected block or text, you can move it to another location on the page. If you click the three lines, the Block Actions Menu appears. From there you can copy or delete the block or text, or add a new line below.

Adding Variables, Glossary Terms, and Internal Links

You can use keyboard shortcuts to add Variables, Glossary Terms, and link to other pages in your ReadMe project.

To add Variables or Glossary terms to your page, type << and a scrollable menu of all Variables and Glossary terms in your project will appear. To link to another page in your ReadMe project, type [ and scrollable menu of all pages for you to choose from will appear.

Copying and Pasting Text

Copying content from the editor will preserve all Markdown syntax and render all blocks and styling when pasted into another page in ReadMe or another Markdown editor. Similarly, pasting content from another source into the editor will preserve all Markdown and render all blocks and styling.

Inserting Line and Paragraph Breaks

In addition to using the Insert Line Below option in the Block Actions Menu, if you are writing text and want to create a line break, also known as a soft return, you can press SHIFT + ENTER at the same time on your keyboard to create a new line in the page you’re writing.

If you have inserted a block or embedded a widget, e.g., a callout where your text is formatted differently, you can press SHIFT + ENTER on your keyboard to exit out of that block or embed and begin typing in a new paragraph.

Formatting Content in the New Editor

We’ve also introduced a new method for formatting text! Now, when you highlight text, an inline hover menu will appear! Within this menu you’ll have the option to bold, italicize, and strikethrough text, as well as hyperlink text and toggle text to appear as inline code.


In addition to using the inline menu, you can also use keyboard shortcuts to format text and create new sections in your page.

Here’s a list of supported keyboard shortcuts:

Markdown Syntax

While the new editor looks and feels different, one thing that has remained consistent from our legacy editor is that all Markdown syntax has been preserved.

You can still use Markdown syntax to reproduce many of the block and text formatting options that you can find in the slash command menu and inline formatting menu.

Here’s the Markdown Syntax the editor supports:

Formatting Images

Anytime you add an image or hover over an image block, a formatting menu appears. This menu allows you to replace or delete the image file, add alternate text, edit the size of the image, add a caption, or add a border!

Reverting to the Raw Text Editor

If at any time while using the new editor you’d like to switch to Raw Text mode, click the cog icon in the top menu of the page and toggle the "Use Raw Text" button to green. All page content will be saved when you toggle between the new Markdown editor and Raw Text editor experiences.


Raw Text reverts your page to Raw Markdown!

Heads up! When you toggle the button to "Use Raw Text," this action reverts your page to raw Markdown. It does not revert the page back to the legacy version of the editor, and you will not be able to use magic blocks.