Generation of JavaScript

The Markdown engine can generate JavaScript for you automatically, facilitating the dynamic creation of items on web pages. This conversion can be done either by specifying an Accept: application/javascript header when requesting for a Markdown file, or by referring to a Markdown file with an additional .js extension after the traditional .md extension. Referring this way to a file Test.md.js for instance, will generate a JavaScript rendering of the Test.md file. This method is useful if referring to JavaScript files from the header of an HTML file, for instance, where you cannot control the browser’s selection of HTTP Accept header field in the request.

When converting a Markdown file (for example Test.md) to JavaScript (for example Test.md.js), two functions are created and included in the file:

function CreateHTMLTest(Args);
function CreateInnerHTMLTest(ElementId, Args);

The final Test in the funcion names are taken from the name of the Markdown file being converted. This makes it possible to include multiple JavaScript files generated from multiple Markdown files on the same page. The Args argument can be used to send information to the function, which is later used by inline script when generating HTML.

The first function returns a string containing the HTML generated by the JavaScript. The second function calls the first function to generate HTML, the looks in the DOM of the page to find an element with a given id attribute, and then sets the innerHTML property of that element to the generated HTML.

Things to keep in mind when converting Markdown to JavaScript:

• Script placed between double braces {{ and }} is preprocessed on the server and affect the structure of the Markdown, which in turn affects the generated JavaScript. Such script do not have access to the Args argument. Instead they have access to any session variables that may exist.

• Script placed between single braces \{ and \} is not processed on the server at all. Instead, it is assumed to be JavaScript itself, and inserted as-is into the JavaScript. This allows you to populate the dynamic HTML using values from your browser, without having to request the server to do it. This also means, that the script syntax normally used for single-braces evaluation on the server, is not used in the JavaScript case. The inline script has access to Args, but as it runs in the browser, does not have access to server-side session-state variables.

• If the Markdown only contains a header-less table (i.e. a table with zero header rows), the JavaScript rendered will only generate the table rows, not the surrounding table, thead and tbody elements, to facilitate dynamic addition of rows to a table.

Generated JavaScript Example

Consider the following Markdown page, saved as Test.md:

It refers to a Markdown template called TestTable.md, in a JavaScript header. To make sure the server converts this Markdown to JavaScript, the extension .js is added to the filename, resulting in a reference to TestTable.md.js file. When the browser requests this file, the server recognizes that the file does not exist. Instead, it recognizes the .js extension, understands that it refers to the Accept: application/javascript header, and modifies the request to refer to TestTable.md with the corresponding Accept header set. The server then loads the Markdown, converts it to JavaScript, and returns JavaScript that generates HTML from the following Markdown template:

This will generate a page similar to:

JavaScript generation Test

The following table was generated by JavaScript:

#new, #features, #neuron, #javascript, #markdown

Utility for converting Microsoft Word documents to Markdown

A new utility called WordToMarkdown has been published helping users to convert Microsoft Word documents (saved in .docx file format) to Markdown. The utility can be used either on the command-line to automate conversions (for instance, if you want to keep a web-site current with content written in Word documents), or via a Windows GUI. The utility can convert single documents, or convert batches of documents identified using one or more wildcards (*).

Download

You can download and install the utility from this link:
https://lab.tagroot.io/Downloads/WordToMarkdown/setup.exe

Once the utility has been installed, you will find it in the Start Menu, by typing WordToMarkdown.

Repository

Source code is available in the MicrosoftInterop repository on GitHub. You can build the utility in Visual Studio, by building the WordToMarkdown project in the solution.

GUI

The GUI of the WordToMarkdown utility is a simple window with the following input controls:

• An input file input. Enter the name of the Word file here. You can use wildcards (*) to identify a batch of files to process. Press the ... button to select a file using a file open dialog.

• An output file input. Enter the name of the Markdown file here. You can also enter the name of a folder. In such a case, the output file will have the same file name as the input file, except having the file extension replaced with .md. Press the ... button to select a file using a file open dialog. If using wildcards (*) in the file name, the number of wildcards should match the number of wildcards in the input file name.

• A recursive checkbox. If checked, and using wildcards, the utility will scann the input folder, and all subfolders for input files matching the pattern provided in the input file name field.

• Press the Convert button to start the conversion process. A message at the end will inform you about the results of the conversion.

Command-Line

You can execute the utility using Command-Line options. This allows you to automate conversions, without the need to use the Windows GUI. If you’ve built the utility using Visual Studio, you will find the executable in the build output folder. If you’ve installed the utility you can find the installation location in the following way:

1. Start the utility
2. Open the Task Manager, and find the utility in the processes page.
3. Right-click on the process, and press Properties.
4. Under Location on the first tab, you will find the location where the application has been installed.

Note: Since the installer is a Click-Once installer, the installation location may look strange.

