<!--VARIABLES {"title": "Installation", "SORT_ORDER": "040", "code": "installation"}--> 

[TOC]

----------------------------------------------------------------------------------------------------
<a id="installation_all"></a>
# 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](#installation_python) and
    - [Java version](#installation_java)
- On Windows, Windows 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 a [Python 3](https://www.python.org/) runtime. See 
[here](<!--page reference-->#python_runtime_installation) for installation instructions
(if required).

The following command may be used to check whether Python is installed:

````shell
>python --version
Python 3.8.7
````

!!! note
    1. 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.
    2. On Unix-like systems, the `python3` command should be used instead of `python`.

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
    1. 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.
    2. (Optional) Consider a
        [Python virtual environment](https://docs.python.org/3.8/library/venv.html)
        (`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](#installation_all) are fulfilled and 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"
.  .  .
````

!!! important
    <a name="java_17_incompatible"></a>
    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](#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 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](https://maven.apache.org/).

!!! important
    Please see the notes about Java 17 [above](#java_17_incompatible).

In a Windows command line terminal execute:

````shell
>cd %MD2HTML_HOME%\java

>release.bat
````

On a Unix-like system execute:

````unixshell
$ cd $MD2HTML_HOME/java
$ ./release
````
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\`.

!!! important
    The tests and the whole build will fail if the variable
    [`MD2HTML_HOME`](#installation_all) is not set.