Mathjax javascript librry setup

# Introduction

## Many Flavours of Markdown

There are many variants of Markdown formats, and each processor may support a range of extensions, and interpret the Markdown specifications in somwhat different ways. The main formats include:

## Markdown Processors

There are also many different Markdown processors, each with their own quirks. See the section Other Markdown Processors and Formats for details.

I selected Pandoc as my markdown converter, because it supports tables and a number of advanced features, as well as the generation of pdf files via Latex, and a number of other file formats as well. I wanted to use a single processor as much as possible to avoid issues with differences in markdown syntax and features supported by different processors.

# Markdown Formatting Cheat Sheet

See Pandoc Documentation for the detailed users guide for Pandoc Markdown formats and processing.

## Paragraphs

• A paragraph is one or more lines of text followed by one or more blank lines.
• Newlines are treated as spaces
• For a hard line break, put either two or more spaces or a backslash at the end of a line.

• Pandoc requires a blank line before a header. (Markdown does not)
• Headers can contain in-line formattong, such as emphasis and links
Markdown Result
A level-one header
==================

# A level-one header

A level-two header
------------------

## A level-two header

Markdown Result

# A level-one header #

# A level-one header

## A level-two header ##

## A level-two header

### A level-three header ###

### A level-three header

#### A level-four header ####

#### A level-four header

##### A level-five header #####

##### A level-five header

###### A level-six header ######

###### A level-six header

Regular Body Test

Regular Body Text

