Writing in the Editor

Atlas gives you a fully functional editor for writing and formatting your content. To access the editor, just click a file from the project dashboard, and that file will open in editing mode. Atlas has two editor modes—visual and code—and supports four markup languages: HTML, Markdown, AsciiDoc, and DocBook (read more about the editor modes in Editing Environments). The visual editor is only available to people using HTML, and includes a number of editing and formatting tools in the toolbar.

The Toolbar

Many of the standard formatting tools you've grown to know and love in other word processors are available in the visual editor's toolbar. From left to right, you've got the following options:

Alt Text Bold

Bolds your selected text.

Alt Text Italic

Italicizes your selected text.

Alt Text Add a link

Converts your selected text to a link. To link to a location within your project, instead of typing the full path, simply type the id of the element, preceded by a # sign, like this: #buildsettings—no file name is necessary. When you build, Atlas will make sure to correctly convert all of those link destinations to include the correct file name.

Alt Text Add an index entry

An index is a collection of key words, concepts, and phrases that are found throughout your project. To create an index, add index terms to your project text by placing your cursor where the term is discussed, and then clicking this button; you'll get a dialog box where you can add an index term, and optionally a secondary and tertiary term as well. When you build, Atlas will collect all of these terms into an alphabetical list linked to the tag locations that you specified. 

Alt Text Add a footnote

Inserts a footnote at the current cursor position. Place footnotes where you want the marker to appear in the output, and the Atlas toolchain will take care of floating the footnotes to the bottom of the page, adding the numbered markers, etc.

Note

Inline styles, such as bold and italic, can't currently be added to footnotes via the visual editor, but are supported and can be added in the code editor. You can read more about footnote markup in HTMLBook here.

Alt Text Define a section ID

Adds a unique ID to the current section for use in styling with CSS or anchoring a cross reference.

Alt Text Insert a cross reference

Creates a cross reference to a previously created section ID. In digital output formats, this will appear as a clickable link.

Alt Text Convert to or insert a numbered list

If you have some text selected, that text will be converted to a numbered list. If not, Atlas will insert an empty numbered list item to get your list started.

Alt Text Convert to or insert a bulleted list

If you have some text selected, that text will be converted to a bulleted list. If not, Atlas will insert an empty bulleted list item to get your list started.

Alt Text Insert a table

This button opens up a menu for you to set up a table that will be inserted at the current location of your cursor. You can set the number of columns and rows, and tell Atlas whether your table should include heading rows.  

Alt Text Embed media

Allows you to insert interactive web content, such as video or audio, into your document.

Alt Text Insert a code block or format inline code

If you have some text selected, Atlas will format it as inline code. If not, Atlas will insert a new placeholder code block for you to type in. If you hover over that code block, you'll see a little </> icon at bottom center. Click this icon to tell Atlas what code language this block uses, so Atlas will know how to apply syntax highlighting when you build.

Alt Text
Figure 5-1. Click the icon to add the language for the code block.
Alt Text Equation editor

Allows you to insert beautifully formatted math content into your document. The equation editor supports LaTeX formatting.

Alt Text Comment

Add comments to the document for your co-collaborators. Comments won't be output when you build the project.

Alt Text Paste from Word or paste plain text

