Overview

You have one of two options for editing the article text. By default, any new book you create will use the Structured Editor. Alternatively, you can switch it to the Markdown editor - but you must do this at the time you create the book.

[!TIP] If you have existing books in Markdown, you can convert the book into Structured Editor. This will wrap the existing Markdown in a Markdown block of the Structured Editor. However, you cannot currently convert a Structured Editor book back to Markdown.

The Structured Editor consists of blocks that define the format of the text in that block. Think of each block like a paragraph. Your paragraph can be a normal paragraph of text, an alert, a quote, etc. For example, if you just start typing in an empty text block it will stay as one block until you hit the Enter key. That will then start a new block. The new block can also be a paragraph block, but you could then switch it to a heading block instead.

Additionally, the text in the blocks can usually have the normal bold, italics and hyperlinks that you would expect.

Blocks

A number of blocks are available to you. When you start a new block of text, you can either click the "+" that will appear or hit the Tab key and the block menu will appear. You can then select which type of block you want to create. From there just start typing.

Text

The text block is your standard paragraph block. This is the one you will likely be using most often so it is the default when starting a new block.

Heading

The heading block allows you to apply different types of headings to your articles. These are used to build the table of contents for the article that will be displayed on the right side of the screen.

Lists

The next block is the lists block. With this you can create either bullet points or numbered lists. You can also indent them for sub-lists.

Image

The image block allows you to upload an image into your article. It will be stored in Rock. Using this block would normally be used if you want to select the file on disk to upload. But you can also paste an image or drag and drop the image into the editor to automatically create the image block and upload.

Markdown

The Markdown block provides two features. The first is the ability to convert existing books to the new Structured Editor. Your existing Markdown content gets placed into one of these blocks. You can then slowly convert the Markdown into individual blocks, or just leave them as-is and just use the new editor for any new articles you create.

Secondly, you might have some people that prefer Markdown or simply have some content that works better as Markdown. Such as external content that is already written in Markdown that you normally just copy and paste in.

Table

The next block allows you to create tables. The table editor can take a little getting used to. But basically you will see little squares show up outside the columns and rows. If you click on these they will let you add new columns and rows or remove existing columns and rows.

Alerts

The next icon in your block toolbar is the alerts. These let you call out notes, tips or warnings to your users.

Code

Next up is the code block. This lets you provide sample code, such as HTML or CSS, and it will be displayed to the user with syntax highlighting. This provides for a much richer user experience than a bunch of text all in one color.

Raw HTML/Lava

This block allows you to enter raw HTML (including Lava) that will be passed through completely unmodified. Meaning two things. First, this block does not automatically process Lava itself. Second, it means you can use things like multiple lines without breaking your Lava. Most other blocks will modify your text slightly, even though it looks correct. Such as replacing new line characters with HTML line breaks. This often causes issues with Lava, so this block allows you to write exactly what you want displayed on the page.

Quote

Finally is the quote block. As you might guess from the name, this allows you to provide some text that will appear as if you are quoting somebody.

Video

While this block does not appear in the toolbar, there is a video block that allows you to embed videos into your documentation. The way to do this is to paste a link (URL) to the video and it will automaticlaly insert a new video block. For example, if you load up the video on YouTube, then copy the URL from the browser and paste (CTRL-V or CMD-V) into the editor and it will automatically create an embed for that YouTube video.

The following video types are supported:

• Rock Media Videos
• YouTube
• Vimeo
• MP4/M4V/MOV

[!TIP] To get the link to a Rock Media video, go to the video detail page and copy that link. It should look something like https://yourdomain/admin/cms/media-accounts/items/1. The domain part does not matter, but the /admin/cms/media-accounts/items/ part does matter. This is what it uses to recognize Rock Media videos.

[!TIP] Do not try to paste the actual MP4 video file or drag and drop it. If you do it will upload the actual file as an attachment which is probably not what you want. Instead it needs to be a file alraedy hosted somewhere and you paste a link to the video.

Editor

The editor itself is pretty straight forward, but we'll point out a few tips and tricks to you that should help you get quickly familiar with it.

First, whenever you click into an existing block a small square menu will appear in the right-side gutter. If you click on this you can configure additional settings on the block. For example, in the Heading block you can choose which type of heading the block should be.

You can also use this menu to move a block up or down in the ordering of blocks as well as delete the block. Another feature for ordering blocks is that you can click and drag on that little square menu to quickly move a block around the article.

Second, if you want to insert a new block in between two blocks you need to go into the previous block and press Enter. For example, if you need to insert a new paragraph between two existing paragraphs. Set your cursor to the very end of the first paragraph and hit Enter and a new block will be created between the two.

Sometimes that isn't really an option. If you have an image followed by a paragraph and you need to insert a new paragraph right after the image you will need to get a little creative. One way is to create a new paragraph after the existing paragraph and then drag it up to put it into position.

Third, the editor also supports pasting content directly from other editors. For example, you can copy and paste text from a web page into the editor or from Word. Be aware that copying and pasting text from one editor to another does not always reproduce the content exactly as intented. It is usually pretty close, but you should visually check over the pasted content to make sure it comes across correctly.

As an example of this, you can copy and paste headers and text from Word and it comes across pretty good. But if you have a bullet list in Word and try to paste it into the Structured Editor it won't come across correctly.