Documenting

Creating specifications with Markdown

This page introduces documenting specifications in Markdown. Click the toggle buttons above to choose other options.

Once we have discussed the examples, we create a Concordion specification describing the feature with examples.

Specification Structure

Concordion provides you the flexibility to structure your specifications however you like.

As a guideline, specifications are often based on individual features of a system. Larger features are normally broken down into smaller features, creating small, focussed specifications that are faster to check.

A common structure is:

# Feature title

Feature description

## Business Rules or Acceptance Criteria


- Rule 1
- Rule 2

...

## Additional detail

Any other background info

### Example 1

details of example 1

### Example 2

details of example 2

...

Structure of Examples

Concordion provides the flexibility to structure examples however you like.

When documenting the context, action and outcome of an example, you can write these three parts using the Gherkin “Given, When, Then” language. This is often a good way to get started. Once you become familiar with thinking about the context, action and outcome, you may find ways to describe your example in a more natural language.

For example, you could use either:

Given a user with full name John Smith
When the system splits the name
Then the first name is John and the last name is Smith

or:

The full name John Smith will be broken into first name John and last name Smith

The Hints and Tips page contains some good practices for writing specifications, including:

  • Writing at a high level of abstraction
  • Only reveal data the specification actually needs
  • Create focussed examples

Creating a suite

Markdown links allow us to create a structured suite of specifications, with the pages nested under a hierarchical index. For example:

Product
     Theme
          Feature
              Sub-Feature
              Sub-Feature
          Feature
          Feature
              Sub-Feature
     Theme
          Feature
              Sub-Feature
          Feature

At each level, the specification contains links to all the specifications below it. For example, a theme page would describe the theme and link to all the features in the theme. The specifications can be nested arbitrarily deep.

By using this approach, and instrumenting the links to child specifications with the run command, executing any specification will automatically execute all its child specifications, with the results aggregated upwards.

To make it easier to navigate around the results, and to remove the headache of having to maintain upward links manually, breadcrumbs are automatically added to output.

In order for breadcrumbs to be generated, certain conventions must be followed.

Example of breadcrumbs

Further details: Breadcrumbs specification

Styling your specifications

Concordion comes with a default style out of the box that is automatically applied to output specifications.

Additional styling

Should you wish to enhance your specifications, you can add CSS, JavaScript, images, or other resources to tweak or completely overhaul the existing styling. If applying additional styling, the fixture will need to specify the resources to be copied to the output specification.

Specification language

Concordion specifications can be written using either Markdown or HTML (alternatively you can use Excel with the Excel Extension, or write your own extension to handle other formats). Specification suites can contain specifications written in a mixture of specification languages.

Markdown format specifications

Markdown provides an easy-to-read and easy-to-write syntax for specifications.

As a crash course, typing the following:

# Heading

This is a __bold text__ in a paragraph

## Subheading

| Name            | Age |
| --------------- | --- |
| Fred Flintstone | 35  |
| Betty Rubble    | 27  |

results in:

HTML output including table

For further details about Markdown, read the Markdown basics and syntax.

In addition to standard Markdown, Concordion supports:

Inline HTML

For syntax that is not covered by Markdown, you can use inline HTML. The HTML will normally need to be wrapped in a <div> element. For an example, see how inline HTML is used for unusual sentence structures.

Extending the Markdown syntax

Markdown extensions allow you to change and/or extend the behaviour of the Markdown parser, for example to change the behaviour of new lines, or to support definition lists.

Concordion provides two ways to configure Markdown extensions:

  • From Concordion 2.0.0, you can use a fixed set of MarkdownExtensions. These are configured using the ConcordionOptions annotation.
  • From Concordion 3.0.0, you can use a wider range of extensions and configuration options provided by the Flexmark parser. Each Flexmark extension is packaged as its own artifact and will need to be added to your project. To add the Flexmark extension to your Concordion fixture, see FlexmarkOptions.

Markdown editors

While you can edit Markdown in a text editor, you’ll get additional features such as preview, syntax highlighting and auto indent with a Markdown editor. There are lots of options available, including online editors, plugins to text editors such as Notepad++ and dedicated Markdown editors. You might want to make sure your editor supports tables, strikethrough and any of the other Markdown extensions you configure (see above).

Github

The syntax used for this extension is compatible with Github Flavored Markdown, allowing specifications to be edited and previewed in the Github editor.

IDEA

The official IntelliJ IDEA Markdown Support plugin is recommended, along with the excellent Concordion Support plugin, which makes it easy to author and run Concordion specifications.

The Markdown Navigator plugin is also supported.

Previously, we recommended the Markdown plugin, but this plugin is no longer maintained and has been removed from the Jetbrains plugin repository.

Eclipse

Available Eclipse plugins include:

Plugin Has editor? Has viewer? Viewer supports tables and strikethrough
Mylyn Wikitext Editor Y Y N
Markdown Text Editor Y N N
Github Flavored Markdown Viewer N Y Y

In order to have editing features and the ability to view with tables and strikethrough, we suggest installing either of the first 2 editor plugins listed above for editing, along with the Github Flavored Markdown Viewer plugin for viewing.

If you have other recommendations for editors, please let us know what you are using, and what support you get from it. Click on the Improve this page link below to edit this page and raise a pull request or create an issue on this project to let us know. Thanks :)

Instrumentingchevron_right