Using Templates

In articles, you can use templates for commonly repeated content in multiple documents. Templates ease the support of the documentation.

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 the code line into the following parts:

1. @[template—Indicates that this will be rendered from a template.
2. (Optional) - info]—A short description.
3. (/path/to/file.md—Indicates in which file the template is located.
4. #template_id—Indicates the section of the exact template that will be used.
5. (Optional) "argument: value")—Arguments that will be replaced later in the generated content.

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

Creating Templates

Place the template files in a _template folder of the docs repo. Inside this folder, you can create an inner folder structure and place new template files whenever 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 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 building 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 

Sometimes the template has to be quite different in terms of Markdown contents. For such cases you can reuse templates (that is, 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 has to be linked only in one article. You can use a template as a base, and create two more to extend the base and use them 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%}).

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

Real-life examples of templates in the Telerik 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 more information in `@[template]`, keep the content as short as possible. If you tend to write long pieces of information, consider adding a description in HTML comments. It will be easier to read. 

* The templates support [Liquid tags](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers). If a certain template has to use a large number of arguments, consider using [Liquid variables](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers#variable-assignment) to shorten the Template declaration in the markup of the article.