markdown4documentation v0.5.0

markdown4documentation

markdown4documentation is a tool that can either convert a single markdown file, a complete directory or a complex structure to HTML or PDF. You can choose between several build-in themes (called templates) or define a custom theme.

Complex structures mean that you can combine multiple markdown files into a single HTML or PDF file. You can insert prebuild HTML structures in the result also as well as whole pdf files.

markdown4documentation can either be used from the CLI or from inside a Node.js script.

• Use the CLI
• Create a custom template
• Create a configuration file
• Use with Node.js script
• Contributing

Use the CLI

First, install from NPM:

npm install --global markdown4documentation

That's all, markdown4documentation is ready for use. NPM now has registered the command markdown4documentation, or shorter m4d.

Simple example

This example generates an HTML file from your Markdown file.

markdown4documentation --file README.md --output README.html

To generate a pdf, simply add --type:

m4d --file README.md --output README.pdf --type pdf

These commands use the default theme. markdown4documentation provides a material design theme also. Just add the --template parameter:

m4d --file README.md --output README.pdf --type pdf --template material

How to create your templates is explained further below.

For more features use a configuration file:

m4d --configuration configuration.json

CLI Parameters

Create a custom template

A template is a JavaScript file, which defines, how markdown4documentation renders HTML elements. To create an own template file, you can copy one of the built-in templates and modify them. You can find the build-in templates in the templates folder.

To set a custom template, just provide the relative or absolute path to the file to the --template parameter.

Create a configuration file

A configuration file is a JSON file. It has one property jobs. Each job describes a conversion.

Sample:

{
    'jobs': []
}

Jobs

markdown4documentation supports three different modes of jobs: file, directory and merge.

• file: Convert a single file, like with the CLI parameters
• directory: Convert all Markdown files in a directory
• merge: Merge multiple Markdown files to one output file

Sample:

{
    'jobs': [
        {
            'mode': 'file',
            'type': 'html',
            'template': 'default',
            'input': 'myFile.md',
            'output': 'myFile.html',
            'suppressLeadingH1': false,
            'indentHeadlines': 0,
            'headingNumbering': false,
            'pdfOptions': {...}
        }
    ]
}

A Job has this parameters:

PdfOptions

PdfOptions has these parameters:

Size Units

Size can be measured in centimeter, millimeter or inch. For centimeter set for example '2cm', for millimeter '20mm' and inch '0.78in'.

Header and footer templates

There are some things you should note on the header and footer template:

• Your templates should be included in a surrounding div.
• The default font-size is very small, so you have to set the font-size manually.
• To remove the default space above and under the header and footer, add this style at the very beginning of the header or footer template: <style>#header, #footer { padding: 0 !important; }</style>.
• The default width of a surrounding div is not 100% as usual. You have to set the width manually to 100% if needed.
• You can inject some predefined values: date, pageNumber and totalPages. Add it as a CSS class: <span class='totalPages'></span>.
• You cannot add images by URL, you have to include images as base64 encoded string.

A possible header could be this:

<style>#header, #footer { padding: 0 !important; }</style><div style='font-size: 10px'>Hello world, Page <span class='pageNumber'></span></div>

Tasks

A task is one file of a merge job.

Sample:

{
    'jobs': [
        {
            'mode': 'merge',
            ...
            'input': [
                {
                    'type': 'file',
                    'file': 'myFile.md',
                    'suppressLeadingH1': false,
                    'indentHeadlines': 0,
                    'sub': []
                }
            ]
        }
    ]
}

A Task has these parameters:

Use with Node.js script

markdown4documentation can be used manually to convert Markdown files to HTML or PDF files.

Install with NPM:

npm install --save markdown4documentation

Require in a script:

const m4d = require('markdown4documentation');

markdown4documentation consists of four main classes.

markdown4documentation has two more classes, which can't be created manually.

Parse a single markdown file

This sample parses markdown to HTML.

const m4d = require('markdown4documentation');

// For a build in template:
const template = m4d.Templates.default;

// For a custom template:
const template = require('path/to/template');

const htmlBuilder = new m4d.HtmlBuilder(template);

const markdown = '...';

const htmlParser = new m4d.HtmlParser(markdown, htmlBuilder);
let html = htmlParser.Parse();

html = htmlBuilder.BuildPage(html);

To create a PDF file you either have to use a configuration or create it manually. markdown4documentation uses Puppeteer for PDF creation.

Classes

Class 'Configuration'

Class 'Job'

Class 'PdfOptions'

Class 'Task'

Class 'Processor'

Class 'HtmlBuilder'

Class 'HtmlParser'

Disclaimer

markdown4documentation may have some other Methods and Properties that can be accessed. But all classes, methods, properties, variables and so on that are not mentioned here are not considered as stable and may not be determined for public use.

Contributing

Do you want to contribute to this project? Great! Please consider reading the contributions guideline in the CONTRIBUTING.md.