Common steps

This program doesn't have an installer and follows the unpack-and-run approach:

Put the unpacked directory md2html into a directory of your choice (or clone the repository there).
Define the MD2HTML_HOME environment variable as the absolute path to the md2html directory.
Follow further specific steps for:
- Python version and
- Java version
On Windows, Windows Explorer context menu items may be added, see here.

Tip

After the program is installed, before further reading, you may go to the Quick start section and try out the program.

Python version

Prerequisites

This program requires a Python 3 runtime. See here for installation instructions (if required).

The following command may be used to check whether Python is installed:

>python --version
Python 3.8.7

Note

Version 3.8 is the intended one for this program. Later versions of Python will very likely be suitable too, but they haven't been fully tested.
On Unix-like systems, the python3 command should be used instead of python.

The following Python packages must be installed:

>python -m pip install markdown==3.3.4 markdown-emdash==0.1.0 pymdown-extensions==8.2 jsonschema==3.2.0 chevron==0.14.0

Note

The packages are specified with their versions for stability reasons. Future versions of the packages may have changes that noticeably affect how the program works.
(Optional) Consider a Python virtual environment (venv) to avoid modifying the system-wide Python installation. venv adaption is not yet done in this program, bit it is planned.

Installation

No program-specific installation steps are required, provided that the common steps are fulfilled and the prerequisites are matched.

Java version

Prerequisites

Java runtime (JRE) 8 or higher. The following command may be used to check whether Java is installed.

>java -version
java version "1.8.0_05"
.  .  .

Important

Java 8 is the intended version for this program. Java 11 was tried and worked stable, no differences were observed. But with Java 17 the program did not compile due to code incompatibilities. This issue is planned to be investigated.

Installation

Here's how the Java version may be installed:

Fulfill the common steps.
Take or build the executable artifact (see below).

Unlike the Python version, the Java version in this distribution doesn't contain the executable artifacts. They must be built or taken separately.

Using the release build

The release artifact is a file named md2html-bin.jar. Download this file (it must be available along with the source code) and put it inside the directory %MD2HTML_HOME%\java\target\ (create this directory if it does not exist). That's it.

Building the project

This needs Java Development Kit (JDK, not JRE) 8 or higher and Maven.

Important

Please see the notes about Java 17 above.

In a Windows command line terminal execute:

>cd %MD2HTML_HOME%\java

>release.bat

On a Unix-like system execute:

$ cd $MD2HTML_HOME/java
$ ./release

The following must be output as the process ends:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

File md2html-bin.jar must appear in the directory %MD2HTML_HOME%\java\target\.

Important

The tests and the whole build will fail if the variable MD2HTML_HOME is not set.