Markup extras

Today we’ve enabled couple of markup extras in TeamDesk. These are:

Fenced Code Blocks

Fenced code blocks are like markup’s regular code blocks, except that they’re not indented and instead rely on start and end fence lines to delimit the code block. The code block starts with a line containing three or more tilde (~) characters, and ends with the first line with the same number of tilde. For instance:

~~~~~~~~~~~~~~~~~~~~~
fenced code block line 1
fenced code block line 2
~~~~~~~~~~~~~~~~~~~~~

renders as

fenced code block line 1

fenced code block line 2

Tables

A “simple” table looks like this:

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

First line contains column headers; second line contains a mandatory separator line between the headers and the content; each following line is a row in the table. Columns are always separated by the pipe (|) character. Once converted to HTML, the result is like this:

First Header Second Header
Content Cell Content Cell
Content Cell Content Cell

If you wish, you can add a leading and tailing pipe to each line of the table. Use the form that you like. A table need at least one pipe on each line for markup to parse it correctly. This means that the only way to create a one-column table is to add a leading or a tailing pipe, or both of them, to each line.

You can specify alignment for each column by adding colons to separator lines. A colon at the left of the separator line will make the column left-aligned; a colon on the right of the line will make the column right-aligned; colons at both side means the column is center-aligned.

Definition Lists

Markup now implements definition lists. Definition lists are made of terms and definitions of these terms, much like in a dictionary.

A simple definition list in markup is made of a single-line term followed by a colon and the definition for that term.

Apple
:   Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.

Orange
: The fruit of an evergreen tree of the genus Citrus.

Terms must be separated from the previous definition by a blank line. Definitions can span on multiple lines, in which case they should be indented.

Abbreviations

Markup adds supports for abbreviations. How it works is pretty simple: create an abbreviation definition like this:

*[HTML]: Hyper Text Markup Language
*[W3C]:  World Wide Web Consortium

then, elsewhere in the document, write text such as:

The HTML specification is maintained by the W3C.

Abbreviation definitions can be anywhere in the document. They are stripped from the final document.

Inline HTML

For E-Mail Alert workflow actions we’ve also enabled the use of HTML tags. This is pretty useful when you need some features not provided by the markup syntax but which are easy to do with HTML.

There are two restrictions however:

  1. The opening tag of a block element must not be indented by more than three spaces. Any tag indented more than that will be treated as a code block according to standard Markdown rules.
  2. When the block element is found inside a list, all its content should be indented with the same amount of space as the list item is indented. (More indentation won’t do any harm as long as the first opening tag is not indented too much and then become a code block — see first rule)

Moreover, HTML code can use markup inside of it:

<div> This is *bold* markup text.</div>

If you need to turn this feature off, you can add markup="off" attribute to HTML tag:

<div markup="off">This is *starred* text.</div>

Rendering markup in Word

Before enabling extras we were mapping markup to Word commonly used styles, however recently we’ve found out that Word is able to use HTML content embedded into the document and modified our code to use this feature. This change enabled us to take advantage of Word’s HTML import filter that is far more capable than our code.

Yet, it may introduce some minor breaks in content styling.

Before the change we were mapping headers to corresponding Header N Word styles either embedded in the document or defined in a Normal.dot template. Word’s HTML Import also uses document’s embedded styles but when they are absent, instead of using template’s defined styles it creates new ones emulating browser’s defaults using Times New Roman font. In order to solve this problem and embed style in the document you can either use the style once or copy the style from template into the document. Please note that:

  • Headers use Heading 1-6 styles.
  • Bold and italic map to Strong and Emphasis styles
  • Block quotes map to Quote style
  • Code blocks map to HTML Code style
  • Abbreviations map to HTML Acronym style
  • Definition terms map to HTML Definition style
  • Tables map to HTML Table style; this style is not present in the template yet you can create new one specifying one of the Word’s predefined styles for the Style based on property.

Support for XHTML formulas

Switching to Word’s HTML import process enables us to render XHTML – Formula results properly; you can now use those formula to conditionally format values.

Tweet about this on TwitterShare on Facebook0Share on Google+0