Using Templates

Templates can be used in the articles when there is content that is commonly repeated in multiple documents. It ease the support of our documentation.

Quick navigation:

• In-article Syntax
• Creating Templates
• Using Arguments
• Reusing Templates
• Examples
• Good Practices

In-article Syntax

The plugin will capture the following syntax and replace it with the corresponding template:

Example 1: In-article Template syntax.

@[template - info](/path/to/file.md#template_id "argument: value")

You can break it into five parts:

1. @[template—indicates that this will be rendered from a template;
2. - info]—(optional) small description;
3. (/path/to/file.md—indicates in which file the template is located;
4. #template_id—indicates the section of the exact template to be put;
5. "argument: value")—(optional) arguments which to be replaced later in the generated content.

The syntax follows the native Markdown syntax for link. By that, in GitHub, a link to the template is rendered.

Creating Templates

The template files are located in the _template folder of ajax-docs repo. Inside this folder, new template files can be put in any folder structure that is required.

Creating a template also follows the Markdown specification and syntax.

Example 2: Syntax for creating templates.

#section-id
You can write here plain Markdown.
#end

Using Arguments

With the templates you can also use arguments in order to change the contents of the generated Markdown according to the context of the article.

Example 3: Using arguments

the-article.md

@[template](/_templates/template.md#template-1 "control: RadControl, version: Q1 2016")

template.md

#template-1
As of **@{version}** **@{control}** exposes this new feature.  
#end

With the build of the documentation, the setup from Example 3 will generate the following Markdown:

Example 4: The result of Example 3

As of **Q1 2016** **RadControl** exposes this new feature.  
```

## Reusing Templates 

There are cases where the template should be quite different in terms of Markdown contents. For such cases you can reuse templates (i.e., nest them inside other templates).

For example, you have two text instances that are the same and the only difference is that some piece of text should be linked only in one article. You can use a template as a base, and create two more to extend the base and use it in the articles. 

> Example 5: Reusing templates

**article-1.md**

@template

**article-2.md**

@template

**template.md**

#base This new control exposes #end

#text @template Lightweight rendering.

#text-with-link @template [Lightweight rendering]({%slug slug/link%}).

And the following Markdown will be generated for the two articles:

> Example 6: The results from Example 5

**article-1.md**

This new control exposes Lightweight rendering.

**article-2.md**

This new control exposes [Lightweight rendering]({%slug slug/link%}).

## Examples

You can find here real life examples of templates used in our documentation:

* Reusing templates ([see commit](https://github.com/telerik/ajax-docs/commit/a9a7dbb51c94806872018f7a44721379767cc7c5)):
    * The template file: [wai-aria-templates.md](https://github.com/telerik/ajax-docs/blob/master/_templates/common/wai-aria-templates.md);
    * Checkbox - [wai-aria-support.md](https://github.com/telerik/ajax-docs/blob/master/controls/checkbox/accessibility-and-internationalization/wai-aria-support.md)
    * DropDownList - [wai-aria-support.md](https://github.com/telerik/ajax-docs/blob/master/controls/dropdownlist/accessibility-and-internationalization/wai-aria-support.md)
    * Editor - [wai-aria-support.md](https://github.com/telerik/ajax-docs/blob/master/controls/editor/accessibility-and-internationalization/standards-compliance/wai-aria-support.md)
    * RadWindow - [wai-aria-support.md](https://github.com/telerik/ajax-docs/blob/master/controls/window/accessibility-and-internationalization/wai-aria-support.md)

## Good Practices 

* Although you can add info in `@[template]` keep it as short as possible. If you tend to write long info consider adding description in HTML comments. It will be easier to read. 

* [Liquid tags](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers) are supported in the templates' content. If a certain template should use large amount of arguments, consider using [Liquid variables](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers#variable-assignment) to shorten the Template declaration in the article's markup.