BlockML Documentation


1 Basic usage

The BlockML OSX app is basically a compiler for plain text files that are marked up with BlockML. To create these plain text files you will need a separate text editor. You can use whatever text editor you like, but it is highly recommended, to use TextMate or Sublime Text, in combination with the BlockML.tmbundle, to get syntax highlighting. If you need help with the setup of TextMate or Sublime Text read: 9 Setup TextMate and Sublime Text. Possible file extensions are .txt and .blockml.

Once you have created a text file and want to compile it, drag and drop it onto the BlockML OSX app. You will notice that the app starts compiling immediately and opens a browser window with your actual output HTML.

The app has generated an output-folder next to your text file. This output-folder contains the HTML-file, the css-folder and an images-folder. Once the output-folder was generated, the css-folder and the images-folder don't get overwritten after recompilation. Use the images-folder to add images to your document and the css-folder to add custom CSS-files.

2 Syntax

BlockML source text consists of plain text and markup elements. BlockML markup has always these structure:

A markup element begins with a selector, which specifies the type of the element. The selector is as short as possible and often inspired by HTML tag names.

The selector is followed by one or more blocks, depending on the type of the element. Blocks contain content and are not interchangeable. Some elements have one optional block at their end, for example the img-element with its optional size specification:

img[cat.png][300, 200]

The content has to be plain text in some blocks, while other blocks can contain plain text and further markup. For instance, the element for inline code has to contain only plain text like: c[UITableView]. An instance for a markup element that could contain other markup is the section element: sec[Overview][An instance of c[UITableView]...]. You can think of blocks like of arguments for a method: a block on a certain position expects a certain input.

3 Markup elements

3.1 Paragraphs, line breaks and white space

Paragraphs and line breaks work exactly like you would except. To create new paragraphs use 2 LFs (press 2 times Enter). To create line breaks use 1 LF.

This is a paragraph.↵
This is a second paragraph.↵
This is a new line.

Useless whitespace gets removed from the compiler.

The BlockML compiler removes useless white space like the LFs above.↵
••••Or this TAB in front of this sentence.

3.2 Title

This element creates a centered, clown sized heading and it sets the <title> of your HTML document.

title[Document Title]

Document Title

3.3 Headings

There are headings from <h1> - <h6>. Headings don't get used for the Table of Contents (see 3.6 Table of contents).

h1[Heading 1]
h2[Heading 2]
h3[Heading 3]
h4[Heading 4]
h5[Heading 5]
h6[Heading 6]

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6

3.4 Document head

Use head[Content] to create a nice looking header for your document.
Allowed contents for this element are title and h1-h6.

title[Document Title]
h2[Heading 2]
h6[Heading 6]

Document Title

Heading 2

Heading 6

3.5 Sections

Sections consist of a section heading and section content.


These content can be text and every BlockML markup element, regardless that not every element makes sense in that context, for example title and toc elements.

Nest the sections to get a section hierarchy.

sec[Section Heading][

sec[SubSection Heading][Content]/* SubSection */

]/* Section */

1 Section Heading

1.1 SubSection Heading


A complex example:

