Markdown Syntax

Basics

The content files for the Telerik UI for ASP.NET AJAX documentation are written in Markdown. Exact syntax rules and examples for how to use Markdown are available here—daringfireball.net/projects/markdown/.

Custom Syntax

Most of the custom elements are based on the blockquote syntax in Markdown. Therefore, the >[name] pattern renders HTML that is custom and the actual result will be visible only by running the local Jekyll site.

Important: Always use camelCase for the [name] in the custom syntax.

Differently defined are the code snippets, which are generated using ````[language]. You can examine the Code Snippet section.

Alerts

Alerts are used to notify the reader for something important. There are 5 types of different alerts:

• Tip
• Important
• Caution
• Warning
• Note

The type of the alert corresponds to its name. For example, >tip will create an alert of type Tip, >warning will be of type Warning.

Example 1: Alert with multiple paragraphs.

>caution This is an alert of type caution,
here the first paragraph stops. 
>
End here begins the second one.

Example 2: Alert with a paragraphs and a list.

>important This is the first paragraph.
>
* list item 1
* list item 2
>
And a second paragraph.

Captions

Captions are used as titles for tables, images, single code snippets and tabbed code snippets. To create them you can use >caption and write a line of text.

Note: Captions support only one line of text.

Important: By definition, they should be put above the element that they describe.

Example 3: Caption syntax

>caption This should the description of an image, table or code example.

Code Snippets

To generate a code snippet you can use four backtick quotes followed by the language used in the snippet.

Note: Indentation will be rendered as it is, so it is important to format the code used.

Example 4: Generating a single code snippet

````JavaScript
var oWin = #find("<%= RadWindow1.ClientId %>")
````

Tabbed Code Snippets

To indicated that certain code snippets should be in a tab-strip, you should list them as plain code snippets, without new lines between them. The new line is a delimiter that indicates which is the last code snippet to be added. In Example 5, you can see how to generate code snippets in a tab-strip. And in Example 6, you can see how the last code snippet will not be added into the tab-strip, because of the new line.

Example 5: Creating code snippets in a tab-strip

````ASP.NET
<telerik:RadButton runat="server" ID="RadButton1" OnClientClicking="OnClientClicking">
</telerik:RadButton>
````
````JavaScript
function OnClientClicking(sender,args){
	// some code to add ...
}
````

Example 6: Using new line, as delimiter to create code snippet outside tab-strip

````ASP.NET
<telerik:RadButton runat="server" ID="RadButton1" OnClientClicking="OnClientClicking">
</telerik:RadButton>
````
````JavaScript
function OnClientClicking(sender, args){
	// some code to add ...
}
````
    
````CSS
.RadButton{
    /* css rules */
}
````

Linking Internal Articles (Working with Slugs)

Link to internal documents can be used only for Markdown documents existing only in the ajax-docs repository.

Every article has a slug tag in its YAML configuration section.

Example 7: Slug attribute

---
slug: splitter/getting-started/overview
---

The slug value is unique and it is manually added to each article. The convention is to use values that represent the path to the MD file—e.g., splitter/getting-started/overview or introduction/installation/included-assemblies.

To add a link to this article, a custom Liquid tag is used—{%slug [article's slug]%}. For example to link the Splitter's Getting-started Overview article (from Example 7), you should use the following syntax:

Example 8: Using slug values to link internal articles

[Getting-started Overview]({%slug splitter/getting-started/overview%})

This will generate a link with a URL leading to the corresponding article.