Preliminaries

Markdown & CommonMark

The text for Accord Project templates is written using markdown. It builds on the CommonMark standard so that any CommonMark document is valid text for a template or contract.

As with other markup languages, CommonMark can express the document structure (e.g., headings, paragraphs, lists) and formatting useful for readability (e.g., italics, bold, quotations).

The main reference is the CommonMark Specification but you can find an overview of CommonMark main features in the CommonMark Section of this guide.

Accord Project Extensions

Accord Project uses two extensions to CommonMark: CiceroMark for the contract text, and TemplateMark for the template grammar.

Lexical Conventions

Accord Project contract or template text is a string of UTF-8 characters.

note

By convention, CiceroMark files have the .md extensions, and TemplateMark files have the .tem.md extension.

The two sequences of characters {{ and }} are reserved and used for the CiceroMark and TemplateMark extensions to CommonMark. There are three kinds of extensions:

1. Variables (written {{variableName}}) which may include an optional formatting (written {{variableName as "FORMAT"}}).
2. Formulas (written {{% expression %}}).
3. Blocks which may contain additional text or markdown. Blocks come in two flavors:
   1. Blocks corresponding to markdown inline elements which may contain only other markdown inline elements (e.g., text, emphasis, links). Those have to be written on a single line as follows:

      {{#blockName variableName}} ... text or markdown ... {{/blockName}}

   2. Blocks corresponding to markdown container elements which may contain arbitrary markdown elements (e.g., paragraphs, lists, headings). Those have to be written with each opening and closing tags on their own line as follows:

      {{#blockName variableName}}
      ... text or markdown ... 
      {{/blockName}}

CiceroMark

CiceroMark is used to express the natural language text for legal clauses or contracts. It uses two specific extensions to CommonMark to facilitate contract parsing:

1. Clauses within a contract can be identified using a clause block:

   {{#clause clauseName}}
   text of the clause
   {{/clause}}

2. The result of formulas within a contract or clause can be identified using:

   {{% result_of_the_formula %}}

For instance, the following CiceroMark for a loan between John Smith and Jane Doe includes a title (Loan agreement) followed by some text, followed by a fixed rate interest clause. The clause contains the terms for the loan and the result of calculating the monthly payment.

# Loan agreement

This is a loan agreement between "John Smith" and "Jane Doe", which shall be entered into
by the parties on January 21, 2021 - 3 PM, except in the event of a force majeure.

{{#clause fixedRate}}
## Fixed rate loan

This is a _fixed interest_ loan to the amount of £100,000.00
at the yearly interest rate of 2.5%
with a loan term of 15,
and monthly payments of {{%£667.00%}}
{{/clause}}

More information and examples can be found in the CiceroMark part of this guide.

TemplateMark

TemplateMark is used to describe families of contracts or clauses with some variable parts. It is based on CommonMark with several extensions to indicate those variables parts:

1. Variables: e.g., {{loanAmount}} indicates the amount for a loan.
2. Template Blocks: e.g., {{#if forceMajeure}}, except in the event of a force majeure{{/if}} indicates some optional text in the contract.
3. Formulas: e.g., {{% monthlyPaymentFormula(loanAmount,rate,loanDuration) %}} calculates a monthly payment based on the loanAmount, rate, and loanDuration variables.

For instance, the following TemplateMark for a loan between a borrower and a lender includes a title (Loan agreement) followed by some text, followed by a fixed rate interest clause. This template allows for either taking force majeure into account or not, and calls into a formula to calculate the monthly payment.

# Loan agreement

This is a loan agreement between {{borrower}} and {{lender}}, which shall be entered into
by the parties on {{date as "MMMM DD, YYYY - h A"}}{{#if forceMajeure}}, except in the event of a force majeure{{/if}}.

{{#clause fixedRate}}
## Fixed rate loan

This is a _fixed interest_ loan to the amount of {{loanAmount as "K0,0.00"}}
at the yearly interest rate of {{rate}}%
with a loan term of {{loanDuration}},
and monthly payments of {{% monthlyPaymentFormula(loanAmount,rate,loanDuration) as "K0,0.00" %}}
{{/clause}}

More information and examples can be found in the TemplateMark part of this guide.

Dingus

You can test your template or contract text using the TemplateMark Dingus, an online tool which lets you edit the markdown and see it rendered as HTML, or as a document object model.

You can select whether to parse your text as pure CommonMark (i.e., according to the CommonMark specification), or with the CiceroMark or TemplateMark extensions.

You can also inspect the HTML source, or the document object model (abstract syntax tree or AST), even see a pdf rendering for your template.

For instance, you can open the TemplateMark from the loan example on this page by clicking this link.