Skip to content

Conversion

Jump to bottom
Arne Westphal edited this page Oct 21, 2018 · 14 revisions

Conversion

To convert some markdown code to Html you can simply use

var htmlConverter = new MarkdownElearnJS.HtmlConverter();

// save as file
htmlConverter.toFile(markdown, filePath, rootPath).then((filename) => {
    console.log(filename);
}, err => console.error(err));

// only the html if you want to save it yourself
htmlConverter.toHtml(markdown).then((html) => {
    console.log(html);
}, err => console.error(err));

Or for Pdf conversion

var pdfConverter = new MarkdownElearnJS.PdfConverter();

// save as file
pdfConverter.toFile(markdown, filePath, rootPath).then((filename) => {
    console.log(filename);
}, err => console.error(err));

//get a buffer
pdfConverter.toBuffer(markdown, rootPath).then(() => {
    console.log();
}, err => console.error(err));

// only the html if you want to use your own render framework
pdfConverter.toHtml(markdown).then((html) => {
    console.log(html);
}, err => console.error(err));

Interface

Both the HtmlConverter and the PdfConverter support the following functions:

toHtml(
    markdown: string,            // the markdown code
    options?: ConversionObject); // see Conversion Options
toFile(
    markdown: string,            // the markdown code
    file: string,                // output file path e.g: "C:\\example\output.html"
    rootPath: string,            //
    options?: ConversionObject,  // see Conversion Options
    forceOverwrite?: boolean);   // if true, existent file will be overwritten

Most of these parameters should be obvious.

  • markdown: the raw markdown code.
  • options: see Conversion Options.
  • file: the full output path including the file name and type.
  • rootPath: the path to the parent directory of the original markdown file. This is necessary for relatively linked files.
  • forceOverwrite: if set to true, the output file defined by file will be overwritten if existent.

Parameters followed by a ? are optional and will be replaced by default values if not given.

PDF Converter Interface

The PDF converter supports the additional function toBuffer. Excluding the file parameter, the interface is equal to the toFile.

Converter Settings

When creating a HtmlConverter or PdfConverter you can set some settings. These settings are meant to be rather constant and thus you do not have to set them in each conversion.

There are general settings, which can be set for both converters, and converter specific settings.

To set these options use

var htmlConverter = new MarkdownElearnJS.HtmlConverter(options);
// or
var htmlConverter = new MarkdownElearnJS.HtmlConverter();
htmlConverter.setOptions(options);
htmlConverter.setOption('headingDepth', 2);

or

var pdfConverter = new MarkdownElearnJS.PdfConverter(options);
// or
var pdfConverter = new MarkdownElearnJS.PdfConverter();
pdfConverter.setOptions(options);
pdfConverter.setOption('headingDepth', 2);

General Converter Settings

These are the default settings:

var options = {
    'newSectionOnHeading': true,
    'headingDepth': 3,
    'useSubSections': true,
    'subSectionLevel': 3,
    'subsubSectionLevel': 4
};
  • newSectionOnHeading (boolean): Whether the create <section> elements on specific headings or not.
  • headingDepth (integer): The last heading level to add a <section> to. (1-6)
  • useSubSections (boolean): If sub- and subsubsections are created at a specific heading level (subSectionLevel, subsubSectionLevel)
  • subSectionLevel (integer): Level from which on created sections are subsections.
  • subsubSectionLevel (integer): Level from which on created sections are subsubsections.

For more information on elearn.js sections check the Syntax Extensions Wiki.

PDF Converter Settings

The PDF settings are an addition to the general converter settings. You can combine these options in one object. The pdf specific option defaults are:

