Export of a text document

To export your text document to a external markdown file, choose File → Export Markdown.. from the main menu. Choose a file name for the markdown file in the file save dialog. The markdown text is saved into this file. In order to save the local images, a subfolder named Images is created in the same folder as the markdown document. The local images are stored in this folder. The Urls that link to the images in the markdown text are changed accordingly in order to point to the new location.

The text document can be exported to one or multiple Maml files. MAML (= Microsoft Assisted Markup Language) is a XML dialect used to build help files. A good tool to convert Maml files to a help file or to web site content is the Sandcastle Help File Builder. There you also find a good tutorial concerning the Maml language.

To export to Maml, choose from the main menu File → Export to Maml... The Maml file export dialog opens. There are different options to influence the final export result:

• Header split level: a value of 0 ensures that the entire document is exported into a single Maml file. A value of 1 splits the document at each first level header, resulting in a Maml file per every first level section. A value of 2 splits the document at each first level and second level header, and so on...

• Folder name for content: folder name relative to the base directory (see below), in which the exported .aml files with the help contents are stored.

• Remove all old contents of content folder: By checking this, all .aml and .content files in the content folder will be deleted before the export. Use this option with care!"

• Base file name of content files: A text string that is set as start for every content (.aml) file name. Can be left empty, because the exporter will generate meaningful file names for the content files.

• Folder name for images: folder name relative to the base directory (see below), in which the exported figures and formulas are stored.

• Remove all old contents of image folder: By checking this, all .png, .jpg, .jpeg, .tif files in the image folder will be deleted prior to export. Use this option with care!

• Enable auto outline: by enabling this option, an auto outline (small table of contents) is included at the beginning of each Maml file.

• Link to previous section: by enabling this option, a link to the previous section is included at the beginning of each Maml file.

• Link to previous section label text: here you can give a text fragment that precedes the link to the previous section. Note that you probably want to include a space at the end of the text in order to separate the label from the link.

• Link to next section: by enabling this option, a link to the next section is included at the end of each Maml file, to make it easier to consecutively read the document.

• Link to next section label text: here you can give a text fragment that precedes the link to the next section. Note that you probably want to include a space at the end of the text in order to separate the label from the link.

• Expand child documents: by enabling this option, child documents included with the extension to include child Markdown documents are expanded before export.

• Renumerate figures: if this option is checked, all figures will be renumerated (after the document is expanded). See the figure renumeration feature above.

• Font family of body text: concerns export of formulas only - since formulas are exported as images, it is important to know the properties of the text they are embedded in. Therefore, font family and font size have to be known in advance. For use with the Sandcastle Help file builder, at the time of writing the font family was "Segoe UI", and the font size 15.

• Font size of body text: see above explanations concerning Font family.

• The Maml file(s) are intended to be used to build a HTML Help 1 (chm) file: For formulas to be shown nicely, it is important that the alignment of the formula image with the surrounding text is perfect. Unfortunately, HTML Help 1 files have a different handling of vertical image alignment than e.g. HTML files. Therefore, it is necessary to know if you want to build a HTML Help 1 file from the exported Maml files, or other content (e.g. a HTML web site).

• Output file name: please provide here the name of the Sandcastle help file builder project file. If you don't want the use the Maml files with Sandcastle help file builder, you can specify any other file name. The file name is then used as base to derive the file name of the content layout file. Additionally, the directory where the file is located in, is used as base directory for other subdirectories, for instance the Image subdirectory.

• Open Sandcastle help file builder after export: by enabling this option, if you have specified a Sandcastle help file builder project file as output file, after export the Sandcastle help file builder application is launched.

Note:
The generation of the file names of the help content files (.aml) is done as following:

Use the hierarchy of the first (maximal three) title levels. If there is only one first level header, ignore it. From each title use from the first three words the first alphanumerical letter of each word. To the generated string, a guid string is appended that is generated from the full hierarchy of titles.

In this way, as long as the title (and the parent titles) do not change, the file name and the Guid of the file will stay the same, which is very important when you use these files with a version control system!

The text document can be exported to a single Microsoft Word .docx file. Microsoft Word needs not to be installed on the computer in order to export to .docx. The styles in the Markdown document are converted to formatting styles in the Word file. LaTeX formulas in the Markdown document are converted to editable formulas in the Word file!

Style mapping

The following style mapping is used in the conversion process:

Paragraph styles

• Heading1 .. Heading6 are mapped to Word's built-in Heading 1 .. Heading 6 style

• Quoted text is mapped to Word's built-in BlockText style

• Lists (bullet lists and numbered lists) are mapped to Word's built-in List style

• Code blocks are mapped to CodeBlock style. This style is not built in Word and will be created if it is not already present (see the topic templating below).

• Figure captions are mapped to the Caption style.

Inline (character) styles

• Links in Markdown are mapped to Word's built-in Hyperlink style.

• Markdown code inlines are mapped to CodeInline style. This style is not built in in Word and will be created if it is not already present (see the topic templating below).

Nested styles

In Markdown it is possible to create nested paragraph styles. For instance, you can easily create a CodeBlock inside a quote like in this Markdown:

> Block quote line 1
> ```
> First line of code
> Second line and end of code
> ```
> Last line of block quote