sec[Section Heading][

sec[SubSection Heading][Content]/* SubSection */

sec[SubSection Heading][

sec[SubSubSection Heading][Some other content]/* SubSubSection */


]/* Section */

sec[Section Heading][Content too]/*Section*/

1 Section Heading

1.1 SubSection Heading


1.2 SubSection Heading

1.2.1 SubSubSection Heading

Some other content

2 Section Heading

Content too

3.6 Table of contents

To get a table of contents use the toc-element. The table of contents gets assembled from the section headings.

toc[TOC Title]

The table of contents for the section example above looks like this:

TOC Title

  • 1 Section Heading[⚐]
    • 1.1 SubSection Heading[⚐]
    • 1.2 SubSection Heading[⚐]
      • 1.2.1 SubSubSection Heading[⚐]

3.7 Links

A Link consists of an URL or of an URL and a link description.

a[][Description Text]
Description Text

3.8 Images

To embed a local image into the document, copy that image into the auto generated images-folder, which is part of the output-folder. Then embed the image name without any path references.


You can also embed images from the internet, when you use their URL.


If an image doesn't fit into the document, resize its width or its height or both with a second block: [w, h]

Don't forget the comma!

/*adjust width and height*/
img[localImage.png][400, 300]

/*adjust only the width*/

/*adjust only the height*/

3.9 Code listings

Code listings uses the following syntax:


BlockML makes use of Highlight.js to provide syntax highlighting. In order to get proper highlighting you have to specify the programming language. You find a list of all available languages under: Use no-highlight if you don't want syntax highlighting.

code[java][System.out.println("Hello World!");]
System.out.println("Hello World!");

You have to escape all square brackets in your code. For more information read 5 Escape of special characters.

code[objectivec][self.scanner = \[Scanner scannerWithString:string\];
self.document = \[HTMLDocument new\];]
self.scanner = [Scanner scannerWithString:string];
self.document = [HTMLDocument new];

3.10 Math formulas

Since BlockML uses MathJax for mathematics rendering you can use TeX/LaTeX or MathML syntax.

Use math[Formula] for larger equations that stay separated by themselves. The delimiters for TeX/LaTeX formulas are $$...$$ or \[...\].

math[$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$$]
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$$

Or use im[Formula] for inline mathematics. The TeX/LaTeX inline delimiters are $...$ or \(...\).

Some inline mathematics: im[$a \ne 0$].

Some inline mathematics: $a \ne 0$.

You have to escape all square brackets and backslashes. For more information read 5 Escape of special characters.

3.11 Tables

The BlockML tables are very similar to HTML tables. There are the 4 markup elements to build a table:

To assemble a table create at first a table-element:


Then add the rows:


Finally, add th-cells and td-cells:

tr[ th[Header 1] th[Header 2] ]
tr[   td[Data 1]   td[Data 2] ]

Header 1

Header 2

Data 1

Data 2

Another simple example:

tr[ th[Header 1] td[Data 1] ]
tr[ th[Header 2] td[Data 2] ]

Header 1

Data 1

Header 2

Data 2

Add a second block, to specify the number of rows or columns a td-cell or a th-cell should span. [h:number] creates a horizontal span and [v:number] creates a vertical span.

In this example th[Header][h:2] creates a horizontal span over 2 columns.

tr[ 	  th[Header][h:2] ]
tr[ td[Data 1] td[Data 2] ]


Data 1

Data 2

In this example th[Header][v:2] creates a vertical span over 2 rows.

tr[ th[Header][v:2] td[Data 2] ]
tr[                 td[Data 1] ]


Data 2

Data 1

And in this example td[Data 1][h:2] creates a horizontal span over 2 columns.

tr[ th[Header 1] th[Header 2] ]
tr[           td[Data 1][h:2] ]

Header 1

Header 2

Data 1

3.12 Captions

You should use captions directly after image-, code-, math- or table-elements. To create a caption use:


The first block specifies the type of the caption like: Listing, Fig., Figure, Table, Abbildung...The second block contains the description text to your image-, code-, math- or table-elements.

Captions of the same type get numbered consecutively. Captions of another type have their own consecutive numbering.

cap[Fig.][An image]

code[python][print("Hello, world!")]
cap[Listing][A code listing]

cap[Fig.][Another image]

code[lisp][(display "Hello, world!")]
cap[Listing][Another code listing]
Fig. 3.1: An image
print("Hello, world!")
Listing 3.1: A code listing
Fig. 3.2: Another image
(display "Hello, world!")
Listing 3.2: Another code listing

3.13 Lists

3.13.1 Unordered lists

To create unordered lists use the ul[]-element and add your list items to it. You can use dashes - in front of items to emphasize the list structure, but you don't have to. The whitespace between dash and item is irrelevant.

You can nest your lists with other unordered or ordered lists. See an example in Listing 3.3.

- item
- item
- item
  • item
  • item
  • item
 - item
  • item
  • item
  • item

3.13.2 Ordered lists

Ordered lists work in the same way like unordered lists.

- item
- item
- item
  1. item
  2. item
  3. item

An example with nested lists:

- item
- item
	- item
	- item
	- item
Listing 3.3: Nested lists
  1. item
  2. item
    • item
    • item
    • item

3.14 Footnotes

For footnotes use fn[Content]. All footnotes get added to the end of the document.

Some text with a footnote fn[Content].

Some text with a footnote [1].

[1]↵ Content

3.15 Cross references

Basically, cross references to captions, sections and bibliography items work almost the same. At first, specify an UID with id[UID]. An UID is an unique string, which should only used for one reference.

Use the id at this place in your text, where you want to mention the reference.

Some text with a reference id[UNIQUE].

Read the following sections, to see how to connect an id with your captions, sections or bibliography items.

3.15.1 References to captions

Add a further block to your caption that contains the UID.


Here is an example with an image-caption. The UID is "IMG01":


Look at id[IMG01].
Figure 3.1: Image

Look at Figure 3.1.

3.15.2 References to sections

Add a further block to your section that contains the UID.

sec[Section Heading][Content][UID]

Here is an example with "SEC" as UID:

For more information see id[SEC].

sec[Section Heading][

For more information see 1 Section Heading.

1 Section Heading


3.15.3 References to bibliography items

bibliography items own by default an UID-block.

bib[UID][Publication Details]

Here is an example with "BIB01" as UID:

...(figure taken from id[BIB01])

bib[BIB01][Author, Title, Date]

...(figure taken from [BIB01])


Author, Title, Date

3.16 Bibliography

To reference a publication use the following syntax:

bib[UID][Publication Details]

The UID is an unique string, which should only used for one bibliography item.

The publication details must become formatted by your self, in a bibliography style of your choice.

If two or more bibliography items follow each other, they get sorted alphabetically by their UIDs.

It might be best practice to collect all bibliography items in a separate "References"/"Bibliography" section or place them at the end of the document. The UID should not be longer then 6 characters and should contain a little bit context to the publication.

Some examples:

bib[SKETCH][Ivan Sutherland.  Sketchpad: A Man-Machine Graphical Communication System. MIT, 1963. a[][PDF]]

bib[DNA][James Watson and Francis Crick. A Structure for Deoxyribose Nucleic Acid. Nature 171, 737-738, 1953. a[][PDF]]

James Watson and Francis Crick. A Structure for Deoxyribose Nucleic Acid. Nature 171, 737-738, 1953. PDF


Ivan Sutherland. Sketchpad: A Man-Machine Graphical Communication System. MIT, 1963. PDF


There are block quotations with or without a source.





3.18 Text styles

You can style your text as bold, italic, underlined, marked, strikethrough, subscript text, superscript text, and as inline code.

3.18.1 Bold

My b[bold] text.

My bold text.

3.18.2 Italic

My i[italic] text.

My italic text.

3.18.3 Underlined

My u[underlined] text.

My underlined text.

3.18.4 Marked

My m[marked] text.

My marked text.

3.18.5 Strikethrough

My s[strikethrough] text.

My strikethrough text.

3.18.6 Subscript

My subscript sub[text].

My subscript text.

3.18.7 Superscript

My superscript sup[text].

My superscript text.

3.18.8 Inline Code

My c[inline code].

My inline code.

3.19 Embed HTML

3.19.1 Inline HTML

Embed inline HTML with ih[HTML Code].

You can use inline HTML in the same way like inline BlockML elements (see 4 Block-level and inline-level markup).


text text ih[<b>text</b>] text.

text text text text.

3.19.2 Block HTML

Embed block-level HTML with html[HTML Code].





Out comment text with /*...*/.

/* Comment */

/* Comment
lines */

Some text with a comment /* a[] */ inside.

4 Block-level and inline-level markup

Since BlockML has to be compilable to HTML, its feature set is closely linked to the capabilities of HTML. Like HTML BlockML has block level markup and inline markup.

Inline-level markup

Inline level markup can appear within plain text or some block-level elements.

a, fn, id, ih, im, c, b, u, i, s, m, sub, sup

Block-level markup

Block-level elements may appear within a sec-element or separated on a new line.

title, head, toc, sec, h1...h6, img, math, code, ul, ol, q, cap, bib, table, html

5 Escape of special characters

Since square brackets [] have a very special meaning in BlockML, it is necessary to escape them, if you want to use them in a non markup context. For example in code or mathematical formulas.

Here is a typical code example:

[self.window orderFront:self];

To escape the square brackets just set a backslash \ in front of them.

\[self.window orderFront:self\];

The backslash \ has a special meaning as escape symbol, you have to use two backslash \\ in order to print one. This can get a little bit messy in fancy TeX/LaTeX formulas.

For example in this TeX/LaTeX formula:

\dot{x} & = \sigma(y-x) \\
\dot{y} & = \rho x - y - xz \\
\dot{z} & = -\beta z + xy

You have to write this:

\\dot{x} & = \\sigma(y-x) \\\\
\\dot{y} & = \\rho x - y - xz \\\\
\\dot{z} & = -\\beta z + xy

And get this result:

\begin{aligned} \dot{x} & = \sigma(y-x) \\ \dot{y} & = \rho x - y - xz \\ \dot{z} & = -\beta z + xy \end{aligned}

But luckily the BlockML App helps to manage all the backslashes. Just insert your code or equation to the upper textfield and use the text from the textfield below.

6 Error warnings

If the BlockML compiler can't compile your text file you will get an error message. For instance, a forgotten closing square bracket will cause an error like this:

sec[Section Heading][

1 Error found!
Error with Section

1 Section Heading


Error with Section

7 Use custom CSS

Just replace the default screen.css and print.css with your own stylesheets. But let the file names unchanged.

	<link media="screen" href="css/screen.css" type="text/css" rel="stylesheet">
	<link media="print" href="css/print.css" type="text/css" rel="stylesheet">

8 Convert HTML documents to PDF

CSS has theoretically the capability to render printable PDFs out of HTML pages. This functionality is called "Paged Media". Some Paged Media features are:

Unfortunately, no browser supports this functions in their PDF export yet. But, there are some HTML to PDF converting tools like Prince, which implement the Paged Media specification. Prince offers a free license for non-commercial use and is perfect for converting BlockML documents to PDFs.

The print.css is the place where you can set up all the Paged Media stuff.

This article is a good introduction to the topic: Printing a Book with CSS: Boom!

9 Setup TextMate and Sublime Text

9.1 TextMate

1. Download TextMate and the BlockML plugin
2. Drag and drop the BlockML.tmbundle onto the TextMate icon

3. Install it

4. Choose BlockML as language

Almost done! The following steps are optional.

5. In case you want to use the BlockML color schemes, drag and drop the BlockML Night.tmTheme/BlockML Day.tmTheme onto the TextMate icon

6. Add the tmTheme-file to the BlockML-bundle

7. Choose a color scheme

Fig. 9.1: Night theme
Fig. 9.2: Day theme

8. Activate Spell Checking

9.2 Sublime Text

1. Download Sublime Text and the BlockML plugin

2. Open Sublime Text's Packages-folder

3. Move the downloaded BlockML-folder into the Packages-folder

4. Choose BlockML as language

5. Finally, you can choose a BlockML color scheme

Fig. 9.3: Night theme
Fig. 9.4: Day theme