Concordion Markdown Grammar

Since: Concordion 2.0.0

With the Markdown extension, Concordion commands are expressed using Markdown links, for example:

[value](- "command")

This format separates the instrumentation (command) from the specification (value). When viewed with a Markdown editor only the specification is shown, with the instrumentation displayed as a title when you hover over the value. The URL has to be set to -, otherwise it will be treated as a normal Markdown link.

The Markdown extension converts the Markdown to XHTML, with the instrumentation as attributes, prior to running Concordion with the XHTML format specification as input.

This specification describes the grammar for the Markdown instrumentation and checks that it generates correctly formatted instrumentation in XHTML.

Link Styles

The extension supports both inline links and reference links.

In both styles, the text value is delimited by square brackets.

Inline Links

Inline links have a set of regular parentheses immediately after the link text’s closing square bracket. Inside the parentheses are a - for the URL followed by a space followed by the command, surrounded in quotes (either single or double quotes are allowed). For example:

Reference Links

As an alternative to inline links, reference links can be used. This can help make the Markdown source more readable, especially for table headers or lengthy commands.

Reference links have a set of square brackets immediately after the link text’s closing square bracket. The link definition can then be placed anywhere in the document. See the Markdown syntax page for more details.

If the link text is the same as the link name, you can use implicit links:

Commands

• assert-equals
• example
• execute
• run
• set
• verify-rows

Expression-only commands

Some commands only require an expression and don't need a text value to be passed. However, Markdown links always require link text.

Any text value that starts with italics will be set to an empty text value in the output specification.

Arbitrary Commands

Any Concordion command can be included in the title of the Markdown link by using the prefix c:.

Note that, unlike HTML format specifications, the expression is not enclosed in additional quotes. Neither are the value of any additional parameters passed to the command.

[value](- "c:command=expression")              
        

[value](- "c:command=expression param=x")              
        

[value](- "c:command=expression param1=x param2=y")              
        

Embedding HTML

For cases where the Markdown syntax is too restrictive, you can inline HTML.

This can be used to embed Concordion structures that are not currently supported by the Markdown syntax.

The execute on a list command can be implemented using the HTML list structure, wrapped in a <div> element. For example:

<div>
    <ol concordion:execute="parseNode(#TEXT, #LEVEL)">
        <li>Europe</li>
        <ul>
            <li>Austria</li>
            <ol>
                <li>Vienna</li>
            </ol>
            <li>UK</li>
            <ul>
                <li>England</li>
                <li>Scotland</li>
            </ul>
            <li>France</li>
        </ul>
        <li>Australia</li>
    </ol>
</div>

Handling unusual sentence structures

In order to handle unusual sentence structures, Concordion allows you to use an execute command on an outer HTML element. When using Markdown, this can be implemented using the HTML structure wrapped in a <div>.

<div>
    <p concordion:execute="#greeting = greetingFor(#firstName)">
        The greeting "<span concordion:assertEquals="#greeting">Hello Bob!</span>"
        should be given to user <span concordion:set="#firstName">Bob</span>
        when he logs in.
    </p>
</div>

Non-Concordion links

The set, assert-equals and execute commands require the link URL to be set to -. Links with other URLs are not modified. For example:

Support for Concordion commands in other namespaces, eg extensions

In order to include Concordion commands with namespaces other than the default Concordion namespaces, such as those available in extensions, you must declare the namespace.

Add the @ConcordionOptions annotation to the fixture class, with the declareNamespaces element set to a list of strings, where the values alternate between namespace prefixes and the namespace they are mapped to. For example:

@RunWith(ConcordionRunner.class)
@ConcordionOptions(declareNamespaces={"ext", "urn:concordion-extensions:2010"})
public class MyFixture

The namespaced command can then be included in the title of the Markdown link, using the prefix declared in the annotation.

Additional checks

Command formatted

Commands can be formatted with bold or italic text

Multiple commands on a single line

Multiple commands on the same line are supported.

HTML entities

HTML entities in the text value are automatically escaped.

Extended character set