This menu helps with copying over pieces from a Word document or from a plain text file. Paste the text you are copying inside the dialog box that appears, and Atlas will do its best to transfer over your formatting (or strip it out, if you're pasting plain text). 

Warning

This option is meant to be used only for short blocks of text, not for entire documents. If you've got an entire file that you want to put in Atlas, you should have that file converted to HTMLBook by a third-party vendor--or take advantage of Atlas' Conversion Services--and then add that converted HTML to Atlas instead.

Alt Text The Insert... menu

The Insert... menu is your one-stop shop for adding predefined text blocks to your document. You can add smaller blocks like notes, warnings, and sidebars, or higher-level blocks like chapters and sections (see Using and Adding Sections for more on the latter). To add a block, place your cursor where you want the new block to appear, and then choose the kind of block you want from the drop-down menu. Atlas will insert the pre-formatted block along with some placeholder text that you can replace.

Warning

Not all elements are allowed everywhere—for example, you can't insert a chapter inside a sidebar. If an element isn't allowed, it'll be grayed out in the menu.

Using and Adding Sections

The concept of sections can be a little tricky to wrap your head around. A section is a block of text that adheres to a specific theme or goes together in some way. The most popular kind of section is a chapter, and if you're writing a novel, this is probably the only kind of section you'll need.

However, more complex projects like reference manuals or documentation will likely want to subdivide chapters further into different levels of sections, as a way of organizing the content into more easily digestible chunks. For example, this chapter of documentation (the one you're reading right now!) is split into multiple level 1 sections, and some of those level 1 sections are split into level 2 sections, and so on. 

Atlas depends on nested sections in your project in order to create a hierarchical table of contents, both visible to readers, and for devices like the iPad or Kindle to use in their internal navigation systems. This means that if you want those features to work correctly when you build your project, you'll need to use nested sections to structure your content.

Note

For AsciiDoc and Markdown Users

If you're writing in AsciiDoc or Markdown, then Atlas will take care of adding correctly nested sections based on your headings when you build, with no extra steps needed from you. Proceed normally!

Sections in Atlas can go up to 5 levels deep: Chapter > Section 1 > Section 2 > Section 3 > Section 4. 

Sections in the visual editor are clearly delineated by dotted borders—the more borders, the deeper the section is nested. For example, if there are three border lines around a paragraph, then that paragraph is within a section that is three levels deep—most likely a Section 2 within a Section 1 within a Chapter .

The special markup is all happening behind the scenes in the code editor; all you really need to know is that you should use nested sections for your content (as opposed to free-standing headings). 

The steps for adding a new section vary depending on what kind of textual element you're currently editing. Generally, you'll follow one of these two paths:

  1. Insert a new paragraph by pressing Enter on your keyboard.
  2. With your cursor in that new, empty paragraph, go to the Insert... menu, and choose Section. 

Atlas will automatically insert a section at the correct nesting level; for example, if you're inside a Section 1, Atlas will insert a Section 2; if you're inside a Section 2, Atlas will insert a Section 3, and so on.

The steps above work great when you're just working with plain text paragraphs, but sometimes you'll need to add sections after more complex blocks like notes, sidebars, code blocks, and so on. If you just press Enter, you'll get a new paragraph inside that block element. To insert a new paragraph after the block, do the following:

  1. Hover your cursor over the block until you see the ¶ at the bottom right of the block. 
  2. Click the ¶ to insert a new paragraph after the block.
  3. With your cursor in that new, empty paragraph, go to the Insert... menu, and choose Section.
Warning

If a block element is located at the end of a section, the editor may not allow you to click the ¶ to add a new paragraph after that block. To get around this, you'll need to dive into the HTML behind the scenes:

  1. Open the Code Editor and navigate to the block element you wanted to add a paragraph after.
  2. Find the closing tag for that block element. (It'll usually be something like this: </div> , </aside> , </pre> , </ul> , or </ol> . The / means it's a closing tag, as opposed to an opening tag, which would not have a slash.)
  3. Press Enter immediately after that closing tag, and insert the following: <p>Some text.</p>
  4. Save and switch back to the Visual Editor. You should now see a new paragraph containing the text "Some text." after the original block element. You can delete the text and insert a section in that paragraph, or you can press the Enter key either at the beginning or end of that paragraph to insert another new, blank paragraph and add a section there (as described above).

Adding Images

Adding images is super easy—simply open the file navigator on your PC, and then drag the image file into your Atlas project. Atlas will automatically upload the image into your repository, and insert the image in the location you dropped it. Images will get stored in the same folder as the open file by default.

Alt Text
Figure 5-2. Add an image in one step: Drag the image from your system file navigator straight into an open file in Atlas.

Alternatively, you can add images to your repository by dragging them into the Atlas file navigator in the left sidebar; insert them into your project by placing your cursor in the correct location within your project, and then clicking the image file name in the file list. This method gives you finer control over the organization of the files in your repository (for example, if you want all images to be stored in a subfolder called "images").

Alt Text
Figure 5-3. Two step method for adding images: 1) Drag the image into the Atlas file navigator; 2) Click the image file name to insert it in place in the open document.

Supported File Types

The Visual Editor will display the following image file types: png, jpg/jpeg, and gif (both static and animated).

However, not all build outputs support all file types. For example, an animated gif will not render in a PDF. Here's a break-down of what files you should use, depending on your target output:

If you want to build your project to PDF only:

Use png, jpeg/jpg, static gif files, and svg files

If you want to build your project to EPUB or MOBI:

Limit yourself to png, jpeg/jpg, and static gif files

If you want to build your project to HTML only:

Use any image file that is supported on the Web

We generally recommend using high-resolution images that will work on many devices. For example, a 300 dpi png will look good both in a PDF and on a hi-res iPad. 

Cross-References and Internal Links

A common component of many reference-type projects is cross-references: links from one part of a document to another. These links might point to a section just a few paragraphs away, but could also point to a location in a completely different file.

Atlas has built-in cross-reference support, though it does take a couple steps. To add a cross-reference:

Add an id attribute to the element that you want to be the destination of the link. Place the cursor in the section you want to add an ID to, and click the ID button in the toolbar. In the box that opens, type an id attribute with any name you like (something descriptive and memorable is probably best--and remember not to use spaces in the id name!). The tool will auto-populate with a suggested ID based on the title of the section.

