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:

Raw Mode Editor Functionalities

We have made the decision to deprecate the raw mode editor with the release of the new editor. The main use case of raw mode is to copy and paste content, and since the new editor handles this seamlessly, an additional raw text mode of the editor is no longer necessary! Additionally, entering invalid raw text can result in site breakage so by removing this functionality, we are adding an additional layer of protection to your ReadMe site.

If you’d like to use the raw mode editor functionality, you can revert to the legacy editor and toggle the β€œRaw Text” functionalityβ€”accessible in the top navigation of the pageβ€”on.

Reverting to the Legacy Editor

If at any time while using the new editor you’d like to revert to the legacy editor, just click the β€œUse the legacy editor” button in the banner at the top of every page. All page content will be saved when you toggle between the new and legacy editor experiences.


Did this page help you?