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.
The following example 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 ...
}
````
The following example 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 or 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.