<!--VARIABLES {"title": "Installation", "SORT_ORDER": "040", "code": "installation"}--> 

[TOC]

----------------------------------------------------------------------------------------------------
<a id="installation_all"></a>
# Common steps

This program doesn't have any installer and is installed according to the principle 
*unpack-and-run*:

- Put (or clone from the VCS) the unpacked directory `md2html` to the directory by choice.
- Define the `MD2HTML_HOME` environment variable as the absolute path of the directory `md2html`.
- Follow further specific steps for:
    - [Python version](#installation_python) and
    - [Java version](#installation_java)
- For Windows, file explorer context menu items may be added, see
    [here](<!--page usage-->#win_explorer_context_menu).

!!! tip
    After the program is installed, before further reading, you may go to the
    [Quick start section](<!--page quick_start-->) and try out the program.

----------------------------------------------------------------------------------------------------
<a id="installation_python"></a>
# Python version

## Prerequisites

This program requires [Python 3](https://www.python.org/) runtime that can be installed in 
different ways. Here is a short instruction for a typical installation on Windows. 

!!! note
    Again, this is just one of the methods intended mainly for less experienced users and those
    who want to save the time. Other installation methods will most likely work as well.

The installer file name is `python-3.8.7-amd64.exe` (or choose the other one applicable to your
platform). Only the following option (1) must be changed:

![](<!--path pict-->install_python_3_8.png)

Nothing else should be changed in this and the subsequent dialogs.

The following command may be used to check whether Python is installed.

````shell
>python --version
Python 3.8.7
````

!!! note "Notes"
    1. Later versions of Python will very probably be suitable too but they were not completely
        checked.
    2. In Linux the `python` command is probably used for running Python 2 that does not suffice 
        for this program. Python 3 may need to be installed separately and called with 
        command `python3`.

The following Python packages must be installed:

````wrapped-shell
>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 reason. Future versions of the
    packages may have changes that noticeably affect the program work.


## Installation

Here's how the Python version may be installed:

- Fulfill the [common steps](#installation_all).
- That's it, provided that the prerequisites are matched.

----------------------------------------------------------------------------------------------------
<a id="installation_java"></a>
# Java version

## Prerequisites

Java runtime (JRE) 8 or higher. The following command may be used to check whether Java is 
installed.

````shell
>java -version
java version "1.8.0_05"
.  .  .
````

## Installation

Here's how the Java version may be installed:

- Fulfill the [common steps](#installation_all).
- 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 latest built release must be available along with the source code. A release is a file named
`md2html-bin.jar`. Download this file 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](https://maven.apache.org/).

In a command line terminal execute:

````shell
>cd %MD2HTML_HOME%\java

>release.bat
````

The following must be output as the process ends:

````shell
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
````

File `md2html-bin.jar` must appear in the directory `%MD2HTML_HOME%\java\target\`.

!!! note
    __Note.__ The tests and the whole build will fail if the variable 
    [`MD2HTML_HOME`](#installation_all) is not set.