Markdown Editor Overview

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. Our fully redesigned Markdown editor combines the best of Markdown syntax with the ease of a WYSIWYG editor. Keep reading for the full details on this experience 👀

Getting Started with the Editor

This tutorial video provides a full overview of ReadMe's Markdown editor, along with the updated Sidebar and Page Controls ✨

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.

In addition to the four default callout options—info, success, warning, and error—you can also change the emoji using the emoji menu (on the left side). If you'd like to change the callout theme attributes, you can customize using CSS selectors and variables.

These are the blocks that ReadMe's Markdown 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, JSFiddle, and Iframe
• Custom HTML

You can also add emojis to your text by typing : and bringing up a menu of options to insert 😉

Tables

You can add a table to any Guides or API Reference page using the slash command menu, however, blocks are not supported within a table cell.

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.

🚧

Variables are stored in raw Markdown using the syntax \<<variable-name>>. To display regular text surrounded by angle brackets, add a single \ escape character preceding the text — e.g., \\<<variable-name>>.

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.

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.

📘

Markdown not supported in table cells

You can't use markdown in a table cell. Instead, you must use HTML tags. See Tables above for details.

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 Raw Mode

If at any time while using the editor you’d like to switch to Raw Mode, click the three dot menu above the page's title and toggle on the Raw Mode option. All page content will be saved when you toggle between the 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.