New Markdown Editor Overview (Beta)

📘

The New Markdown Editor is in Beta!

If you’d like to get access to the new Editor or any of our upcoming beta releases, please fill out this form.

Overview

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

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

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

Shortcuts

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:

Reverting to the Raw Mode Editor

If at any time while using the new editor you’d like to revert to raw mode, just click the “Use Raw Mode” button in the banner at the top of every page. All page content will be saved when you toggle between the new Markdown editor and raw mode editor experiences.

🚧

Raw Mode reverts your page to Raw Markdown!

Heads up! When you click the button in the top banner to "Use Raw Mode," that 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.


Did this page help you?