Intermediate Markup Syntax
WARNING: This specification is still being developed and
is subject to change.
Intermediate Markup Syntax (IMS) is a specification for creating text documents.
All Black Belt Coder articles are entered into our system as IMS. Articles
submitted in formats such as HTML must be manually converted to IMS before we
can use them. Proprietary software is then used to convert the IMS to HTML.
Black Belt Coder maintains a copy of both the HTML and the original IMS. Authors
wanting to update a published article should first obtain the original IMS from
us before making changes that they plan to resubmit.
Authors submitting articles to Black Belt Coder do not need to understand the
information in this article. For the most part, IMS is just plain text. But IMS
supports tags that can be used to control the final HTML.
Why was IMS Created?
IMS was not created to make things more difficult for authors by requiring them
to learn yet another syntax. For the most part, any plain text document is
IMS-compliant. Black Belt Coder is more than happy to accept quality articles
submitted as plain text.
However, some articles need more control over the final HTML. For example, an
article may contain formatted source code, or it may list data in a table. Since
any HTML formatting codes in the article would be converted to characters (for
example, "<" would be converted to "<"), IMS is used to gain any control the
author needs to format text.
How Do I Write an IMS-Compliant Document?
As previously stated, most plain text documents are already IMS-compliant. Here
are some of the basic rules.
Paragraphs are separated by two newlines (entered by pressing Enter twice at the
end of a paragraph). Lines separated by only one newline will be treated as part
of the same paragraph.
IMS tags can be used to control formatting. IMS tags begin with two open square
brackets ([[) and terminate with two closing square brackets (]]). For example,
[[hdr]]This is a Section Header[[/hdr]].
If you need double square brackets to appear within your text, write them as three square brackets ([[[). This tells the conversion software that
this is not part of an IMS tag, and two open square brackets are written to the
HTML.
IMS Tag Reference
This section decuments the syntax for all tags supported by
IMS. Note that the text that appears between an opening and closing IMS tag is
referred to as the inner text. For example, [[keyword]]This is the inner
text[[/keyword]].
IMS tags can have one or more argument.
IMS tags are delineated with double square brackets and have an opening and
closing tag just like HTML tags (for example, [[keyword]]...[[/keyword]]). Some
tags can have a colon followed by one or more arguments. Each argument is
separated by a semicolon ([[link:http://www.domain.com;Tooltip Text]]Inner Text[[/link]]).
Some tags take one or more arguments. The syntax for these arguments is the same
syntax used for defininting attributes within an HTML tag. For example,
[[tagName argumentName="argumentValue"]]. In addition, some tags support a
default attribute. Default attributes provide a shortcut and can be written as
[[tagName:argumentValue]].
[[code language="value"]...[[/code]]
Use the [[code]] tag to embed a block of source code in the article text.
The language argument specifies the language used within the code
block. For example, cs (C#), vb (VB.NET), cpp, (C++), xml (XML & HTML), etc. The
language argument is required and can be specified as a default
argument. For example, [[code:cs]]...[[/code]].
[[comment]]...[[/comment]]
The comment tag provides a
place to put notes or other information. The resulting HTML will not include any
comment tags or comment tag inner text.
If you ever request the original IMS for an article you wrote (for example, if
you want to update the article), we can provide that. And it will still include
any comment blocks that were part of the original submission.
[[hdr]]...[[/hdr]]
This defines header text, similar to the <h1> in HTML. Only one level of header is
supported.
This tag can also be shortened to [[h]]...[[/h]].
[[html]]...[[/html]]
Use this tag if you want to embed raw HTML within your article. The conversion
software will copy the contents inside this tag to the HTML document without
change.
In general, we prefer not to use this tag in our articles. Use this tag when you absolutely, positively need to directly
control the HTML in part of your article.
[[image url="value" navigateurl="value" tooltip="value"]]
Use the [[image]] tag to display a graphic in your article.
The url argument specifies the address of the image to be displayed.
The url argument is required and can be specified as a default
argument. For example, [[image:logo.jpg]].
The navigateurl argument specifies an address to navigate to if the
image is clicked. This argument is optional. Use it to turn the image into a
hyperlink.
The tooltip argument specifies text that appears in a pop-up balloon
when the user hovers the mouse over the image. This argument is optional.
[[keyword]]...[[/keyword]]
Use the [[keyword]] tag to indicate a word within your text represents a symbol
or keyword from your code. For example, you might write text something like: After initialization, the code
then calls the [[keyword]]Run()[[/keyword]] method.
[[link url="value" tooltip="value"]]...[[/link]]
Use the [[link]] tag to insert a hyperlink in your text. The inner text will be
the visible link text.
The url argument specifies the address to navigate to if the link is
clicked. The url argument is required and can be specified as a default
argument. For example, [[link:http://www.blackbeltcoder.com]]...[[/link]].
The tooltip argument specifies text that appears in a pop-up balloon
when the user hovers the mouse over the image. This argument is optional.
[[meta]]...[[/meta]]
The [[meta]] tag is a special tag used to contain meta information for the
article such as the title, description, keywords, author's email, etc. Once
this tag is processed by Black Belt Coder, it is stripped from the IMS.
To see an example of the data expected within this tag, please download our
article template.
All Other Tags
Any other tag not specifically supported by the IMS parser will simply be
converted into an HTML tag. For example [[table width="100%"]]...[[/table]] would translate
into <table width="100%">...</table>.