[TOC] ---------------------------------------------------------------------------------------------------- # Common schema

**M₂H** accepts the following artifacts as its input: - source Markdown texts; - one or several HTML templates; - one argument file; - HTML page resources. The program processes these artifacts and generates a set of static HTML pages that may represent a logically related documentation with a sidebar menu, navigation, index and other elements. The following subsections describe the above artifacts in more details.

## Source Markdown texts These texts comprise the main documentation content written by the author. They are written in the Markdown language []. The [Page content section]() describes the methods, tricks and elements that may be used in process of the content writing. ## HTML templates An HTML artifact that is generated out of a markdown text is not a complete HTML page. It's just a fragment that must be put inside the `...` HTML element. A **template** may be considered as an HTML page that doesn't have the main content but just specifies the place (placeholder) where this main content must be inserted. See [here]() for more details about templates and other placeholders that may be used in templates. ## Argument file The *argument file* defines the set of input source files and different parameters for the following HTML documents generation. See [here](#using_argument_file) for more details. ## HTML page resources Different resources, like CSS, JavaScript and images are not processed by the program. The program may just adjust the location of these resources while putting link on them into the certain pages. These are usually [plugins]() that perform these adjustments. ---------------------------------------------------------------------------------------------------- # Restrictions and security **M₂H** doesn't restrict HTML code inside the Markdown texts. Particularly, these texts may contain JavaScript that will be translated unchanged into the generated HTML page. This must not be a problem for personal use but may be a security issue when converting and publishing source texts from untrusted third-parties. Click the image below to see how it may look like. !!! tip In case of worry, first have a look at the source text by clicking at the "Source text" link ("</>") at the page top. Also you can view the HTML text (`Ctrl`+`U` in most browsers). ---------------------------------------------------------------------------------------------------- # History **M₂H** was born in about 2019 as a Python script of about 50 lines of code written in about one hour. It was used for writing notes on a computer science study course. Then this solution was used for the other writing works. As the requirements grew the solution developed up to its current state. As for the Java implementation, it appeared as the response to the lack of Python in the environment where the program was going to be used. For now the Java implementation slows down the development as it needs writing the same things in two languages, and it's considered to be abandoned sometime. Still as for now the final decision is not made and the Java implementation is fully supported. ---------------------------------------------------------------------------------------------------- # Alternative solution Among other static site generators "Pelican" [] may be called as quite close to **M₂H** by its functionality though being more mature and feature-rich. It uses the same Python-Markdown module [] and has a similar motivation, see [Some history about Pelican](https://docs.getpelican.com/en/stable/report.html). Still **M₂H** has some unique features and its relative simplicity may be seen as an advantage.