var options = {
    'newPageOnSection': true,
    'contentZoom': 1,
    'customHeader': "",
    'headerHeight': "0",
    'customFooter': "...", // this code is too long to be displayed here
    'footerHeight': "17mm",
    'customStyleFile': undefined,
    'chromePath': undefined,
    'puppeteerOptions': undefined,
    'keepChromeAlive': false
};
  • newPageOnSection (boolean): Whether to insert a page break before every section or not.
  • contentZoom (float): Zoom factor for the HTML rendering. (e.g. 1.5 will display everything 50% larger, if possible)
  • customHeader/customFooter (string):
  • headerHeight/footerHeight (string):
    • Changes internal settings of header and footer height
    • You can use strings like 1.7cm or 12px with units px, mm, cm, in
    • Do not use any spaces
  • customStyleFile (string):
    • You can insert an absolute path to add an additional CSS file
    • This file can overwrite elearn.js specific styles for the PDF Output
  • chromePath (string):
    • You can insert an absolute path to the chrome executable
    • This can be used if the bundled chrome does not work for some reason (e.g. on ARM architectures)
    • Only use if you know what you're doing
  • puppeteerOptions:
  • keepChromeAlive:
    • If set to true, the chromium instance will kept running as long as possible
    • Reduces PDF conversion time after the first startup
    • Will automatically restart if launcher options change
    • If set to false the running instance will be terminated
      • Always set to false when done if you want to your programm to terminate correctly

Examples

customHeader / customFooter
<div style="text-align: right; padding: 7mm; 10mm">
  <span class="date"></span> - <span class="pageNumber"></span>
</div>

This will create headers or footers like 9/18/2018 - 7.

Conversion Options

Conversion options can be used in every conversion function:

htmlConverter.toHtml(markdown, options);
pdfConverter.toPdfHtml(markdown, options);
pdfConverter.toFile(markdown, file, rootPath, options, forceOverwrite);
pdfConverter.toBuffer(markdown, rootPath, options, forceOverwrite);

These options tend to be different for every file converted, which is why they have to be given as parameter for every conversion.

General Options

The general options include following values

var options = {
    bodyOnly: false,
    language: "en",
    automaticExtensionDetection: false,
    removeComments: false,
    includeQuiz: false,
    includeElearnVideo: false,
    includeClickImage: false,
    includeTimeSlider: false
};
  • bodyOnly (boolean): Will return only the basic conversion of the markdown file. There is no correct <html> or <body> surrounding it. Should not be used for actual saving. Might be useful if you want to scan the output for extensions (MarkdownElearnJS.ExtensionManager.scanForQuiz(html), ...)
  • language (string) ["en", "de"]: Will include the elearn.js language selection in the <head> of the Html.
  • automaticExtensionDetection (bool): Whether to automatically scan for extensions or not. Might be overwritten by explicit includeXY below.
  • removeComments (bool): Whether to automatically remove all Html comments (<!-- ... -->) in the output or not.
  • includeQuiz/includeElearnVideo/includeClickImage/includeTimeSlider (boolean): Whether to include the specific extension or not.

HTML Conversion Options

For the function toFile you can additionally overwrite the following default values

var options = {
    exportAssets: false,
    exportLinkedFiles: false,
};

By default toFile will only export the actual .html file.

If you want to export the necessary elearn.js assets set exportAssets: true. This way the basic assets and all included extensions will be exported to a assets folder next to the output file.

When publishing a .html file, you most likely would like to include your linked images. When exporting to a different folder, relative links will no longer work. Absolute links will not work when publishing either. Therefore you can set exportLinkedFiles: true. The markdown will then be converted and all linked files, no matter if linked with an absolute or relative path, will be extracted to the assets folder next to the output file. Detected files are images, videos, audio files, stylesheets and scripts, when used in corresponding html tags. So basically everything linked in a img, source, script, link after the html conversion.

PDF Conversion Options

For the functions toFile and toBuffer you can additionally set a value for renderDelay.

var options = {
    renderDelay = 1000, // in ms
};

A render delay is the time to wait between loading the Html page and rendering it to a pdf file. This might be useful for scripts triggered after the initial loading.

Clone this wiki locally