# Markdown support

`DocNet` uses markdown files as input. The markdown is parsed with the markdown parser from topten software (called 'MarkdownDeep'). It supports the default markdown statements as well as github style code block markers and specific extensions for writing documentation, which are described below.

## Standard Markdown

The standard markdown syntax as defined by John Gruber is supported in full.

## Php Markdown Extra

MarkdownDeep supports PHP Markdown Extra. PHP Markdown Extra comes with a set of neat extensions for markdown to define e.g. tables, footnotes and more. Please see the link above for all the syntax examples. Additionally, you can look at the unit test files for MarkdownDeep in the DocNet respository at GitHub.

A couple of examples are given below

### Footnotes

MarkdownDeep supports Footnotes, which can be added through the following system: To specify a footnote marker, specify `[^1]`, which will result in:1

The actual footnote text is then specified with `[^1]:` following the text of the actual footnote. Click on the superscript `1` link above to go to the footnote rendered at the bottom of this page.

### Definition lists

To specify simple definition lists, simply do:

    Item one
    :   this is the description of item one

    Item Two
    :   this is the text of item 2

which results in:

Item one
  this is the description of item one
Item Two
  this is the text of item 2

### Tables

There's basic support for defining tables.

Specifying:

    Fruit|Color
    --|--
    Apples|Red
    Pears|Green
    Bananas|Yellow
    Bongo|Bongo... it's a strange color, do you have a minute? It's a bit like the sea, but also a bit like the beach. You know how it is... oh and a bit like the wind too? You see it? Hey! Where're you going?!

results in:

Fruit | Color
--- | ---
Apples | Red
Pears | Green
Bananas | Yellow
Bongo | Bongo... it's a strange color, do you have a minute? It's a bit like the sea, but also a bit like the beach. You know how it is... oh and a bit like the wind too? You see it? Hey! Where're you going?!

### Special attributes

DocNet supports special attributes for Links and Images. Currently this is supported on normal links/image specifications only, e.g.:

    ![id text](imageurl){.cssclass1 .cssclass2 #idvalue name=value}

which will result in:

    <img src="imageurl" alt="id text" id="idvalue" class="cssclass1 cssclass2" name="value" />

### Image rendering

By default images have no special rendering applied to them. To apply a shadow, specify '.shadowed' as css class in a special attribute specification. If you want to have an image rendered centered with a note below it, simply specify a title for the image:

    ![](mycenteredpicture.jpg "this is a picture")

will be rendered as: (xxx and yyy are the width/height values of mycenteredpicture.jpg)

    <div class="figure">
    <img src="mycenteredpicture.jpg" title="this is a picture" width="xxx" height="yyy"/>
    <p>this is a picture</p>
    </div>

All images rendered contain the width/height of the picture file included in the html.

### Abbreviations

There's also support for abbreviations, using the `<abbr>` HTML tag.

Specifying:

    *[FuBar]: F**ked Up Beyond Any Repair.

gives an abbreviation link in the following sentence: This is a test for abbreviations: FuBar.

## Highlighting code

The markdown parser has been extended with GitHub code specifications, so it's easy to specify a specific code beautifying based on a language. This feature uses the Highlight.js javascript library and most popular languages are included.

Example: to specify a codeblock as C#, append `cs` after the first ``` marker:

    var i=42;

To specify a block of text in a fixed sized font but not specify any language highlighting, specify `nohighlight` as language name:

    this is a simple <pre> block

## Linking

`Docnet` doesn't automatically transform links to markdown files by default. To enable automatic link conversion to local markdown files, please specify the `ConvertLocalLinks` option in the docnet.json file file with the value `true`. If `ConvertLocalLinks` isn't specified or set to `false`, any link to any document in your documentation has to use the url it will get in the destination folder.

Example: you want to link to the file `How to\AddEntity.md` from a page. If `ConvertLocalLinks` isn't specified or set to `false`, you have to specify in the markdown the url it will need to be in the result site, which is the link `How%20to/AddEntity.htm`. If `ConvertLocalLinks` is set to `true`, you can specify `How%20to/AddEntity.md` and DocNet will convert it to `How%20to/AddEntity.htm`.

Important!

The markdown parser also doesn't allow spaces to be present in the urls. If you need a space in the url, escape it with `%20`.

1. And this is the footnote related to the example above. ↩