Headers can be assigned attributes using this syntax at the end of the line containing the header text: {#identifier .class .class key=value key=value}

Indentifers can be used to provide links from one section of a document to another. For example, we defined an identifer: # Markdown Formatting Cheat Sheet # {#formatting-cheatsheet} so:

Using Identifiers to link to sections within a document
Markdown Result

See the section [Markdown Formatting Cheat Sheet](#formatting-cheatsheet)

See the section Markdown Formatting Cheat Sheet

See the section [Markdown Formatting Cheat Sheet]

See the section Markdown Formatting Cheat Sheet

[See the section Markdown Formatting Cheat Sheet][Markdown Formatting Cheat Sheet] |

See the section Markdown Formatting Cheat Sheet

The latter rows work becuase Pandoc behaves as if reference links have been defined for each header. See the section on Links for details of reference links

## In Line Formatting

Basic Text Formatting
Markdown Result
_emphasis_ or *emphasis* emphasis or emphasis
__strong emphasis__ or **strong emphasis** strong emphasis or strong emphasis
~~strikeout~~ strikeout
H~2~O - subscript H2O - subscript
2^10^ - superscript 210 - superscript
verbatim text, not formatted verbatim text, not formatted
Regular Body Text Regular body text
• Pandoc does not treat a _ surrounded by alphanumeric characters as an emphasis marker. If you want to emphasise part of a work use * instead
• A \ will cause the following character to be treated literally
• A backslash-escaped space is parsed as a nonbreaking space
• If a verbatim text includes a backtick, use double backticks:
• The verbatim rule is that “a verbatim span starts with a string of consecutive backticks (optionally followed by a space) and ends with a string of the same number of backticks (optionally preceded by a space).”
• Attributes can be attached to verbatim text, just as with fenced code blocks: <>{.haskell} • Pandoc’s superscripts and subscripts work for HTML output, but it fails PDF generation. I had to add \usepackage{fixltx2e} to the front of my Latex template to get it to work. • Horizontal Rules: A line containing a row of three or more *, -, or _ characters (optionally separated by spaces) produces a horizontal rule. ## Lists ### Bulleted and Ordered Lists • A bulleted list item begins with a bullet (*, +, or -). The bullet must be followed by a space • A list must styart with a blank line, except sub-lists. • The “4 space rule”: A list item may contain multiple paragraphs and other block-level content. However, subsequent paragraphs must be preceded by a blank line and indented four spaces or a tab. The list will look better if the first paragraph is aligned with the rest: • List items may include other lists. In this case the preceding blank line is optional. The nested list must be indented four spaces or one tab: Bullet Lists Markdown Result A simple compact list: * one * two * three A simple compact list • one • two • three A simple “loose” list, with each list item formatted as a paragraph * one * two * three A simple “loose” list, with each list item formatted as a paragraph • one • two • three A more complex list * fruits - apples - macintosh - red delicious - pears - peaches * vegtables - brocolli - chard A more complex list • fruits • apples • macintosh • red delicious • pears • peaches • vegtables • brocolli • chard • Ordered lists work just like bulleted lists, except that the items begin with enumerators rather than bullets. • Enumerators are decimal numbers followed by a period and a space. The numbers themselves are ignored. (Standard Masrkdown) • Fancy Lists: Ordered list items to be marked with uppercase and lowercase letters and roman numerals, in addition to arabic numerals. List markers may be enclosed in parentheses or followed by a single right-parentheses or period. They must be separated from the text that follows by at least one space, and, if the list marker is a capital letter with a period, by at least two spaces (Pandoc Extension) • Startnum: Pandoc also pays attention to the type of list marker used, and to the starting number, and both of these are preserved where possible in the output format. (Pandoc Extension) Ordered Lists Markdown Result 1. one 7. two 4. three 1. one 2. two 3. three This is a fancy list with starting numbers.  9) Ninth 10) Tenth 11) Eleventh ii. subone iii. subtwo iv. subthree This is a fancy list with starting numbers 1. Ninth 2. Tenth 3. Eleventh 1. subone 2. subtwo 3. subthree ### Definition Lists • Each term must fit on one line, which may optionally be followed by a blank line, and must be followed by one or more definitions. • A definition begins with a colon or tilde, which may be indented one or two spaces. • The body of the definition (including the first line, aside from the colon or tilde) should be indented four spaces. A term may have multiple definitions, and each definition may consist of one or more block elements (paragraph, code block, list, etc.), each indented four spaces or one tab stop. • If you leave space after the definition, the blocks of the definitions will be considered paragraphs. • For a compact definition list, do not leave space between the definition and the next term: Definition Lists Markdown Result This is an example of a definition list Term 1 : Definition 1 Term 2 with *inline markup* : Definition 2 { some code, part of Definition 2 } Third paragraph of definition 2. This is an example of a definition list Term 1 Definition 1 Term 2 with inline markup Definition 2 { some code, part of Definition 2 } Third paragraph of definition 2. Here is another example, to show the formatting Sailboat : A hole in the water into which one pours money : A challenging, relaxing, enjoyable world of possibilities Car : A pollutor that just loses its value : Can get you where you want to go Here is another example, to show the formatting Sailboat A hole in the water into which one pours money A challenging, relaxing, enjoyable world of possibilities Car A pollutor that just loses its value Can get you where you want to go ### Numbered Example Lists • The special list marker @ can be used for sequentially numbered examples throughout a whole document • The first list item with a @ marker will be numbered ‘1’, the next ‘2’, and so on. • Numbered examples can be labeled with any alphanumber string and referred to elsewhere in the document Numbered Example Lists Markdown Result (@1st) My first example will be numbered (1). some stuff here (@2nd) My second example will be numbered (2). and some more stuff here. (@3rd) My third example will be numbered (3). As (@1st) illustrates, its different from (@3rd) 1. My first example will be numbered (1). some stuff here. 1. My second example will be numbered (2). and some more stuff here. 1. My third example will be numbered (3). As (1) illustrates, its different from (3) ### List Quirks and Gotchas • Consider the example: + First + Second: - Fee - Fie - Foe + Third • Pandoc follows a simple rule: if the text is followed by a blank line, it is treated as a paragraph. Since “Second” is followed by a list, and not a blank line, it isn’t treated as a paragraph. The fact that the list is followed by a blank line is irrelevant. • If you need to explicitly end a list, put in an html comment: - item one - item two <!-- end of list --> { my code block } 1. one 2. two 3. three <!-- end of list --> 1. uno 2. dos 3. tres ### Auto-Linking • If you enclose a URL or email address in pointy brackets, it will become a link: Automatic Links Markdown Result <http://google.com> http://google.com <sam@green.eggs.ham> • An inline link consists of the link text in square brackets, followed by the URL in parentheses. • Optionally, the URL can be followed by a link title, in quotes. But in the example below, when I try to put a libk title in quotes within a table, Pandoc generates the HTML fint, but it fails when tryiong to generate a PDF file from the Latex output. • The link text can contain formatting (such as emphasis) In-Line Links Markdown Result [Google](http://google.com) Google [_FSF_](http://fsf.org) FSF • An explicit reference link has two parts, the link itself and the link definition, which may occur elsewhere in the document (either before or after the link). • The link itself consists of link text in square brackets, followed by a label in square brackets. • The link definition consists of the bracketed label, followed by a colon and a space, followed by the URL, and optionally (after a space) a link title either in quotes or in parentheses. • Note that link labels are not case sensitive • Sample link definitions: [my label 1]: http://google.com "My title, optional" [my label 2]: /foo [my label 3]: http://fsf.org (The free software foundation) [my label 4]: /bar#special 'A title in single quotes' [my label 5]: <http://foo.bar.baz> Reference Link Usage (Explicit and Implicit) Markdown Reference Links Result [FSF][my label 3] FSF [Google][my label 1] Google [my label 1] my label 1 [my label 3][] my label 3 • See the section Header Identifiers for how to create links to other sections of the same document ### Footnotes • The identifiers in footnote references may not contain spaces, tabs, or newlines • The identifiers are used only to correlate the footnote reference with the note itself; in the output, footnotes will be numbered sequentially. • The footnotes themselves need not be placed at the end of the document. They may appear anywhere except inside other block elements (lists, block quotes, tables, etc.). • The example in the Pandoc User Guide whichb includes an indented code block of the form { some.code } generates HTML OK, but but it fails when tryiong to generate a PDF file from the Latex output. • Sample footnaotes syntax: Here is a footnote reference,[^1] and another.[^longnote] [^1]: Here is the footnote. [^longnote]: Here's one with multiple blocks. Subsequent paragraphs are indented to show that they belong to the previous footnote. The whole paragraph can be indented, or just the first line. In this way, multi-paragraph footnotes work like multi-paragraph list items. This paragraph won't be part of the note, because it isn't indented. • results in: Here is a footnote reference,1 and another.2 This paragraph won’t be part of the note, because it isn’t indented. • Inline footnotes are also allowed (though, unlike regular notes, they cannot contain multiple paragraphs). The syntax is as follows: Here is an inline note.^[Inlines notes are easier to write, since you don't have to pick an identifier and move down to type the note.] Here is an inline note.3 ## Images • A link immediately preceded by a ! will be treated as an image. The link text will be used as the image’s alt text • When processing the example text, Pandoc generates the HTML, but fails when generating the PDF from Latex if the link includes any link text. • An image occurring by itself in a paragraph will be rendered as a figure with a caption. • You have to be careful about where you place your images. The generated html makes a URL from the image location, but the generated Latex needs a directory path to the image. This can cause the PDF generation to fail. My solution to this problem is to: • Only use images that are the same directory as the markdown source file, or a subdirectory. • cd to the directory the markdown source is in before calling pandoc • Enter the image file location as relative to the directory the markdown source file is in • In the PDF output, latex will use any pixels/inch sizing information in the image to size it accurately for the page (you can’t enter width and height information in the markdown like you can in html). So make sure the sizing information is included in the image so its gets formatted properly for the pdf page. ![My Logo](bicycle-icon3-114x114.png) • If you just want a regular inline image, just make sure it is not the only thing in the paragraph. One way to do this is to insert a nonbreaking space after the image. This is the Sublime Text Icon ![Sublime Text](sublime_text.png) here. This is the Sublime Text Icon is here. ## Tables Since I use Sublime Text 2 for text editing, I make use of the excellent Table Editor package. This means I need to use table formats that are supported by both Pandoc and Table Editor. Refer to the Table Editor Cheat Sheet for the Table Editor commands. ### Table Types Pandoc Table Editor Notes Pipe Simple Table Column alignment is not supprted by Pandoc Pipe Pandoc Column alignment is not supprted by Pandoc Pipe - emacs org mode EmacsOrgMode Column alignment is not supprted by Pandoc Pipe Markdown Use : on header row to indicate column alinment. The cells of pipe tables cannot contain block elements like paragraphs and lists, and cannot span multiple lines. The syntax is the same as in PHP markdown extra Grid No name Table editor supports this form of table but does not give it a name. Pandoc does not support alignments , or cells that span multiple columns or rows. The cells of grid tables may contain arbitrary block elements (multiple paragraphs, code blocks, lists, etc.) Simple Table, Multi-Line Table Not Supported These tables are not supported at all by the table editor ### Simple Table (Table Editor Definition) The Sublime Text 2 Table Editor Plugin’s simple table looks like the following. Pandoc supports this form: This is a Simple Table Name Phone Bill Bourne +1 (613) 555-1234 Sarah Bourne +1 (617) 555-1234 ### Pandoc Table (aka Grid Table) ST2’s Table Editor Plugin’s Pandoc table looks like the following. Pandoc supports this form, but justification is not supported. This is a Pandoc Table First Header Second Header Content Cell Content Cell Content Cell Content Cell Another Cell Last Cell # Unicode Characters Pandoc renders Unicode characters properly in HTML, but not in PDF. I have not figured out what the issue is yet. Unicode UTF-8 Result Name of Character U+2318 E2 8C 98 PLACE OF INTEREST SIGN U+2325 E2 8C A5 OPTION KEY U+21E7 E2 87 A7 UPWARDS WHITE ARROW (Shift) U+21EA E2 87 AA UPWARDS WHITE ARROW FROM BAR (Caps Lock) U+2303 E2 8C 83 UP ARROWHEAD (Ctrl) U+232B E2 8C AB ERASE TO THE LEFT (Delete) U+F8FF EF A3 BF Apple Symbol U+21A9 E2 86 A9 LEFTWARDS ARROW WITH HOOK (Return) U+00AE C2 AE ® REGISTERED SIGN U+00A9 C2 A9 © COPYRIGHT SIGN U+2122 E2 84 A2 TRADE MARK SIGN U+2103 E2 84 83 DEGREE CELSIUS U+2109 E2 84 89 DEGREE FAHRENHEIT # Inlining of Native Output Code ## Using TeX Expressions $\TeX$ expressions can be placed between dollar signs - eg. \TeX\$. This allows us to print $\TeX$ symbols.

A detailed list of $\TeX$ symbols can be found at:

Useful Symbols:

• \textcopyright

## Math using MathJax

Pandoc supports typsetting math for HTML output using a number of different mechanisms. The one I am using here is MathJax. See also Octopress with MathJax

$R_{ab} - {\textstyle 1 \over 2}R\,g_{ab} + \Lambda\ g_{ab} = \kappa\, T_{ab}$ $\forall x, y : \mathbb{Z}, x > 3 \land y < 2 \Rightarrow x^2 - 2y > 5$

# Other Markdown Processors and Formats

There are many flavours of Markdown, each with its own characteristics. My requirements included the ability to support tables, and the ability to generate PDF files as well as html.

Major Markdown processors, and the variants of Markdown they support include:

• Pandoc

• Supported by OctoPress & Jekyll via a Jekyll plug-in Jekyll Pandoc Plugin
• Written in Haskell. May be slow for large sites
• Supports an enhanced Markdown inspired by, but not identical to, markdown extensions in PHP markdown Extra package](http://michelf.ca/projects/php-markdown/extra/) and Maruku

• Converts to many file formats:

• Converts from the following source file formats:

• Considered the “swiss army knife” of documents conversation, given the large number of formats, and the large number of conversion and formatting options it supports.

• Kramdown

• Red Carpet

• Maruku

• Supported by OctoPress and Jekyll
• Supports an extended version of Markdown.
• RDiscount

• Supported by OctoPress and Jekyll
• A Ruby wrapper on the Discount Markdown processor written in C
• Supposed to be very fast

1. Here is the footnote.

2. Here’s one with multiple blocks.

Subsequent paragraphs are indented to show that they belong to the previous footnote.

The whole paragraph can be indented, or just the first line. In this way, multi-paragraph footnotes work like multi-paragraph list items.

3. Inlines notes are easier to write, since you don’t have to pick an identifier and move down to type the note.