Creating specifications with Markdown
This page introduces documenting specifications in Markdown. Click the toggle buttons above to choose other options.
- Specification Structure
- Specification language
Once we have discussed the examples, we create a Concordion specification describing the feature with examples.
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
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.
Further details: Breadcrumbs specification
Styling your specifications
Concordion comes with a default style out of the box that is automatically applied to output specifications.
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 |
In addition to standard Markdown, Concordion supports:
- MultiMarkdown format tables. If using Github, you might want to limit yourself to Github Flavored Markdown tables.
- strikethrough format using
~~tildes around the words~~.
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.
See the MarkdownExtensions javadoc for a definition of the available extensions.
Note that the Concordion fixture will need to be configured to enable the markdown extensions.
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).
The syntax used for this extension is compatible with Github Flavored Markdown, allowing specifications to be edited and previewed in the Github editor.
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.
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 :)