-
Notifications
You must be signed in to change notification settings - Fork 289
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.
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:
-
@[template
—indicates that this will be rendered from a template; -
- info]
—(optional) small description; -
(/path/to/file.md
—indicates in which file the template is located; -
#template_id
—indicates the section of the exact template to be put; -
"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.
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
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**
**article-2.md**
**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%}).
## 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://docs.shopify.com/themes/liquid-documentation/basics) are supported in the templates' content. If a certain template should use large amount of arguments, consider using [Liquid variables](https://docs.shopify.com/themes/liquid-documentation/tags/variable-tags) to shorten the Template declaration in the article's markup.
- Home
- Getting Started
- Deploying Documentation on IIS
- Git and GitHub Workflow
- Handling Redirects (link to the docs-seed wiki)
- Markdown Syntax (link to the docs-seed wiki)
- Markdown Nesting (link to the docs-seed wiki)
- Using Templates (link to the docs-seed wiki)
- Using Git and Git Bash
- Faster Jekyll Build via generate_exclude.rb Script
- Using Helper Tools
- Troubleshooting
- Use VS Diff tool with Git and SourceTree