Availability:Docs
Title:
Crumbs:
Description:

	Keywords: Metadata is added at the top of the document with semi-colon's
	Title: Epic's Use of Markdown and Extensions to Syntax
	Crumbs:DocumentationGuidelines
	Description:How to create new documentation source files using Epic's custom Markdown extensions.
	DoIndex:false

	[TOC (start:2 end:3)]

	[REGION:note]
	**Note:** This document is itself written using Epic's Markdown; you can [see the source here](DocumentationGuidelines\SyntaxSource).
	[/REGION]

	##Overview

	Epic's version of Markdown is based on [MarkdownSharp](http://code.google.com/p/markdownsharp/).  MarkdownSharp was based on [Markdown](http://daringfireball.net/projects/markdown/) with some of the functionality from [PHP Markdown Extra](http://michelf.com/projects/php-markdown/).

	This document is intended to be a guide to the extensions made to support Epic's functionality and what specifically from Markdown Extra is being supported.  This syntax guide is supplemental to the original [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax).

	## Epic's Functionality

	### Auto generation of Table of Contents and Headings

	The header generation is altered to include a bookmark which will be the heading with spaces removed.  To support multiple headers of same name subsequent headers will be appended with an index starting at 2.
	Generate a header list with correct indentation at the top of the document replacing the tag \[TOC\]

	By specifying \[TOC (start:HeadingStartLevel end:HeadingEndLevel)\] you can set the heading levels which will be included in the table of contents start and end are optional variables if missing then start is given a value of 1, end is given a value of 6.  The end variable must follow start if both are set.

	If the first characters of a header are !! the header will not be included in the table of contents.

	#### Markdown Syntax
		#Heading
		[TOC(start:2)]

	#### HTML Output
		<h1 id="Heading1">Heading</h1>
		<ul><li><a href="#Heading">Heading</a></ul>


	#### Results
	The table of contents at the top of this page has been generated by the method outlined here \[TOC\] (start:2 end:3)

	### Linking to bookmarks within document

	Allow user to link to headers within the document, in addition to allowing the users to place bookmarks which can be linked to within the document

	#### Markdown Syntax
		Here is an example link to a heading within the file [Auto generation of Table of Contents](#AutogenerationofTableofContents).  The header text is linked to by removing spaces in the text.  In addition if more than one header has the same name subsequent headers can be referenced by appending 2, 3 etc onto the name without spaces [Markdown Syntax 1](#MarkdownSyntax) [Markdown Syntax 2](#MarkdownSyntax2) [Markdown Syntax 3](#MarkdownSyntax3) 
		Here is an example link to a user defined bookmark within the document [Bookmark 1](#Bookmark1).
		(#Bookmark1) The bookmark text must be the first text on a line.

	#### HTML Output
		<p>Here is an example link to a heading within the file <a href="#AutogenerationofTableofContents">Auto generation of Table of Contents</a>.  The header text is linked to by removing spaces in the text.  In addition if more than one header has the same name subsequent headers can be referenced by appending 2, 3 etc onto the name without spaces <a href="#MarkdownSyntax">Markdown Syntax 1</a> <a href="#MarkdownSyntax2">Markdown Syntax 2</a> <a href="#MarkdownSyntax3">Markdown Syntax 3</a> </p>
		<p>Here is an example link to a user defined bookmark within the document <a href="#Bookmark1">Bookmark 1</a>.</p>
		<p><a id="Bookmark1"/> The bookmark text must be the first text on a line.</p>
	
	#### Results

	Here is an example link to a heading within the file [Auto generation of Table of Contents](#AutogenerationofTableofContents).  The header text is linked to by removing spaces in the text.  In addition if more than one header has the same name subsequent headers can be referenced by appending 2, 3 etc onto the name without spaces [Markdown Syntax 1](#MarkdownSyntax) [Markdown Syntax 2](#MarkdownSyntax2) [Markdown Syntax 3](#MarkdownSyntax3) 

	Here is an example link to a user defined bookmark within the document [Bookmark 1](#Bookmark1).

	(#Bookmark1) The bookmark text must be the first text on a line.

	### Linking to other pages in our documentation

	We link to other pages via relative links, if the document is in the root of the markdown folders we use \%ROOT\% to reference it.  Languages are not specified in links, the assumption is that you will link to the file of the language you are currently viewing.

	#### Markdown Syntax
		[UE4 Home](\%ROOT\%)
		[Unreal Editor User Guide](Engine/UI)

	#### HTML Output
		<a href="./../../../INT\index.html">UE4 Home</a>
		<a href="./../../../INT\Editor\index.html">Unreal Editor User Guide</a>

	#### Results
	[UE4 Home](\%ROOT\%)

	[Unreal Editor User Guide](Engine/UI)

	### Linking to local images

	We do not need to reference the image folder.  We only need to reference other paths if the image belongs to another page in the documentation, languages are not specified in the links, we try to locate the image in the language folders image directory first then default to the INT image folder.

	#### Markdown Syntax
		![Logo](Logo_Epic-New.jpg)
		![Editor Viewport](Engine/UI/LevelEditor\Viewports\viewport.png) 

	#### HTML Output
		<img alt="Logo" src="./../../../images\EpicMarkdownDocGuides\EpicMarkdownExtension\Logo_Epic-New.jpg"/>
		<img alt="Editor Viewprot" src="./../../../images\Editor\viewport.png"/>

	#### Results
	![Logo](Logo_Epic-New.jpg)

	![Editor Viewport](Engine/UI/LevelEditor\Viewports\viewport.png)

	### Image Alignment
	It was desirable to have an ability to provide some formatting instructions for images and also how they would be converted.

	*   (w: h: a: convert: type: quality: fill: ) is used after image information to indicate:
		* 	**w:** width
		*	**h:** height
		*	**a:** indicates the float style applied to the image with settings of left, right, and none
		*   **convert:** is either false or true, indicating whether an image should be compressed and/or converted to a differnt type
		*	**type:** can be one of jpg, png, gif
		*	**quality:** is the jpeg compression quality
		*	**fill:** is a #number indicating the background colour of an image if the format being convert to is jpg.
	*	The order of options is important, but each is optional and can be omitted, or the entire bracket style after the image information can be omitted.
	*   If the conversion parameters are missing then the default values in the app.config file will be used.
	*	Existing Markdown image inclusion methods Inline and Reference have both been extended to support the formatting.
	*   Floating an image to the left or right can have an undesired result that unrelated content can surround the image, for example when moving to a new section we would not want the headers to be positioned to the side of an unrelated image.  This text is in a paragraph alongside the image.  The style sheet elements are used to control when to clear float styles by specifying `clear: both;` currently headings of levels 1, 2 and hr elements will stop floating.


	#### Markdown Syntax
		This is the inline image with right ![Epic Logo](Logo_Epic-New.jpg "Here's a title")(a:right) float specified, height and width have been left blank
		This is the reference image ![Epic Logo][RefEpicLogo] with width, height, and left float.
		[RefEpicLogo]: Logo_Epic-New.jpg "Here's a title"(w:50 h:50 a:left convert:true quality:75 fill:#000000)
		This text is in a paragraph alongside the image. A special div element follows ending floating.
		[REGION:clear]
			<!-- clear float -->
		[/REGION]    
	
	#### HTML Output
		<p>This is the inline image with right <img style="float: right;" title="Here's a title" alt="Epic Logo" src="./../../../images\EpicMarkdownDocGuides\EpicMarkdownExtension\Logo_Epic-New.jpg"/> float specified, height and width have been left blank.</p>
		<p>This is the reference image <img width="50" height="50" style="float: left;" title="Here's a title" alt="Epic Logo" src="./../../../images\EpicMarkdownDocGuides\EpicMarkdownExtension\Logo_Epic-New.jpg"/> with width, height, and left float.</p>
		<p>This text is in a paragraph alongside the image. A special div element follows ending floating.</p>
		[REGION:clear]
			<!-- clear float -->
		[/REGION]
    
	#### Results
	This is the inline image with right ![Epic Logo](Logo_Epic-New.jpg "Here's a title")(a:right) float specified, height and width have been left blank.

	This is the reference image ![Epic Logo][RefEpicLogo] with width, height, and left float.

	[RefEpicLogo]: Logo_Epic-New.jpg "Here's a title"(w:50 h:50 a:left convert:true quality:75 fill:#000000)

	This text is in a paragraph alongside the image. A special div element follows ending floating.

	[REGION:clear]
		<!-- clear float -->
	[/REGION]

	### Tables
	Tables are supported the formatting available in the syntax for MultiMarkdown was very flexible and chosen to provide the basis for Epic.

	*	Colon's are used to indicate alignment of the tables data in a header row.
	*	There can be pipes at the head and tail of lines, or they can be omitted.
	*	Captions can be added.
	*	Span columns are available.
	*	Span rows are supported by using the ^ symbol in a cell


	#### Markdown Syntax
		[Table 1 - Headers to top]				    
		|             | Grouping                      ||   
		 First Header | Second Header  | Third Header  |  
		 ------------ | :------------: | ------------: |  
		 Content      |          *Long Cell*          ||  
		 Content      |      **Cell**  |         Cell  |  
		 New section  |     More       |         Data  |  
			 ^        |            And more           || 


		 ------------ | :------------: | ------------: |  
		 Content      |          *Long Cell*          ||  
		 Content      |      **Cell**  |         Cell  |  
		 New section  |     More       |         Data  |  
			 ^        |            And more           || 
	
		[Table 2 - Headers to the right]				    
		| ------------ | :------------: | ------------: |  
		|  Content      |          *Long Cell*          ||  
		|  Content      |      **Cell**  |         Cell  |  
		|  New section  |     More       |         Data  |  
		| 	 ^        |            And more           || 


	#### HTML Output

		<table>
		<caption>Table 1 - Headers to top</caption>
		<colgroup><col/>
		<col align="center"/>
		<col align="right"/>
		</colgroup><thead>
		<tr>
			<th colspan="1"/>
			<th colspan="2">Grouping</th>
		</tr>
		<tr>
			<th colspan="1">First Header</th>

			<th colspan="1">Second Header</th>
			<th colspan="1">Third Header</th>
		</tr>
		</thead>
		<tbody>
		<tr>
			<td colspan="1">Content</td>
			<td align="center" colspan="2"><em>Long Cell</em></td>
		</tr>

		<tr>
			<td colspan="1">Content</td>
			<td align="center" colspan="1"><strong>Cell</strong></td>
			<td align="right" colspan="1">Cell</td>
		</tr>
		<tr>
			<td rowspan="2" colspan="1">New section</td>
			<td align="center" colspan="1">More</td>

			<td align="right" colspan="1">Data</td>
		</tr>
		<tr>
			<td align="center" colspan="2">And more</td>
		</tr>
		</tbody>
		</table>
	
		<table>
		<caption>Table 2 - Headers to the right</caption>
		<colgroup><col/>
		<col align="center"/>
		<col align="right"/>
		</colgroup><tbody>
		<tr>
			<th colspan="1">Content</th>
			<td align="center" colspan="2"><em>Long Cell</em></td>
		</tr>
		<tr>

			<th colspan="1">Content</th>
			<td align="center" colspan="1"><strong>Cell</strong></td>
			<td align="right" colspan="1">Cell</td>
		</tr>
		<tr>
			<th rowspan="2" colspan="1">New section</th>
			<td align="center" colspan="1">More</td>

			<td align="right" colspan="1">Data</td>
		</tr>
		<tr>
			<td align="center" colspan="2">And more</td>
		</tr>
		</tbody>
		</table>	

	#### Results

	[Table 1 - Headers to top]			    
	|	          | Grouping                      ||   
	 First Header | Second Header  | Third Header  |  
	 ------------ | :-----------:  | -----------:  |  
	 Content      |          *Long Cell*          ||  
	 Content      |      **Cell**  |         Cell  |  
	 New section  |     More       |         Data  |  
		 ^        |            And more           || 

	By having no header information above the allignment row the left most column is treated as a header.

	[Table 2 - Headers to the right]
	| ------------ | :------------: | ------------: |  
	|  Content      |          *Long Cell*          ||  
	|  Content      |      **Cell**  |         Cell  |  
	|  New section  |     More       |         Data  |  
	| 	 ^        |            And more           || 

	### Metadata
	This will be implemented similar to MultiMarkdowns syntax for metadata, with the following rules.

	*	The metadata must begin at the very top of the document - no blank lines can precede it.
	*	Metadata consists of the two parts - the key and the value
	*	The metadata key must begin at the beginning of the line. It must start with a letter or number, then the following characters can consist of letters, numbers, spaces, hyphens, or underscore characters.
	*	The end of the metadata key is specified with a colon
	*	After the colon comes the metadata value, which can consist of pretty much any characters (except new lines). 
	*	After the metadata is finished, a blank line triggers the beginning of the rest of the document


	All metadata is placed in <meta name="Key" content="Value"/> html blocks in the header of the document.
	Some key's in addition to the above have special functionality.

	* Title metadata is used in the Header block `<title>Title</title>`
	* HtmlDocumentType metadata is used to define which of the templates in the include/templates folder to use for html generation.  If missing the default.html template file is used.
	* DoIndex:false tells the indexer to exclude the document from the indexes, and thus search results.  The value true is default for all documents
	* ForcePublishFiles: can be used to force publish attachements and images to the html folders.


	#### Markdown Syntax
		Keywords: Metadata is added at the top of the document with semi-colon's
		Title: This specifies the document title, however the path to the document will be used as a title if this metadata is missing.


	#### HTML Output
		<title>This specifies the document title, however the path to the document will be used as a title if this metadata is missing.</title>
		<meta name="Keywords" content="Metadata is added at the top of the document with semi-colon's" />
		<meta name="Title" content="This specifies the document title, however the path to the document will be used as a title if this metadata is missing." />

	#### Results
	You can see the documents title bar has been updated with the title meta tag.
	Viewing the document source will show the meta data in the documents head.

	### Definition Lists

	Syntax to support definition lists have been added to the conversion.  Definition lists operate with the same allignemnt and embeding rules as the markdown standard lists.

	#### Markdown Syntax
		Defintion list elements at top level:
		$ Definition 1 : Description 1
		$ Definition 2 : Description 2
			* List element 1
				1. Ordered
				1. Ordered
			* List element 2
		$ Definition 3: Description 3


		Definition list elements embeded:
		* List element 1
			$ Definition 1 : Description 1
			$ Definition 2 : Description 2
		* List element 2

	#### HTML Output

		<dl>
		<dt>Definition 1 </dt>
		<dd>Description 1</dd>
		<dt>Definition 2 </dt>
		<dd>Description 2

		<br/>
		<ul>
		<li>List element 1
		<br/>
		<ol>
		<li>Ordered</li>
		<li>Ordered</li>
		</ol></li>
		<li>List element 2</li>
		</ul></dd>
		<dt>Definition 3</dt>
		<dd>Description 3</dd>

		</dl>

		<ul>
		<li>List element 1
		<br/>
		<dl>
		<dt>Definition 1 </dt>
		<dd>Description 1</dd>
		<dt>Definition 2 </dt>
		<dd>Description 2</dd>

		</dl></li>
		<li>List element 2</li>
		</ul>

	#### Results

	Defintion list elements at top level:
	$ Definition 1 : Description 1
	$ Definition 2 : Description 2
		* List element 1
			1. Ordered
			1. Ordered
		* List element 2
	$ Definition 3: Description 3


	Definition list elements embeded:
	* List element 1
		$ Definition 1 : Description 1
		$ Definition 2 : Description 2
	* List element 2


	### Additional Backslash Escapes

	In addition to the characters that can be escaped by markdown, we also allow escaping:

		>   greater than
		|	pipe
		\%	percent

	## Markdown Extra Functions Used

	### Strict Bold Italic

	There must be spaces to the left and right of the opening and closing `_italics_` and `__bold__` syntax this is to stop the false positive detection of these when used within File_names_including_underscores.

	### Fenced Code Blocks

	#### Markdown Syntax
	`~~~`

	Code fenced by 3 or more ~ characters

	`~~~`

	#### HTML Output
		<pre class="prettyprint"><code>Code fenced by 3 or more ~ characters
		</code></pre>
	
	#### Results
	~~~
	Code fenced by 3 or more ~ characters
	~~~

	### Regions

	Regions are are basically areas that can have a style applied, i.e. a div in HTML. You can specify a region using this syntax:

		[REGION:stylename]
		...
		[/REGION]

	In HTML generation, this will be converted to:

		<div class="stylename">
		...
		</div>

	You must also create a corresponding style rule in the css file:

		.stylename
		{
			background:#123456;
			border:1px solid #654321;
		}

	#### Built-in Regions

	Some styles for regions already exist for common things like notes, tips, warnings, and quotes.

		[REGION:note]
		This is a note. It is inside a yellow box and you can see the note icon at the top left.
		[/REGION]

	[REGION:note]
	This is a note. It is inside a yellow box and you can see the note icon at the top left.
	[/REGION]

		[REGION:tip]
		This is a tip. It is inside a green box and you can see the tip icon at the top left.
		[/REGION]

	[REGION:tip]
	This is a tip. It is inside a green box and you can see the tip icon at the top left.
	[/REGION]

		[REGION:warning]
		This is a warning. It is inside a red box and you can see the warning icon at the top left.
		[/REGION]

	[REGION:warning]
	This is a warning. It is inside a red box and you can see the warning icon at the top left.
	[/REGION]

		[REGION:quote]
		This is quoted text. It is inside a blue box and you can see the quote icon at the top left.
		[/REGION]

	[REGION:quote]
	This is quoted text. It is inside a blue box and you can see the quote icon at the top left.
	[/REGION]

	### Including Files and Excerpts

	The entire contents or a subsection from one page can be included into another.

	The syntax for including an entire page is:

		[INCLUDE:Engine/Landscape]

	This will cause the full Landscape page to be converted and inserted in the page containing that line.

	Excerpts can be defined in a page using the following syntax:

		[EXCERPT:TerrainLayerCoords]
		...
		[/EXCERPT:TerrainLayerCoords]

	This excerpt can be included using this syntax:

		[INCLUDE:Engine/Landscape/Materials#TerrainLayerCoords]

	The result (shown in a quote region):

	[REGION:quote]
	[INCLUDE:Engine/Landscape/Materials#TerrainLayerCoords]
	[/REGION]