Cheatsheet

This document comes with examples for most of the features offered by MarkAPL. The documentation is however not comprehensive: it provides just enough information to get you going.

For a comprehensive documentation refer to http://download.aplteam.com/MarkAPL.html or call MarkAPL.Reference 0.

1. Headers

These are the standard ways to mark-up headers:

# Level 1
## Level 2
### Level 3
#### Level 4
##### Level 5
###### Level 6

Note that headers may contain only text and code but nothing else.

Headers of level 1 and 2 can also be produced with = and -:

This is a level 1 header
========================

This is a level 2 header
========================

Note that before and after a header a blank line is required.

2. APL Code

First of all code can be either marked up as in-line code (within a paragraph, a list item, a block quote, a grid cell and a header) or as a code block standing on its own.

2.1. In-line code

In-line can be marked up by enclosing the code with ticks.

This `{{⍵/⍨2=+⌿0=⍵∘.|⍵}⍳⍵}` is an example.

Result:

This {{⍵/⍨2=+⌿0=⍵∘.|⍵}⍳⍵} is an example.

2.2. Code blocks

Code blocks can be marked up in two different ways:

2.2.1. “Git” style fencing

This requires 3 ticks as shown here:

```
{{⍵/⍨2=+⌿0=⍵∘.|⍵}⍳⍵}
```

Result:

{{⍵/⍨2=+⌿0=⍵∘.|⍵}⍳⍵}

2.2.2. “Extra” style fencing

This requires 3 ~ as shown here:

~~~
{{⍵/⍨2=+⌿0=⍵∘.|⍵}⍳⍵}
~~~

Result:

{{⍵/⍨2=+⌿0=⍵∘.|⍵}⍳⍵}

2.2.3. Info string and special attributes

A code block may have an info string or special attributes or both; see

3. Tables

|Name     |Remark     |No. of users|
|:-----|:---------:|------:|
| APL     | Brilliant |   800 |
| Cobol   |       Old | 14000 |
| F#      |      Newer|  3400 |
| Haskell |       New |  3400 |
| Java    |       Just|    74 |
|=========|===========|=======|
|Total    |           | 21674 |

Result:

Name Remark No. of users
APL Brilliant 800
Cobol Old 14000
F# Newer 3400
Haskell New 3400
Java Just 74
Total 21674

Simplest possible table: one column, no header, no alignment, no footer:

--|
10|
20|
30|

Result:

10
20
30

Notes:

4. Lists

List may start right after a paragraph. They break at two empty lines.

4.1. Ordered lists

2. Second
2. Third

Result:

  1. Second
  2. Third

4.2. Unordered lists

* This
* That

Result:

4.3. Nested lists

Note that indentation defines what belongs to what.

* This
* That

  A para belonging to <That>

  10. Ten
  1.  Eleven

      A para belonging to <Eleven>

  Another para belonging to <That>

* More

Result:

Lists may contain paragraphs, code blocks, sub lists and, since version 3.0, tables, blockquotes and images.

5. Blockquotes

> This is a blockquote. Note that a blockquote may contain anything: paragraphs, lists, code blocks, tables, headers, definition lists and even blockquotes.

Result:

This is a blockquote. Note that a blockquote may contain anything: paragraphs, lists, code blocks, tables, headers, definition lists and even blockquotes.

> > Nested Blockquote.

Result:

Nested Blockquote.

6. Definition list

APL
: Best programming language ever

COBOL
: Oh dear

Result:

APL
Best programming language ever
COBOL
Oh dear

7. Horizontal lines

---

Result:


8. Paragraphs

Everything that is not identified as something else is considered a paragraph.

9. In-line mark-up

In-line mark-up can be used in paragraphs, lists, tables, blockquotes, definition lists and headers.

9.1. Bold and italic

A para can contain **bold**, *italic* and **_bold and italic_**.

Result:

A para can contain bold, italic and bold and italic.

9.2. In-line code

A para can contain `inline code {+⌿⍴⍵}`.

Result:

A para can contain inline code {+⌿⍴⍵}.

9.3. Strike-through

This feature is not available was introduced in version 9.0

9.4. Syntactical sugar

Available options:
* --- (m-dash)
* -- (n-dash)
* (c) (copyright)
* (tm) (trade mark)
* ... (ellipses)
* <<Guillemets>>
* ==> (right arrow)
* <== (left arrow)
* <==> (left-and-right arrow)

Result:

Available options:

9.5. Double quotes

