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 content 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.
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 already hosted somewhere and you paste a link to the video.
Child Articles
This will let you place an inline Table of Contents of child articles anywhere in your article. Typically you will probably put this at the end, but there is nothing that requires it to be the last thing in your article. The rendered HTML is driven by a Lava template which can be edited on the book details page.
Block tools are just that, entire vertical blocks of content. But there are also inline tools, which affect only part of the content in a block. It is important to note that only some text-based blocks support inline tools. To get to your inline tools, highlight some text just as you would inside any text editor.
Note
Some browsers behave differently when using double click to highlight a word of text. Some highlight just the word and others will highlight the word and the following space. Often this won't really matter (such as making text bold). But there are some inline tools (such as linking) that might cause unwanted visual artifacts on that final space.
Below you will find a list of each of these tools in order. Forgive stating the obvious with some of the tools, but we wanted to provide a full list to you to remove any possible confusion.
fa fa-bold Bold: This will mark the selected text as bold.
fa fa-italic Italic: This will mark the selected text as italic.
fa fa-link Link: This will create a simple web link to another web page based on the URL you enter.
fa fa-book Article Link: This will create a link to another article, and optionally a section in that article. It can also be used to link to another section in the current article. When linking to an article, this option should be used instead of a regular link. The article link will track any changes that might cause the URL of the article to change.
fa fa-code Code: This is a way to highlight the text as a code segment. This can be used to specify exact text to be entered, or sometimes just to draw special attention to the text.
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 intended. 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.