Markdown with Scrivener

Want to write professional-looking content for AppleVis? Most of the AppleVis editors and bloggers use Markdown, a simple language for generating HTML. To create Markdown content, familiarize yourself with Markdown syntax using this quick introduction to Markdown. That's all you need! Now just start using Markdown in your AppleVis posts and comments!

Wellcome back. By now, you've discovered that knowing Markdown isn't enough. Markdown syntax is pretty unforgiving, and your first Markdown post probably contained errors that you had to edit. Or you just gave up.

Perhaps the best single tool for creating Markdown content is MultiMarkdown Composer. This app is free for MacOS. The user interface consists of two panes. Enter Markdown content on the left pane and preview the output on the right. If you find any mistakes, go back and fix them in the left pane.

Many people use MultiMarkdown Composer to create their Markdown content, but I mainly use it as a previewer. To create the content, I use a more powerful and flexible tool—Scrivener.

About Scrivener

Scrivener, available from Literature and Latte, is a powerful content-generation tool designed for writers. It's extremely flexible and configurable, supports very large content with ease, and outputs to many formats, including Markdown. I use v3.0.2 on MacOS, but Scrivener is also available on iOS and Windows. Try Scrivener free for 30 days. The standard license costs US$45.

Scrivener is the end of my long search for a new word processor. I needed a replacement for Word 2010 on my retired Windows 7 system. I was discouraged by the Microsoft Office subscription model for Office 365 and VoiceOver issues with Apple Pages, I wanted an app that was affordable, accessible, and content-oriented. After I bellyached to a couple of writer friends, they encouraged me to try Scrivener. I figured anything used by professional writers to create 150,000-word manuscripts ought to be worth a look.

Scrivener is accessible on MacOS and comes with a helpful interactive tutorial. The full Scrivener manual comes in PDF format, which I found cumbersome to use. Fortunately, a quick web search provides answers to most Scrivener questions.

Scrivener is geared towards creating content. It uses a compile model to produce output in a variety of file formats and visual styles. When I noticed Markdown support. I had to give it a try. I've now written three blogs in Markdown with Scrivener.

Scrivener Layout

Launch Scrivener. Scrivener prompts you to select a template. Select the blank template. Then enter a name for the project and specify a save location.

Scrivener opens your new blank project in its main window. The interface consists of two main areas, the editor window and the binder table. Jump between them with control+tab.

The binder table is a hierarchical tree of nested folders and documents. I configured Scrivener to use folder and document names as Markdown headings, with heading level determined by the nesting depth.

In Scrivener, both folders and documents can have text. That's right, folders are more than just containers, they can have text, too. In a simple Scrivener project consisting of one folder, the Markdown output uses the folder name as a heading, and the folder text as the body text after the heading.

Sighted users drag and drop binder documents to control order and nesting level. This is accessible with VoiceOver using control+command plus any one of the arrow keys. You might need to experiment with this to get the hang of it. To create a new document, hit enter then enter the title. With focus on a folder or document, hit escape to edit the title.

I do 99% of my work in the editor window, the binder table, and a third area, the Compile dialog.

Compile Settings for Markdown

The Compile dialog is Scrivener's nerve center, with several controls that determine how your content will appear in a number of output formats. This section describes how to configure the Compile dialog to generate Markdown.

To open the Compile dialog, hit command+option+E. This dialog is a bit cluttered. You might want to navigate through the controls to become familiar with it.

Follow these steps to configure the Compile dialog for Markdown output.

• Set the Compile For pull down menu to MultiMarkdown.
• In the Format table, select Basic MultiMarkdown.
• Open the Assign Section Layout dialog.
  • In the Assign Section Layout dialog, select both Heading and Section from the section type list and assign them to the template called Text Section With Heading. This tells Scrivener to use the binder titles of folder and documents as Markdown headings.
  • Press Enter to close the Assign Section Layout dialog.
• Back in the Compile dialog, select the Option tab. Check the following checkboxes:
  • Convert Rich Text to MultiMarkdown
  • Treat "Preserve Formatting" as Raw Markup.
• Press Enter to close the Compile dialog and generate output.

Now wipe the sweat off your brow. Fortunately, the options are sticky, so you only need to do this configuration once per project.

After you close the Compile dialog, Scrivener opens a Save As dialog. Specify the output file name and a location to save it. This dialog also contains an option to open the output file in another application. This is an easy way to preview your output in MultiMarkdown Composer.

With Scrivener configured to compile your project to Markdown, you're ready to start creating your content. Hit control+tab if necessary to bring focus to the editor window. The following sections describe how to access various Markdown features from Scrivener content.

Creating Links

Links just work. Use Scrivener's native link support. Here are the steps.

1. Copy the target link to the pasteboard (from the Safari address bar, for example).
2. In Scrivener, select the text to associate with the link.
3. Open the Edit menu and select Add Link.
4. The Add Link dialog populates the address field using the link from your pasteboard. If you didn't copy it in step 1, enter it manually. Then hit Enter.

When you compile to Markdown, the document text from step 2 will appear in brackets, followed by the target link address in parenthesis. The text from step 2 appears as a clickable link in MultiMarkdown Composer and appleVis.

Bold and Italic

Use Scrivener's native font formats for bold and italic text. Select the text, then hit command+B or command+I. While in Scrivener, VO+T describes font information, including whether bold or italic are selected.

Tables

I almost never create tables in my AppleVis blogs, but Scrivener's native Table support produces the appropriate Markdown. Select Table from the Insert menu. The default table has two rows and three columns. Use the Table submenu from the Format menu to modify the table. Markdown output uses the first row as column headers.

