Markdown syntax

You can include graphs (2D and 3D) from your current Altaxo project. The graph is referenced by name, either with the absolute path name, or relative to your markdown document. The Url of an absolute graph name starts with graph://, the Url of a relative path name starts with graph:.

Example:
Assuming your graph is named Foo\Bar\GRAPH0 and your Markdown document is named Foo\Note0:
To include the graph with absolute name in your document, use:
To include the graph with the relative name (relative to the folder 'Foo', in which your Markdown document is located), use:

At the time of writing, when you change a graph in Altaxo, the included graph in the Markdown document is not automatically updated. Press F5 to update your document and all included graphs. Also, if you rename a graph, the Urls in the markdown document are not updated automatically.

Specifying names of Altaxo graphs

Sometimes, you have to specify graph names that contain special characters. For instance, a graph name may contain a space or a slash. You can specify those names by replacing space with %20 and slash with %2F.

Graphs will be searched in the following order, using the originally specified name and some modifications:

• first of all, the originally specified graph name will be tried

• the original name is modified by replacing slashes by backslashes, and the modified name is tried then

• the original specified graph name is modified by decoding sequences such as %20 to their corresponding character, and the modified name is tried then

• the original specified graph name is modified by decoding sequences such as %20 to their corresponding character, and then slashes are replaced by backslashes, and the modified name is tried then

Example 1:

You have a graph named Weather yesterday in the Altaxo root folder. Then you can specify it using:


Example 2:

You have a graph named //SomeGraph in the folder Foo, and your text document is located in this folder, too. Then you can specify the graph using the relative path:


Please note that if you would have used instead:  the graph name would be interpreted as absolute name, and the graph would be searched in the document's root folder instead.

You can include images either from the file system or from the clipboard. To include images from the file system, select the image in Explorer, select Copy or press Ctrl-C. Then click in the source text of your markdown document, and choose Paste from the edit menu or press Ctrl-V. The image is then stored in the local image store in Altaxo, and is referenced with a long Url, which starts with local:.

To include an image from the clipboard, click in the source text of your markdown document, and choose Paste from the edit menu or press Ctrl-V. The image is then stored in the local image store in Altaxo, and is referenced with a long Url, which starts with local:.

Resizing graphs and images

You can give an image the size you want by appending an attribute to the image.

Example:

{width=5cm}

will resize your graph to a width of 5 cm. Please note that there must be no spaces in the attribute=value assignment, e.g. neither width=5 cm will work, nor width= 5cm.

To specify a height instead, use height=value likewise. You can even specify width and height, but then the aspect ratio of your image is not preserved.

Currently, the following units will be recognized: mm, cm, in, pt (1/72^nd inch), and px (1/96^th inch).

You can include formulas, using LaTeX notation. Formulas can either be included inline, i.e. in a line with other text, or in an extra line.

To include a formula inline, use a single dollar sign at the start and the end of the formula.

Example:
$f(x) = \frac{\sin(x)}{x}$ renders to:

Note that here we have no space between the dollar sign and the start of the formula text, nor a dollar sign between the end of the formula and the right dollar sign. You can also include spaces on both sides, but you can not mix, i.e. use a space at the start and no space at the end or vice versa. Furthermore, the markdown then might be incompatible with other renderers, e.g. Pandoc.

Formulas on an extra line start and end with two dollar signs. The dollar signs have to be on separate lines. The formula is then horizontally centered on the page.

Example:

C#

Copy

$$ 
f(x) = \sqrt[n]{x+x^2+x^5}
$$

renders to:

You can include special characters using HTML symbol entities. For instance, £ renders to £, ∀ renders to ∀, ⅞ renders to ⅞. A table with such characters can be found in the internet, for instance here.

If you don't found here what you want, you can also include any Unicode character. Use the Windows character map to include such a character. Please note that the font that is used to display the preview of your markdown document may not support all Unicode characters.

Some extensions to the standard markdown syntax can be used in Altaxo (in fact, the formulas from the previous section are already such an extension).

Piped table extension

You can write tables using the following syntax (borrowed from readme.md of markdig):

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

renders to:

Note that the actual appearance of the table depends on the rendering device. For instance, in Altaxo's Wpf rendering, and in help files build with the Maml export feature, tables will always take the full width of the document. Additionally, Maml export does not support alignment of table columns.

Task list extension

Write task lists using the following syntax:

- [ ] Item1
- [x] Item2
    - [x] SubItem21
- [ ] Item3
- Item4

renders to:

• Item1

• Item2

  • SubItem21

• Item3

• Item4

Figure extension

This extension is useful if you want to include figures and tables on separate lines, and want to provide them with a figure caption or table caption, respectively. Special commands are built into Altaxo to renumerate figures, and to allow to reference them from the text by number.

To include a figure, surround the figure by a block of ^^^, like so:

^^^
![](graph://Foo\GRAPH0){width=5cm}  {#An_important_graph}
^^^ Figure 1: This is a graph

In line 2 of the code block above, a graph from the Altaxo project is included. This is not new and was shown already before. The graph has a text mark #An_important_graph attached. New is that the graph is now framed with ^^^ blocks above and below. Moreover, in the last line, there is a figure caption. You can write figure captions either above (in the first line containing ^^^, which is e.g. common for tables), or as in the example above, in the line below the figure or table.

Note:

Only one of the two possible figure captions (above, below) may contain text. However, you can place a text marker in the other caption.

Even more useful is the figure extension, if used in conjunction with Altaxo's built in figure renumeration feature.

If you have more than one figure, for instance:

^^^
![](graph://Foo\GRAPH0){width=5cm}  {#An_important_graph}
^^^ Figure 1: This is a graph 
..
..
..
^^^
![](graph://Foo\GRAPH1){width=5cm}  {#Another_graph}
^^^ Figure 3: This is another graph

you most probably have the problem to keep the figure numbers up-to-date. After Figure 1, Figure 2 should follow, but in the example above, it is Figure 3 instead.

Invoke Altaxo's figure renumeration command by using Text → Renumerate figures from the main menu. This command looks for all figure captions in the document, and then tries to find a category and a number in each figure caption. The category is considered the first word in the figure caption. In the example above, the category for both figures is Figure. Both figure captions have a number, too. Altaxo then replaces the numbers in the figure captions by new numbers. Each category gets its own numbering.

Even more useful is that Altaxo also cares about the links to the figures. Assume you have referenced the figure in the text like this:

As can be seen in [Fig. 3](#Another_graph) .....

During the figure renumeration command, Altaxo parses all links. If a link points to inside a figure block, then the link text (here: Fig. 3) is parsed. If a number is found in the link text, then this number is replaced by the actual number that the figure has got now. In the example above, Figure 3 would be renumerated to Figure 2, and the link text would then be changed to Fig. 2, accordingly.

Note:

The figure renumeration feature is also available as a preprocessor option when exporting a document to Maml, Html, or an OpenXml document.

Extension to include child markdown documents

You can include child markdown documents using syntax similar to a code block. The following code will include a child document named Chapter1\Text into the master document:

```{Altaxo child="Chapter1\Text"}
Chapter1 - Title
```

The text Chapter1 - Title inside of the code block is optional and is only for the user to visualize what he is including.

The master document can be expanded later, for instance during export to Maml or to an external Markdown document.

Next section: Usage (of the editor and preview window)