“Markdown is intended to be as easy-to-read and easy-to-write as is feasible. Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.”

– John Gruber, Daring Fireball



What is markdown?

Markdown is a simple formatting solution that allows you to export content from your OneSpace projects with HTML formatting.

Content formatted with markdown is easy-to-read and easy-to-write because it uses simple plain text characters rather than complicated tags or formatting instructions. When you export the final content, Project Center seamlessly converts the markdown to HTML. This means contributors do not need to learn how to write HTML in order for your final content to be formatted with HTML, ready for use on your website.



What does markdown support?

We provide contributors with a Markdown Usage Guide which includes instructions for using the following basic markdown elements. A link to this guide is included on any textarea or text field elements that have markdown enabled.

  • Multiple Paragraphs
  • Linebreaks
  • Italic fonts
  • Bold fonts
  • Hyperlinks
  • Ordered Lists
  • Unordered Lists
  • Headers (H1, H2, etc.)

The markdown functionality will support many other additional advanced options as well. If you choose to use advanced markdown options, please confirm that the markdown syntax will work as expected and then provide additional instructions for your contributors in the assignment.



What does markdown look like compared to HTML?


Markdown Source
Contributors will use Markdown, such as the example below, in their copy within the text fields and text areas of the assignment.


 

—
HTML Source
When you export the final content, Project Center converts the markdown to HTML, such as the example below.



—
HTML Preview
When you use the HTML source on a website, it will render with the defined formatting, such as the following.





How do I enable markdown?

To enable markdown you will need to check “Allow Markdown” on each applicable text field or textarea in theTask UI Builder during Assignment Setup. This checkbox will control the contributor experience as well as the export settings for the field.





What does a contributor see when markdown is enabled?

When markdown is enabled on a text field or text area, the contributor will see two links above the field:

  1. Formatting Help - this links to our Markdown Usage Guide so that contributors can get additional information about using markdown syntax within their copy. 
  2. Preview - this converts the Markdown Source in the text box to an HTML Preview so that the contributor can confirm that they’ve used the correct markdown syntax. 
—

Here is an example of a text field with markdown syntax for a hyperlink.


—

Here is the same example text field with the Preview feature turned on. This allows a contributor to toggle easily between the markdown source and the HTML preview to confirm their work.




What do I need to include in the assignment instructions?

Be sure to include information in the instructions that tell contributors what markdown elements to use and in what scenarios. For example:

Include one link with descriptive link text in each paragraph. Use the correct markdown syntax for including links.
Example: [link text](http://www.linkurl.com)

Place single asterisks around the names of albums, books and movies to italicize them.
Example: *The Sandlot* is a quintessentially American film…

Additionally, we have a number of templates that use Markdown. Each of these templates includes detailed instructions specifically for using markdown. Find a list of these templates in ourTemplate Library.

—

Tips for Success

Test & confirm your workflow setup through export
It’s a good idea to test your new workflow all the way through to export with a sample batch. We recommend using realistic looking dummy data such as Lorem Ipsum with the intended markdown options included. This will help ensure that your assignments and instructions are setup properly to deliver the HTML you expect in the final export.
—
Consider your word count validation requirements

If your assignment requires word count validation on specific items, you will still have to break the article into segments. You may still enable markdown on each text field or text area to ensure that they are all exported with HTML. In the following example, we’ve enabled markdown on each text field and text area.


Below, you can see the HTML source for the example above. Each section would be exported via a separate column in excel.


If, on the other hand, your project does not require specific word count validation on small segments of an article, but rather the word count for an entire article is more important. You can ask contributors to include all headings, paragraphs, etc. all in one all-inclusive text area and use markdown to distinguish the headings, paragraphs etc. In the following example, we’ve used one large text area with markdown to capture all the headings and paragraphs for the Buying Guide content.


—
A note about using bullets…

If you use markdown on individual bullets within separate text fields, the markdown will not join them into one list, but instead, will display each individual bullet as an unordered list of one. (the bullet list will show up with visual breaks between the bullets). If word count validation is important for your bullets, you may want to add the markdown syntax to these sections at a later time. See the difference in the HTML code below.