Pairs of double-quotes (\") are exchanged against their typographically correct equivalents "like here".

Result:

Pairs of double-quotes (") are exchanged against their typographically correct equivalents “like here”.

Note that Germany, Austria and Switzerland use different characters. MarkAPL looks at the HTML parameter lang in order to decide which to choose. See the MarkAPL reference for details.

Note that a double-quote can — like any other character — be escaped by a \ character. However, escaping is an issue more complex than you might think. Please refer to the reference for details.

9.6. Special HTML characters: “<”, “&” and “>”

Since Markdown is a writing format it is easy to write about <html> & use tags.

Result:

Since Markdown is a writing format it is easy to write about <html> & use tags.

9.7. Links

9.7.1. External links

External links with [APL wiki](http://aplwiki.com) and without link text: <http://aplwiki.com>

Result:

External links with APL wiki and without link text: http://aplwiki.com

Note that you must specify a protocol (“http://”, “https://”, “ftp://” etc), otherwise it is not going to be converted. Don't use this for “mailto:” links.

You can add a title as well as special attributes to an external link:

[APL wiki](http://aplwiki.com"This link brings you to the APL wiki"{target="_blank"})

This is the result:

APL wiki

The title is shown when you hover with your mouse over the link.

9.7.2. Automated links

A special version of an external link is the so-called automated link. Such a link is suitable only in case the url as such is going to be the link text:

<http://aplwiki.com

Note that such a link must specify a protocol like “http://”, “https://”, “ftp://” etc. Do not use autolinks for “mailto:” links.

9.7.3. Internal links

Since MarkAPL assigns anchors to all headers you can establish a link with

[{Link text}]({Caption})

You can link to such a header in the current document with a simplified syntax in case the link text is exactly the caption:

Link to the [headers](#) section.

Link to the headers section.

Naturally it is important that every single header has a unique ID in order to make this work. Therefore _MarkAPL_ converts any header to an ID. _MarkAPL_ has quite a complex set of rules for how to do this. See MarkAPL's full documentation for details.

If _MarkAPL_ encounters the same header again then it will add a number to it in order to tell them apart. It will report this on ns.report

In such cases — which should be rare, really — it is a better idea to assign a unique ID via special attributes. Of course you must then use this ID when linking to that header, so the simplified syntax is not on option in such cases.

Sometimes the header text does not really fit as link text. Overcome this by specifying:

Link to the [headers](# "Link text") section.

9.7.4. Link references

Link references consists of two parts:

  1. The definition of a link ID together with its URL.
  2. References to the link ID.

The definition of such a reference can go anywhere in the document but usually they go to the bottom.

Examples for definitions:

[1]:      http://aplwiki.com
[git]:    http://github.com "Linus' brain child"{target="_blank"}
[vector]: http://vector.co.uk "The well-respected Journal of the British APL Association"

You can use the IDs then to inject the links into, say, a paragraph:

This paragraph links to [][1], [][git] and [the APL Journal][vector].

This paragraph links to http://aplwiki.com, Linus' brain child and The APL Journal.

Note that special attributes can be defined in the definition part but not the link part.

10. Images

![Dots](http://download.aplteam.com/APL_Team_Dots.png "APL Team's dots")

Dots

11. Special attributes

Sometimes one wants to assign special attributes to a certain element. Typical candidates are images and tables.

This can be achieved by specifying those attributes by putting them to the right of the object in question, enclosed by curly brackets.

For example, in order to specify width and height for an image, add a description and center both, image and description:

![](http://download.aplteam.com/APL_Team_Dots.png){height="70" width="60" style="display:block;margin:auto;"}
_The logo_ {style="text-align:center;font-size:70%;padding-top:0;margin-top:-10px;"}

The logo

You can also assign class and ID to an object via this syntax:

The logo {#logo .center .red}

This is how the resulting HTML code would look like:

<p id="logo" class="center red">The logo</p>

Noe that links are special: any special attributes must be part of the links definition. That means they must be specified to the left of the closing glyph, be it a > or a ).

12. Helpers

There are helper methods available that are designed to help an APL programmer to convert data in a workspace into Markdown.

12.1. Matrix2MarkdownList

If you have a matrix in APL then you can easily convert this into Markdown by calling the method Matrix2MarkdownList.

Note that the matrix must have three columns:

  1. List type. A 0 defines a bulleted list. Any positive integer starts an ordered list, and defines at the same time the starting point.
  2. Nesting level. The first row must start with nesting level 0 or 1.
  3. Either a text vector or a vector of text vectors.

This is an example:

 m←''
 m,←⊂0 1 'Level 1 a bull'
 m,←⊂2 2 'Level 2 a num'
 m,←⊂2 2('Level 2 b num' '' 'Another para' '' '~~~' '{+⌿⍵}' '~~~')

12.2. Matrix2MarkdownTable

If you have a matrix in APL then you can easily convert this into Markdown by calling the method Matrix2MarkdownTable.

Defaults:

Note that via the left argument column headers can be specified. You can use leading and/or trailing colons to define column alignment.

Examples:

      m←3 3⍴'Kai' 1000 'Remark' 'Thomas' 20 'Blah' 'Max' ¯1 'Foo'
      ch←'Name' 'Points' ':Comments:'
      ⎕←⍪ch #.MarkAPL.Matrix2MarkdownTable m
Name|Points|Comments
:-|-:|:-:
Kai|1000|Remark
Thomas|20|Blah
Max|¯1|Foo
Name Points Comments
Kai 1000 Remark
Thomas 20 Blah
Max ¯1 Foo

13. Inject data

You can inject key/value pairs into a Markdown document with this syntax:

[data]:name='Kai Jaeger'
[data]:dob=19310231

MarkAPL itself does not take advantage of such data but you can by referring to it via ns.data.

For details refer to the MarkAPL reference document.

14. Inject parameters

You can inject key/value pairs representing parameters into a Markdown document with this syntax:

[parm]:toc=1 2 3
[parm]:title='My own title'

Such lines must be the first ones in any document.

MarkAPL will use these parameters to overwrite any defaults or settings via a parameter namespace.

For details refer to the MarkAPL reference document.

15. Version

This document refers to version 3.6.0 of MarkAPL.
Kai Jaeger ⋄ APL Team Ltd ⋄ 2017-11-20