Markdown: here's some user level docs

javaweaver

As part of putting up a Vanilla site, I put together a short documentation describing how to format entries. (The site was set to support the normal editor, markdown, and html). Thought it might be useful for others to copy. I know it took me a couple of hours to put it together, so in interest of perhaps saving someone else some work, here it is. Change the "example" text to your specific site.

(I couldn't get the Html editor to actually show this code, so I suggest you use View Page Source in your browser and then copy the actual html code produced for this page.)

Using Normal, Markdown, and HTML Editing Quick Guide

This forum site provides you with three formatting choices when you are adding or editing your discussion comments. At the most basic level, you can simply enter your comments as text with no additional formatting such as bold, links, or headings. At the next level, you can choose to use the Markdown formatter which let you enter formatting characters like **bold** to get bold. Finally, you can use the HTML formatter which allows you to use many standard HTML tags.

You select which formatter you use for a particular discussion entry by picking one of the buttons (Text, Markdown, Html) at the bottom of the Enter your comments text box. If you don't see these choices, then you can enable them by going to the "Account" tab, then click the "Forum Preferences" in the left sidebar, and finally checking the box for "Show the comment format type selector when adding comments".

You might be interested to note that this particular entry was created using the HTML formatter, so really anything you see done here can be done using that mode.

---

Normal Text Mode Editing

The normal text editor is very simple. You simply enter your comments in plain text. You start a new paragraph or leave a blank line with the "Enter" key. That's it. No other formatting is supported, and for many entries, that's all you'll need.

The other two formatting choices, Markdown and HTML, both enhance the basic text mode editor. That means you still control paragraphs using your "Enter" key.

---

Editing with Markdown

One of the editing choices you have for this forum is called Markdown. Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, which is then automatically converted to the proper code for display in your discussion comment. If you want to enter normal text, just type it in. Use the enter key to start new paragraphs. For boldface, links, headers, and some other formatting, you use characters such as *, [], #, extra blanks, and _.

Markdown Syntax

The following sections include examples of using characters for formatting your text with Markdown.

Emphasis

A single underscore or asterisk is italic (_italic_ or *italic*), two is bold (__bold__ or **bold**), like this: italic or bold.

Headers of different sizes

You use from one to six #'s to produce headers, one large and six smallest. For example, #### Level four header #### produces (trailing #'s are optional for all header formatting):

Level four header

while ### Level three header ### produces:

Level three header

Entering Links and Images

You use [] and () to enter links: [Example Site](http://example.net "Example") produces: Example

For images (hosted on a website such as Photobucket.com), ![Title](http://photobucket.com/fill-in-actual.jpg "Title") produces:

Lists

Unordered lists use *, + or - like this:
- This - is - a list

• This
• is
• a list

Ordered lists use number followed by period.

1. with 2. numbers

1. with
2. numbers

Blockquote

> You can use lines starting with a > (greater than)
> at the beginning to get them in a block like this.

Code

Indent text at least 4 spaces for all formatting in it to be ignored.
# This isn't displayed as header, because it is indented 4 spaces.
Inline code can also be `escaped` with backticks: escaped.

Horizontal lines

You can add a horizontal line with three or more dashes on a line:
----

---

Escaping

If you don’t want some of these rules to apply, they can be escaped by preceding the special character with a backslash: This is \*\*not\*\* in bold.

This is **not** in bold.

More about Markdown

Markdown has more features and alternate tags. You can find out more at the official Markdown site.

---

Editing with HTML

The third editing mode supported in HTML. This mode allows you to format you code using standard HTML tags. Most basic formatting tags are allowed, but script code and other potentially dangerous code is stripped. We're not going to provide you with an HTML reference here - they're available plenty of other places.

This editor allows you to post an embedded video player directly in your comment by using the video ID provided by google, youtube, or myspace.

To post, you paste just the id in a custom <video> code designed just for the HTML formatter.

<video type="google">docid</video> for (google video) -or-
<video type="youtube">video id</video> for (youtube) -or-
<video type="myspace">video id</video> for (myspace)

Note that the HTML editor sits on top of the basic Text editor, so you don't really need to use <p> tags.

---