To find the command-line options of the utility, open a terminal window, and go to the location where the utility is installed using the cd command. Type:

WordToMarkdown -?

This will list the command-line options:

Note: Using the command-line options method, you can add custom Markdown meta-data headers to the converted files. This may be useful if generating a web site with content from the Word documents. See the Markdown Meta-data documentation for more information about meta-data tags.

#utility, #word, #microsoft, #markdown, #new, #repository

Microsoft Interoperability API (Word)

A free API package for interoperability with Microsoft products is now available on neurons. The first version allows you to convert Microsoft Word documents (saved using Open XML SDK, i.e. .docx documents) to Markdown. This can be used for presentation purposes, or for the purposes of creating smart contracts, etc. It is an optional component that can be installed by the neuron operator. The API is protected, and requires either a login (using user accounts defined by the Admin-interface; no special privileges), or a JWT token issued by the neuron (available to clients connected via XMPP, for instance), or being logged in through a web session. The API cannot be accessed anonymously.

Some more information
Package	TAG.MicrosoftInterop.package
Installation key	Y/0hf+O003/pMh6CDnQTowb3DMJj3X28Xu0H0/bOPsIdGo+XOGY2kWsEyxkpKMSNdAOjSGDlxUIA00c066163c7125123382bdd308a2ad35
More information	https://github.com/Trust-Anchor-Group/MicrosoftInterop

Markdown Lab

Once the package has been properly installed, it will insert itself into the Markdown Lab on the Neuron®. It introduces an INPUT field that allows you to upload a Word document to the server, and convert it to Markdown, on the page. This way, you can experiment with the conversion capabilities provided. If you want to have documents for testing purposes, the repository contains a set of testing documents.

Internet Content Decoder and Converter

The package contains an Internet Content decoder for MS Word documents. This means you can build your own web services, and similar tools, that receive Word documents as content, and they will be automatically decoded. There’s also an Internet Content converted from Word to Markdown that can be used to publish Word documents directly on the site. These documents will be automatically converted to Markdown, and from Markdown to any other accepted format (like HTML), if the request indicates that the client only accepts HTML, for instance. This allows you to publish content directly using Word documents, without the need to converting them manually first.

Formatting Support

Microsoft Word supports a very rich set of features for formatting content in their documents. Markdown on the other hand, is not designed for creating formatted content in the same way, so a 1-to-1 conversion is not possible. But basic formatting constructs can be converted successfully. The following lists should give you an idea of what is supported and not.

Supported

• Sections
• Multiple columns
• Paragraphs and justifications (Left, Right, Center, Justify)
• Simple formats, such as Bold, Italic, Underline, Strike Tough, Superscript, Subscript, Insert, Delete, inline code
• Block code
• Horizontal separators
• Some fields and form input controls
• Tables, column spans
• Lists (Bullet-point lists, numbered lists, mixed lists)
• Table of contents
• Images & Figures
• Captions
• Frame contents
• Footnotes
• Endnotes

Not Supported (examples)

• Languages
• Positioning
• Colors
• Fonts
• Sizes
• Pages
• Headers
• Footers
• Macros
• Some fields and form input controls
• Row spans in tables
• Custom list formats.
• Indexes, Bibliographies, etc.
• Drawings and Shapes
• Frame position and layout.

Logging of unrecognized elements

If converting a Word document that contains elements the package library does not understand, information about these items will be logged to the event log. You can use this information to extend support to such items in the repository.

API Endpoint

API interface for the Word -> Markdown conversion is very simple. You execute a POST to the /MicrosoftInterop/WordToMarkdown resource on the Neuron® where the package is installed. The contents of the POST is the actual Word document. The response will be Markdown.

Example code

The following Markdown snipped, with associated Javascript function call, will call the API, and convert a Word document provided via a file INPUT tag, and place it into a TEXTAREA tag on the page. This code is inserted into the Markdown Lab available to logged in users with sufficient privileges on the Neuron®:

---

#api, #markdown, #word, #microsoft, #new, #features

Complex tables in Markdown

One of the limitations of traditional Markdown has been the lack of ability to create tables containing content that requires more than a line to represent. When more complicated tables had to be generated, they had to be created using embedded HTML tags, which limits the portability of the content, as these are only displayed correctly if the Markdown is used to render HTML interfaces.

The IoT Gateway Markdown engine has traditionally somewhat bypassed this limitation by allowing for simple Markdown inclusion. But that method required splitting the content into multiple files.

During the work of transforming Microsoft Word documents to Markdown, a need for a more flexible table construction using Markdown has been necessary. The engine has therefore been updated to include a new type of table construct, where you use the combinations of footnotes and the traditional table construct, to create more complex tables. If a single footnote reference is included in a table cell, the contents of the note will be rendered inside the cell directly, instead of at the bottom of the screen.

Example:

| Table with complex cells ||
|:-------------|:-----------|
| [^e11]       | [^e12]     |
| [^e21]       | [^e22]     |

[^e11]:	| Info about cell ||
    |:--------|-------:|
    | Row     | 1      |
    | Column  | 1      |

[^e12]:	| Info about cell ||
    |:--------|-------:|
    | Row     | 1      |
    | Column  | 2      |

[^e21]:	| Info about cell ||
    |:--------|-------:|
    | Row     | 2      |
    | Column  | 1      |

[^e22]:	| Info about cell ||
    |:--------|-------:|
    | Row     | 2      |
    | Column  | 2      |

Generates the following table:

Table with complex cells
Info about cell Row 1 Column 1	Info about cell Row 1 Column 2
Info about cell Row 2 Column 1	Info about cell Row 2 Column 2

More information is available in the Markdown reference documentation.

#new, #features, #markdown

Horizontal Alignment of text in Markdown

The latest version of the Markdown library now supports horizontal alignment of content. This is done by using the << and >> operators at the beginning and ends of rows or blocks, to signal different types of alignments:

Horizontal Alignment
<<...	Left-alignment
...>>	Right-alignment
>>...<<	Center-alignment
<<...>>	Margin-alignment

More detailed description of the syntax is available in the Markdown reference.

Note: You may need to refresh the page, or clear browser cache, to make sure the most recent styles are downloaded with the page, in case the following examples are not displayed correctly.

Support

The Markdown engine can generate different types of output. Horizontal alignment is supported by various degrees in the different formats, as shown in the following table:

Horizontal Alignment support

	Left	Right	Center	Margin
HTML
LaTeX
XAML
Xamarin.Forms
Smart Contract
Plain Text

CSS classes

When rendering to HTML, the following class names will be used:

Horizontal alignment class names

Alignment	Class name
Left	horizontalAlignLeft
Right	horizontalAlignRight
Center	horizontalAlignCenter
Margins	horizontalAlignMargins

The CSS available in the themes installed with the Neuron® contain the following default styles: (Note that you may need to refresh the browser or clear the cache for these styles to be reloaded.)

.horizontalAlignLeft
\{
    text-align:start;
\}

.horizontalAlignRight
\{
    text-align:end;
\}

.horizontalAlignCenter
\{
    text-align:center;
\}

.horizontalAlignMargins
\{
    text-align:justify;
\}

Example

Following is a Markdown example, illustrating different horizontal alignments of text:

--------------

<<### Left alignment
<<
<<Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam ultrices erat ac enim dictum, sit amet tincidunt mi eleifend. Cras tristique, est a pellentesque finibus, augue risus posuere turpis, nec blandit tellus nulla et nulla. Quisque leo neque, eleifend eget enim ut, elementum fermentum elit. Maecenas commodo molestie odio et consequat. Fusce eu turpis lacus. Donec tincidunt non nisl eget consectetur. Nulla vehicula nunc eget luctus varius. Sed orci justo, tristique quis mi at, rutrum varius lorem.

--------------

### Right alignment>>

>>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam ultrices erat ac enim dictum, sit amet tincidunt mi eleifend. Cras tristique, est a pellentesque finibus, augue risus posuere turpis, nec blandit tellus nulla et nulla. Quisque leo neque, eleifend eget enim ut, elementum fermentum elit. Maecenas commodo molestie odio et consequat. Fusce eu turpis lacus. Donec tincidunt non nisl eget consectetur. Nulla vehicula nunc eget luctus varius. Sed orci justo, tristique quis mi at, rutrum varius lorem.>>

--------------

>>### Center alignment<<
>><<
>>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam ultrices erat ac enim dictum, sit amet tincidunt mi eleifend. Cras tristique, est a pellentesque finibus, augue risus posuere turpis, nec blandit tellus nulla et nulla. Quisque leo neque, eleifend eget enim ut, elementum fermentum elit. Maecenas commodo molestie odio et consequat. Fusce eu turpis lacus. Donec tincidunt non nisl eget consectetur. Nulla vehicula nunc eget luctus varius. Sed orci justo, tristique quis mi at, rutrum varius lorem.<<

--------------

<<### Margin alignment>>
<<>>
<<Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam ultrices erat ac enim dictum, sit amet tincidunt mi eleifend. Cras tristique, est a pellentesque finibus, augue risus posuere turpis, nec blandit tellus nulla et nulla. Quisque leo neque, eleifend eget enim ut, elementum fermentum elit. Maecenas commodo molestie odio et consequat. Fusce eu turpis lacus. Donec tincidunt non nisl eget consectetur. Nulla vehicula nunc eget luctus varius. Sed orci justo, tristique quis mi at, rutrum varius lorem.>>

--------------

This is rendered as follows (in HTML):

---

---

---

---

---

#new, #features, #markdown