Markdown Syntax

Basics

The content files for all docs-seed product documentations are written in Markdown. For more information and examples on using the exact Markdown syntax rules, go to 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.

In the custom syntax, always use camelCase for the [name].

The code snippets ar edifferently defined. They are generated by using ````[language]. For more information, go to the Code Snippet section.

Alerts

Alerts notify the reader about something important.

The supported alerts are of the following types:

• 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: An 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: An alert with a paragraph 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 a caption, use >caption and write a line of text.

• Captions support only a single line of text.
• By definition, captions are placed before the element they describe.

Example 3: Sample caption syntax

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

Code Snippets

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

Indentation will be rendered as it is, so it is important to format the displayed code.

Example 4: Generating a single code snippet

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

Tabbed Code Snippets

To render code snippets in a tab-strip, list them as plain code snippets, without empty lines between them. An empty line acts as a delimiter that indicates that this is the last code snippet that will be added.

Example 5 shows how to generate code snippets in a tab-strip.

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 shows how the last code snippet will not be added to the tab-strip because of the empty line.

Example 6: Using an empty line as a delimiter to create a code snippet outside the 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)

We regard as an internal article each page that is part of the Telerik product documentation, for example, all pages from the Telerik UI for ASP.NET AJAX website documentation.

Every internal article has a slug meta tag defined in its YAML configuration section (or front meter). Slugs can be used only when they point to internal articles. For links to external sources, use the standard Markdown syntax for links. 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—for example, splitter/getting-started/overview or introduction/installation/included-assemblies.

Example 7: Slug attribute

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

However, sometimes we may have deeply nested articles and, therefore, very long slugs. That is why you may consider an alternative approach for providing shorter slug values, for example, slug: overview-splitter.

Whatever the approach, keep it consistent across the respective product documentation. If you go for the shorter approach to name your slugs, do it for all articles across the product documentation. If you use the path approach, stick to it for each documentation topic within the product documentation.

To add a slug link to this article, use the {%slug [article's slug]%} custom Liquid tag. For example, to link the Overview article from the Getting Started section of the Splitter (from Example 7), use the following syntax:

Example 8: Using slug values to link internal articles

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

On the docs website, this will generate a link with a URL leading to the corresponding article.