Nested styles are not supported by Word, at least not directly. After all, you can base a paragraph style on another paragraph style. This is what would happen in the example above: for the code block inside the quote a new paragraph style is created, which is based on the BlockText style (see style mapping above). The name of the newly created paragraph style is the concatenation of the two style names BlockText and CodeBlock, so the new paragraph style name is BlockText CodeBlock. In this way, even if there is no predefined style BlockText CodeBlock, after the conversion process you can change the appearance of that style for the entire document at once.

Known limitations

There are a couple of limitations when exporting to OpenXml:

• Inline Html is not exported

• Horizontal rules inside BlockQuotes will most probable break the styling. This is because a horizontal rule in Word is realized by using an own paragraph style with a bottom line.

Templating

The appearance of the finally exported Word file depend on how the styles described above are defined. There is a set of style definitions built-in into Altaxo, with which the Word document's appearance is close to the GitHub style used for rendering the Markdown document inside Altaxo.

If you want to use another style set, the easiest way is to create a Word document in which all of the above mentioned styles are defined and set according to your wishes. During the export process you can then use this document as style template file, so that your styles are transferred to and used in the the final Word document. There is another advantage to use a .docx file as style template: you are able to embed your own fonts in it.

If you are unsure how which styles you need to modify, then copy the Markdown (see below) into an Altaxo text document, and then export it with the GitHub style to a .docx file. Then open the exported .docx file with Word, and style all the paragraphs. Attention! Do not style the paragraphs directly. Instead, click on the Start tab, then click on the very small arrow belowChange formatting templates (not on the button itself). A list of formatting templates should appear, that remains open until you close it explicitly. When you then click into your document, you will see that the formatting template selected in the list will change depending on where you have clicked into the document. To change for instance the formatting template for Heading 1, click into the text Heading 1. The formatting template Heading 1 should then be selected in the list of formatting templates. Now, right-click on the selected formatting template and choose Change... Now change the styles as you like. Repeat this for all paragraphs with different formatting templates. Store the document. This document now can be used as style template for exporting.

Here is the markdown text to copy into Altaxo and then export:

Standard text. Standard text. Standard text.
Standard text. Standard text. Standard text.
Standard text. Standard text. Standard text.
Standard text. Standard text. Standard text.
Standard text. Standard text. Standard text.

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

>BlockQuote text (style: 'BlockText')  
>BlockQuote text (style: 'BlockText')  
>BlockQuote text (style: 'BlockText')  
>BlockQuote text (style: 'BlockText')  

```
Code Code Code (style: 'CodeBlock')
Code Code Code (style: 'CodeBlock')
Code Code Code (style: 'CodeBlock')
```
^^^
![](res:Icons.16x16.ArrangeBottom){width=5cm}
^^^ Figure 1: (style: 'Caption')

> Note: the next paragraph is a CodeBlock inside a BlockQuote.
>```
>Code (style: 'BlockText CodeBlock')
>Code (style: 'BlockText CodeBlock')
>Code (style: 'BlockText CodeBlock')
>```
> The previous paragraph was a CodeBlock inside a BlockQuote.


Bullet list paragraph (style: 'List'):

- Item1
- Item2
- Item3

Numbered list paragraph:

1. Item1
1. Item2
1. Item3

---

Now look at some inline formatting styles:

---

This word is `codeinline` formatted (formatting style: 'CodeInline').

This word is [hyperlink](https://altaxo.github.io/Altaxo/) formatted (formatting style: 'Hyperlink') .

Exporting to OpenXml (.docx) file

Make the text document you want to export your current window. Then choose File → Export to OpenXMl (.docx) from the main menu. The following dialog opens up:

Here, you have the following options:

• Apply maximum image width and height:
  If you have images included, often the problem is that they are too large. By checking the checkbox and entering a value, e.g. 15 cm for the maximum width, you can limit the size of the images in which they appear in the Word document.

• Graph rendering resolution:
  The graphs that are included in your Markdown will be rendered with that resolution. In most cases 600 dpi is sufficient. Word can run into problems if you set this value too high.

• Expand child documents: If your Markdown document contains child documents (see here), they will be expanded prior to the export.

• Renumerate figures: if this option is checked, all figures will be renumerated (after the document is expanded). See the figure renumeration feature above.

• Use automatic figure numbering: if this option is checked, the built-in capability of OpenXml documents for figure numeration is used. The figure numbers are exported to text fields that do the numbering automatically. The number in the links to the figures are replaced by text references to those automatic numbers.

• Do not use hyperlink style for figure references: if checked, the links to figures are not formatted in the hyperlink style. Instead, they are formatted as plain text.

• Name of the file used as style template
  If you leave GitHub as style template (as seen in the figure above), the built-in GitHub style template is used for the final word file. If you press the Select button, you can choose one of your own Word documents as a style template. The contents of this file will not be changed.

• Remove old contents of the style template file
  If this checkbox is unchecked, text content that is in your own style template file will be copied to the exported file, and the contents of your Markdown document appended at the end of the old contents. If the checkbox is checked, the text contents of your style template file will not be copied to your exported file.

• Output file name
  Select here the full file name of the .docx file to export.

• Open the application associated with .docx file
  If checked, the application that is associated with the .docx extension will be opened with the exported file after the export has finished. Usually, this will be the Word application (if installed on your computer)

Press OK to export your file. After export, have a look at your document, especially at the tables. You may need to adjust the column widths.

Next section: Altaxo's code editor