Using Markdown documents

Using Markdown documents

Each item can have a rich text document, which is typically shown in the HTML pane. That pane supports a number of different formats, one of which is Markdown documents.
 
To create a new Markdown:
  • Menu > File > New > New Markdown file
You can then enter text using the Markdown syntax. Whenever the document is saved (or focus is moved to another item), IQ will generate the HTML version of the document
If you structure a large document into a hierarchy of small-sized items, use HTML Export to get a single HTML document. An obvious advantages of this approach is easier section / item manipulation and organisation
 
To view the formatted output:
  • Press F2 or switch to Browse mode (Ctrl + M)
  • The generated HTML can be fine-tuned using a CSS Stylesheet file. See below for details
     

Editing Markdown documents

Editing can be done using :
  • the built-in editor or,
  • an external editor
There are a large number of Markdown editor programs. Some very simple (Notepad could even be used), some very specific.
One such one is Markdown Monster which sets itself apart from the rest for these features:
  • Spell-check
  • Built-in screen shot capture
  • Paste HTML as Markdown, a.k.a. HTML to Markdown conversion
  • Publish to a Weblog
  • Themed Previews (e.g. Github)
  • Add-ins (e.g. Automatic Table of Content generation)
     
The rest of this page describes the Markdown syntax and the use of the included editor 
 

1. Headers

Headers are marked with one or more #. IQ will expand header levels so entering # 4 (no space) will be converted to #### which is a H4 header

A header (level 4)

2. Paragraphs and character formatting

Paragraphs are separated by a blank line.

Paragraphs which are not separated by a blank line are combined. So this second line will actually be shown with the previous one.

To add a carriage return, add 2 spaces at the end of the line.
So this text is now on a different line

Font attributes can be Italic, bold, and monospace. To format, enclose the text with:

  • * for italic
  • ** for bold
  • ` for monospace
  • Underline and strikethrough are possible by enclosing the text with the HTML codes (<u> … </u> and <s> … </s>)

3. Lists

To make a bullet list, add a blank line and start the list with either - or *:

  • this one
  • that one
  • the other one

or for numbered lists, start the line by 1. :

  1. first item
  2. second item
  3. third item
    To add a carriage return, add 2 spaces at the end of the line.
  4. One last item

(no need to enter the correct number for numbered list items, items will auto-increment)

To create nested lists, add 1 or more Tab character:

  • Level 1
    1. Level 2
    2. Level 2 again
  • Back to Level 1
  • One more

Hyperlinks are entered using one of:

  • the following syntax: [Link text](Link URL)
  • Insert > Hyperlink (Ctrl + K) to show the Hyperlink dialog. All the standard IQ hyperlinks are allowed:
    • Web page URL
    • Local file
    • Item or list of items
    • Grid
    • All items in a field
    • etc.
    • Details here

5. Images

Images handled like hyperlinks except that the link is preceded by !:

To insert an image, use one of:
  • ![Optional image text](Image URL)
  • Insert > Image

6. Tables

Use Insert > Table and select the number of rows and columns
 
Format is :
| | Grouping | |
| Header 1 | Header 2 | Header 3 |
| :------------ | :-----------: | -----------: |
| Line 1 | **Bold** | Cell |
| Line 2 | *Long Italic Cell* ||
  • There can be any number of header lines (2 in the above example)
  • The line below the last header is used to set cell alignment:
    • :------- for left
    • :-------: for centered
    • -------: for right
  • To merge two cells, delete the spaces between the | | (Long italic cell in the above example)

In the above example, the table would look like this:

  Grouping
Header 1 Header 2 Header 3
Line 1 Bold Cell
Line 2 Long Italic Cell

 
7. Other Formatting

Quotes

Start the line with > for quotes:

Block quotes are written like so.

They can span multiple paragraphs, if you like.

Code

Code can be formatted in 2 ways:

  • Tab (or 4 spaces) at the start of each line
  • Add ``` at the start and end of the block (easier to copy / paste code)

Tab:

Let me re-iterate ... 
for i in 1 .. 10 { do-something(i) }
 
Delimited by ```:
define foobar() {
      print "Welcome to flavor country!"; 
}
 

Footnotes

To create a footnote enter [^1]. The footnote text will be shown at the end of the document.

e.g. Here’s a footnote [1].

Definition lists

Definitions are automatically formatted. To enter a definition enter the Word on a blank line. Then for each meaning, enter : followed by a Tab and the meaning:

Word
Definition 1

Definition 2

e.g.

Apple
Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
An american computer company.
Orange
The fruit of an evergreen tree of the genus Citrus.

Again, text is indented 4 spaces. (Put a blank line between each term/definition pair to spread things out more.)

Oher codes:

  • H1 and H2 headers can be created by adding 3 or more = or -
  • Use 3 dashes for an em-dash: —
  • Use 2 dashes for ranges (ex., “it’s all in chapters 12–14”).
  • Three dots will be converted to an ellipsis: …
  • Three underscores to draw a horizontal line
  • To prevent characters from being interpreted, precede it with \. e.g. \** will not bold text but this will be bold

8. Style Sheets and other header information

The Markdown document uses the MultiMarkdown syntax which is an extension over the standard Markdown. Amongst the enhancements, the format supports a header section:

  • CSS: Full path to the style sheet file
  • Title: Document title
  • Base Header Level: X : Offsets the Header level (i.e. for 3, a # generates an H3

The CSS file is particularly useful since it allows full control over the HTML generated from the Markdown