Now go back to the place where you are adding the cross reference. Select the text that you want to turn into a link, and click the cross reference button in the toolbar. In the dialog box that pops up, type the id name that you created in the previous step, as shown in the following figure.

Alt Text
Figure 5-4. Type the ID of the section you want to create a cross reference to.
That's it! You can move files and sections around while you're writing, and Atlas will update the link when you build to make sure it points to the correct file in your project.

Atlas will also automatically generate link text for you. This is great for referencing chapter numbers or section titles that might change. Insert a cross reference into a document without selecting any text, and when you build, Atlas will automatically add the title of the section, or the chapter number, depending on what type of element you are referencing.

For example, if you want to point to a chapter in a sentence like this:

Learn more about cross references in ???.

Add a cross reference in place of the question marks. Then, when you build, the sentence will look like this:

Learn more about cross references in Chapter 4.

If you later add in a new chapter before Chapter 4, the cross reference will automatically update the next time you build:

Learn more about cross references in Chapter 5.

Inserting Code Blocks

Adding a code block to a document in Atlas is simple: place the cursor on a new line and click the Alt Text button.

The Atlas book-building toolchain supports syntax highlighting via Pygments. This allows your code sections to render in final formats with color coding appropriate for the programming language displayed. To take advantage of syntax highlighting, you must specify the language of the code used within each code block.

Setting the Language

To set the appropriate language for a code block, hover your mouse over the block and then click on the </> bubble that appears.

Alt Text
Figure 5-5. Click on the </> bubble to open the code language dialogue.

Then, type the name of the appropriate language in the box.

Alt Text
Note

Atlas accepts valid Pygments short names in this box. These are case-sensitive and generally lowercase.

List of Supported Languages

Atlas supports syntax highlighting for all languages in version 1.6 of the Pygments library. Below is a list of some commonly used programming languages with the appropriate Pygments short name in parentheses. For a full list of available lexers, visit the Pygments site.

  • C (c)
  • CSS (css)
  • HTML (html)
  • Java (java)
  • JavaScript (js, javascript)
  • Perl (perl, pl)
  • PHP (php, php3, php4, php5)
  • Python (python, py, sage)
  • Ruby (rb, ruby, duby)
  • SQL (sql)
  • XML (xml)

Indexing

Indexing content with Atlas is similar to indexing in Adobe InDesign. Place index markers throughout the text near the relevant content, and a full back-of-the-book index will be created when you build.

Note

Placing Markers

We recommend that index markers not be placed inside code blocks or section headings, because anchors in those elements can cause oddities in the build output. Otherwise, markers should not have any adverse effects, so place them close to the relevant content!

To insert an index marker, place your cursor and click on the Alt Text button in the toolbar. You'll see a dialogue where you can add primary and secondary terms, specify sort-as labels, etc.

Alt Text
Figure 5-7. Insert indexterm dialogue.

Click OK, and a bookmark icon will appear in your text. Click on this placeholder icon to edit or remove your indexterm, but don't worry: these icons won't render in your final formats when you build.

Alt Text
Figure 5-8. Index markers in the visual editor.
Note

Do not create a new paragraph to add an index marker; doing so will create a blank paragraph space in build outputs.

Once you've added index markers throughout your project, add an index placeholder tag (<section data-type="index">&nbsp;</section>) to your content where you'd like the index to appear in your final build. This tag can either be in its own file or added to the same file as other content, but must be a root tag (read more here).

Finally, on the Configure tab, check the "Generate Index" checkbox for the formats you want to build, and build! Indexes in EPUB, Mobi, and Web PDF will have clickable links, and PDF versions will display the appropriate page numbers for each term.

Ranges

Indexterm ranges can be inserted by using the "ID" and "Range Startref" fields in the visual editor dialogue:

  1. At the beginning of the range, insert an index tag as usual, and add a unique ID to the ID field.
    Alt Text
  2. At the end of the range, enter the same index term and in the "Range Startref" field, enter the ID that you typed in above.
    Alt Text

Here's what the underlying markup looks like:

<a contenteditable="false" data-primary="Hello World example" data-type="indexterm" id="HWex">&nbsp;</a>
<a contenteditable="false" data-primary="Hello World example" data-startref="HWex" data-type="indexterm">&nbsp;</a>

Indexing Locally

When indexing via the Atlas UI, you don't need to worry about the syntax of the markup—Atlas takes care of it for you. However, if you prefer to insert and edit index markers outside of the Atlas UI, you'll need to use software designed for editing plain text. Popular word processing software like Microsoft Word or Notepad will introduce extraneous markup into Atlas files and should not be used.

Following are some examples of appropriate plain-text editors: