Md2word NPM | npm.io

md2word

Markdown to word automation

Concept

Markdown is easy to learn and write (see this guide). It can be validated (using markdownlint) and automated (using markdown-it).

Hence this is the perfect syntax to collaborate when writing a document.

However, some book publishers expect to receive a Word document.

This tool was created to automate the rendering of a markdown page inside a word document using styles that can be customized.

Setup

To install the tool use : npm install md2word -global
To validate and serve a markdown file, simply use md2word <md filename>

When the markdown file is served, open Word and executes the formatting macro : an example is provided here.

Markdown linter

The markdown linter can be tweaked with a configuration file as described here. The file must be named md2word.json and be placed in the same folder than the markdown file.

Example file :

{
  "default": true,
  "MD013": false,
  "no-hard-tabs": true
}

Example of a md2word.json

Code linters

Code linting is made possible through dedicated scripts (not included).

For each language that requires validation, create a file named <language>.linter.js in the folder containing the markdown file.

The module is loaded using Node.js's require and it must only exports one asynchronous function taking two parameters :

basePath the folder containing the markdown file being parsed
text the code to validate

The function should resolve to an array of messages containing :

line the line number where the message is generated (0 based, relative to the text content)
message the error message

module.exports = async function (basePath, text) {
  return [{
    line: 0,
    message: 'Any error'
  }]
}

Example showing the expected return of a custom linter

An example of a javascript linter (based on standard) is provided in in the repository.

Commands

Basically, the markdown file is parsed and broken down into a set of commands.

For instance, the following markdown :

# This is an example

This text is **bolded and *italic***, so cool !

Example markdown

Is translated into this list of commands :

text This is an example
left 18
select 18
format header1
enter
text text is bolded and italic, so cool !
left 28
select 17
format bold
left 6
select 6
format italic
right 11
enter

Example list of commands generated from the markdown

List of commands

Command	Parameter	Explanation
type	escaped text (%N instead of carriage return)	Type some text. Cursor is set after the text.
left	character count	Moves the cursor to the left
right	character count	Moves the cursor to the right
select	character count	Moves the cursor to the right and selects underlying text
format	style name	Format the current selection with the style
xref	text code/image index	Replace the occurrences of text with a cross reference to the code or image (index is 1-based)

List of styles

Style name	Style param	Effect
header1	n/a	Header level 1
header2	n/a	Header level 2
header3	n/a	Header level 3
header4	n/a	Header level 4
bold	n/a	bold
italic	n/a	italic
underline	n/a	underline
code	language	code
caption	code/image index	code or image caption (index is 1-based)
inline_code	n/a	inline code
box_header	n/a	Box header
box_content	n/a	Box content
image	n/a	Convert the selected path into an image path
bullet_list	level index	* bullet list item (level and index are 1-based)
order_list	level index	1. order list item (level and index are 1-based)
box_bullet_list	level index	* bullet list item (in a box, level and index are 1-based)
box_order_list	level index	1. order list item (in a box, level and index are 1-based)
url_title	n/a	url name
url	n/a	url

NOTE : Only URLs using the following link syntax are accepted :

[url name](url_address)

Accepted URL syntax

And are rendered like the following :

url name (<a href="url_address">url address</a>)

Example rendering of URL syntax

Special syntaxes

Captions

Images and code samples must own a caption.

The caption is introduced with a blockquote : it must be an unformatted one liner (you may use code element).

alert('Hello World !');

Example using the alert function

Boxes

A box is defined by a title and its content. The title is introduced with a blockquote : it must be an unformatted one liner (you may use code element). The content is introduced with an additional blockquote level.

> This is the box title
>> This is the box **content**. It may contain :
>>
>> * Formatting
>> * Bullet lists

Example of a box

Cross references

The following tokens are automatically converted into cross references to captions.

{{xref:NEXT}} references the next immediate code or image
{{xref:PREVIOUS}} references the previous immediate code or image
{{xref:id}} references the code or image flagged with id

The id can be set directly in the caption using {{xref:id}}: it must be specified at the beginning of the caption as surrounding spaces are removed.

For example :

The {{xref:NEXT}} is a JavaScript example

```javascript
// This is a javascript comment
function div (a, b) {
  return a / b;
}

assert.strictEqual(div(1, 1), 1);
\```

> {{xref:JS_SAMPLE}} JavaScript example

The {{xref:PREVIOUS}} can also be referenced **after** it was used.
Or it can be referenced **anywhere** in the document, as shown in {{xref:JS_SAMPLE}}.