Here's an example table using Scrivener's native table format.

Creating Headings

Probably the single best reason to not hand-code Markdown is that changes to heading level must be done manually, and it's a real pain. Scrivener has a better solution—use the document and folder titles in the binder.

If your binder titles aren't showing up as headings in the Markdown output, take a look at how you've set up section layouts. In the Compile dialog, open the Assign Section Layouts dialog and make sure that Heading and Section are set to Text Section With Heading, as described previously. Once you've done this, the folder and document titles in the binder compile to Markdown headings and the folder and document text compile to body text following the headings.

The name of a folder becomes a Heading 1, and the name of a document in the folder becomes a Heading 2, for example. Nest the folders to create subsections within sections.

Avoid heading level 2 in AppleVis content because AppleVis uses it for other page content. To skip heading level 2 in Scrivener, nest an empty dummy folder under your top-level binder folder, and nest the rest of your content below the dummy folder. In the Compile dialog, uncheck the dummy folder to leave it out of the compile. The compiled Markdown output will use heading level 3 and greater for all your headings.

Preserve Formatting and Raw HTML

Many Markdown features have no equivalent in Scrivener, or the mapping to Markdown is unsatisfactory. Fortunately, Scrivener lets you embed Markdown and HTML tags directly in your content.

To do this, select the text containing Markdown or HTML tags. Then go to the Format menu and select Preserve Formatting.

Horizontal Rules

For example, the Markdown tag for a horizontal rule is five asterisks. In Scrivener, enter five asterisks on a line by themselves. Select them, then go to Format->Preserve Formatting. Scrivener passes the asterisks directly during compile, which produces a horizontal rule in MultiMarkdown Composer.

*****

The above five asterisks, marked with Preserve Formatting, produces a horizontal rule.

Just like that!

I know. Horizontal rules are so 1994. My point is that Scrivener lets you create your own Markdown using Preserve Formatting. Here are a couple more examples.

Code

To generate code blocks, use either Markdown or raw HTML tags.

Indicate a code block in Markdown by adding four spaces at the start of each line.

    This example line, marked as Preserve Formatting, starts with four spaces.

The above Markdown produces the following.

This example line, marked as Preserve Formatting, starts with four spaces.

You can do the same thing with the \<code> HTML tag.

 <code>
A code example using HTML tags.
</code>

Don't forget to select that text and mark it as Preserve Formatting. The above raw HTML produces the following.

A code example using HTML tags.

Em Dash and Other Symbols

To include any kind of special symbol, use the HTML code directly in your content. There's no need to mark the text with Preserve Formatting.

For example, use &mdash; for an em dash—like this.

Note that if you type two dashes, Scrivener converts them to a Unicode em dash by default. Don't do this! Unicode em dashes compile to three dashes, which is the Markdown tag for an em dash. Unfortunately, not all Markdown translators support this tag. It will look like an em dash in MultiMarkdown Composer, but will come out as three dashes when you post to AppleVis.

Bullet and Number Lists

Create simple lists using Scrivener's native list mechanism. Go to the Format menu, open the List submenu, and select the desired list type.

Indented lists, or sublists, are a bit trickier. While Scrivener supports lists and indents, the two features don't work in combination when exporting to Markdown. For this reason, I recommend using raw Markdown in the Scrivener content to create lists. Non-indented lists start with an asterisk. Indent level one starts with four spaces and an asterisk. Add four spaces for each additional indent level.

• This list uses Preserve Formatting.
• Each line starts with an asterisk.
  • This sublist item starts with four spaces and an asterisk.
  • The sublist is indented one level.
• The non-indented list continues after the sublist.

Block Quotes

Use Markdown to create a block quote. Start the line with a greater than sign, select the entire quote, and mark it as Preserve Formatting. It will appear like the following.

Accessible design is good design.—Steve Ballmer

Cleaning up Markdown

After several repetitions of writing in Scrivener and reviewing in MultiMarkdown Composer, you're finally ready to post to AppleVis. Here are a few steps to remember.

• Scrivener's output Markdown text file contains a title and author tag at the top. Don't include this in your AppleVis post. I'm sure there's a way to stop Scrivener from writing them to the Markdown output, but I haven't figured it out.
• After deleting those lines, the first line is the heading level 1 for your post. Remove the leading and trailing hashtags, then copy and paste this into the title text field on the AppleVis web page.
• Finally, copy and paste the remainder of the Markdown text file into the body text field on the AppleVis web page.
• Don't forget to select Markdown from the AppleVis format pulldown menu.
• As careful as I am, I always screw things up. That's why I now use the Preview button and review the entire article in AppleVis before I hit the Save button. This is also insurance against differences between MultiMarkdown Composer and AppleVis.
• While previewing the article in AppleVis, one thing I check for is triple dashes using VO+F. If I find a triple dash, that means my Scrivener source contains an em dash symbol rather than the HTML &mdash; code.

Conclusion

Scrivener is an accessible tool for anyone doing serious content creation. It lets you focus on developing the content, then worry about appearance and formatting during the final compile phase.

Scrivener is part of my Markdown toolchain. I iteratively write in Scrivener and preview in MultiMarkdown Composer. When I'm ready to go live, I do a final preview in AppleVis, then post it.

Is it perfect? No. I wish native nested lists compiled to Markdown. But the Preserve Formatting feature is a great workaround that provides support for coding Markdown tags directly in the content.

Scrivener isn't the only way to develop Markdown. Let me know how you use Markdown in the comments.