-
Notifications
You must be signed in to change notification settings - Fork 0
Style Guide
This guide includes a few short notes to help you as you write for Ignite UI. Click here for a blank sample topic for you to use as the basis for your writing.
Ignite UI help uses Markdown (specifically GitHub flavored Markdown or GFM) for the help topics with a few considerations:
Every file must begin with a comment-based metadata header that includes the file name, the associated control and any keywords used for indexing the search.
<!--
|metadata|
{
"fileName": "",
"controlName": [],
"tags": []
}
|metadata|
-->
Note: If your document is in AsciiDoc, the metadata is formatted with AsciiDoc comments like this:
////
|metadata|
{
"fileName": "",
"controlName": [],
"tags": []
}
|metadata|
////
Each topic must have a single top-level title prefixed by a single #. All other titles must use multiple #'s that represent the title level.
Note: Do not use titles with a series of
=signs beneath the text. The only supported title format in the help is the#type.
Markdown supports two different ways of handling code, indentation and fenced code blocks. The Ignite UI help only supports fenced code blocks.
There are a few (localized) variables that you can use in your topics in order to avoid hard coding ever-changing URLs, version or language-based information into the documents.
| Variable | Description | Example |
|---|---|---|
| %%jQueryApiUrl%% | jQuery API root link | help.infragistics.com/jQuery/2014.2 |
| %%SamplesUrl%% | Represents the root URL for the samples browser | www.igniteui.com |
| %%ProductVersion%% | The product version | 2014.2 |
| %%ProductVersionShort%% | Represents the short product version number | 14.2, 15.1, etc. |
| %%ProductVersionFull%% | Long product version string | 2014 Volume 2 |
| %%InstallPath%% | Common product install path | C:\Program Files (x86)\Infragistics\2015.1\Ignite UI |
| %%PlatformName%% | Platform name (Used in x-platform topics) | jQuery |
| %%ProductName%% | Product name (Used in x-platform topics) | Ignite UI |
When you want to make a "note" use the > character to separate out the text. For instance:
Note: This is a note.
The built-in GitHub editor is pretty good all around, can display topic images and generally give really good representation of the results. It does, however, struggle with inline Markdown (links and images) inside block HTML (e.g. tables).
Another online alternative is the Live (Github-flavored) Markdown Editor.
If you use Atom it comes with Markdown support and live preview package that does handle GFM and just about anything encountered in the docs. Also uses the marked parser.
If you like Brackets you can install the Markdown plugin.
MarkdownPad is free and includes a live preview pane, while it doesn't handle GFM (tables or code blocks) it does support rich text editing and shortcuts (ctrl+b for bold or ctrl+k for code).
Tip: Whichever editor you decide on, beware - some downloaded/saved files are encoded as 'UTF-8 without BOM' and full UTF-8 is required, so make sure you change encoding in something like Notepad++.
Here are a few example topics written in GFM that may helpful as you write: