[TOC] ---------------------------------------------------------------------------------------------------- # About this section This section describes running the program and configuring writing projects. Content writing, formatting, and structuring are described in the other sections. ---------------------------------------------------------------------------------------------------- # Cross-platform The Java and the Python executables are platform-independent, so they should work in all environments where the corresponding runtimes are installed. The program was tested on: - Windows - Ubuntu Linux - macOS The examples in this documentation are mostly given for Windows, but they may be easily adapted for Unix-like platforms. Some Unix-specific notes are provided when required. ---------------------------------------------------------------------------------------------------- # Command line syntax A simple usage example for the Python version is: ````shell >python %MD2HTML_HOME%/python/md2html.py -i test.txt ```` and for the Java version is: ````shell >java -jar %MD2HTML_HOME%/java/target/md2html-bin.jar -i test.txt ```` Both commands will convert file `test.txt` into file `test.html` using default parameters. !!! note The above commands illustrate the main idea of the program usage, but more convenient ways are described below in this section. The program has many more command line options that are listed and described on the [reference page](#command_line_syntax). There are two ways to use the program: - [With command line arguments](#using_command_line_arguments) - [With an argument file](#using_argument_file) ---------------------------------------------------------------------------------------------------- # Using command line arguments This mode accepts all required parameters in the command line and allows processing one document per run (unless the [GLOB](#input_glob) argument is used). It's selected when the `--argument-file` argument is not specified. ---------------------------------------------------------------------------------------------------- # Using argument file {#using_argument_file} The `--argument-file` argument defines the **argument file** that will be used for processing. Here's the example that executes the argument file with name `md2html_args.json`: ````shell >python %MD2HTML_HOME%/python/md2html.py --argument-file md2html_args.json ```` The *argument file* allows defining: - multiple files to be processed; - the same parameters that can be specified in the command line; - some additional parameters; - extended processing using *plugins*. Here is a very simple example of an _argument file_: ````json { "documents": [ { "input": "index.txt", "title": "Home" }, { "input": "about.txt", "output": "about.html", "title": "About" } ] } ```` It's similar to using command line arguments, except it defines several documents to process. A more complex example and the _argument file_ structure are described in the [reference page](#argument_file_structure). !!! note The command line and the _argument file_ may specify different values for the parameters that mean the same (sometimes they have different names). In this case the command line arguments will **override** the corresponding parameters in the _argument file_. ---------------------------------------------------------------------------------------------------- # Command scripts {#command_scripts} The program versions (Python and Java) are supposed to work independently and require only their corresponding runtime. For example, the Java version should work even if there's no Python in the environment where it runs. For different auxiliary purposes, command scripts for Windows and Unix-like platforms are used. Here are the scripts that run the program: For Windows | For Unix-like | Description ------------------------|---------------------|-------------------------------- `generate_doc_py.bat` | `generate_doc_py` | Uses the Python version `generate_doc_java.bat` | `generate_doc_java` | Uses the Java version The Windows versions may be run by double-clicking in Windows Explorer. The Linux *Bash script* versions may need special environment adjustments (depending on the Linux distribution) to behave the same way. In Ubuntu these scripts were tested only in the command line terminal. These scripts execute the _argument file_ `md2html_args.json` in the current working directory. When double-clicked in Windows, they will open a command window and close it when they successfully complete. If there are errors, the command window will stay open with the information and error messages displayed. These scripts are very small and intended to be copied to a project's directory where they will process the project's _argument file_ (see the [recommended project structure](#typical_project_structure)). ---------------------------------------------------------------------------------------------------- # Windows Explorer context menu integration {#win_explorer_context_menu} The program may be integrated into the Windows Explorer context menu: ![WINDOWS_EXPOLORER_CONTEXT_MENU](windows_context_menu.png) This may be a quick and convenient way to convert single documents. The "no prompt" version generates HTML from the selected file with default options. It leaves the command window open only in case of errors. The other version opens a command line window and allows redefining some options. Just pressing `Enter` will start generation with the default options. To add these context menu items, open the Windows Registry editor (press `Win`+`R`, type `regedit` and press `Enter`) and add the following keys and values: ```` [HKEY_CURRENT_USER\Software\Classes\*\shell\md2html] @="Markdown to HTML..." "icon"="\"X:\\path\\to\\md2html\\bin\\context_menu\\icon.ico" [HKEY_CURRENT_USER\Software\Classes\*\shell\md2html\command] @="\"\"X:\\path\\to\\md2html\\bin\\context_menu\\md2html_prompt.bat\" -i \"%1\"" [HKEY_CURRENT_USER\Software\Classes\*\shell\md2html_fast] @="Markdown to HTML (no prompt)" "icon"="\"X:\\path\\to\\md2html\\bin\\context_menu\\icon.ico" [HKEY_CURRENT_USER\Software\Classes\*\shell\md2html_fast\command] @="\"X:\\path\\to\\md2html\\bin\\context_menu\\md2html_prompt_fast.bat\" -i \"%1\"" ```` Here `@` stands for `(Default)` value name. `py` or `java` may be added before `-i` argument. The quotes must be set like this: ![](reg_value.png) There is a Windows command line script that automates this operation. Open a Windows console and execute: ````shell >%MD2HTML_HOME%\bin\context_menu\generate_reg_file.bat The output file is: C:\Users\user1\md2html_context_menu_integration.reg ```` Find the generated file in the user's profile directory, check and execute it (by double-click). Read the pop-up message and confirm the operation. !!! note There's no such integration for Linux and macOS. ---------------------------------------------------------------------------------------------------- # Typical project structure {#typical_project_structure} The program doesn't impose restrictions on the writing project structure. The following structure is just a suggested approach that is used in this documentation. Note that there's the [quick start script]() that automatically creates a small project with a structure like this. The following description may be used for manual project setup. ````shell $ tree -L 2 --charset=ascii --dirsfirst . |-- doc | |-- content | | |-- doc1.html | | `-- doc2.html | |-- layout | | `-- <...> | |-- pict | | |-- image1.png | | `-- image2.png | |-- themes | | `-- light | | `-- <...> | |-- favicon.png | `-- custom.css |-- doc_src | |-- templates | | `-- multipage.html | |-- doc1.txt | `-- doc2.txt |-- doc0.html |-- doc0.txt |-- generate_doc_py.bat `-- md2html_args.json ```` - `doc0.txt` and `doc0.html` are the Markdown document and its corresponding generated HTML page that we want to have in the project's root. !!! hint It may be convenient to have a starting page in the project's root directory. But this page, on the other hand, requires special manipulation, so this decision is a trade-off. - the `doc` directory along with the `doc0.html` file contains the whole project's HTML content with all required resources like images and CSS files. This directory may be used and shipped autonomously (with additional `doc0.html` file if it's used). !!! note For this documentation and projects generated by the *quick start script* this is not true. As the pages have links to their source texts, if we want these links to work, we need to ship the source texts as well. As can be seen, the `doc` directory is a ready-to-use setup containing all necessary artifacts, such as CSS, JavaScript and images. Only the HTML content needs to be generated and placed here (see below). - the `doc/content` directory is intended to contain the **generated artifacts only**. In case of issues with document generation, this directory may be safely deleted. On the following project regeneration, this directory and its content will be recreated. See also [Troubleshooting](#cleanup_and_regenerate). !!! important If unsure, please use renaming instead of deletion, or use a version control system (like Git) to avoid data loss. - the `doc_src` directory contains all source files required for producing the project's output (plus the `doc0.txt` file if we use it) - the `templates` subdirectory contains the templates used for the HTML content generation !!! note Templates are not actually user written artifacts, but they also don't belong to the `doc` directory because they are not required for the writing project viewing. Here we probably see an imperfect structure design that might be revised (and ir is planned), but still this structure is surely workable, and the users may easily redefine it in their writing projects. - `generate_doc_py.bat` --- the *double-click script* for the HTML output generation. Here the Python version is demonstrated. See [here](#command_scripts) for the other variations - `md2html_args.json` --- the project's [*argument file*](#using_argument_file); - `doc/layout` directory contains the resources that are used by the template. It's a convenient way to separate those resources from the ones that belong to the writing project content. This directory may be copied to a new project, and it will most likely work (in conjunction with the particular *template*) - `doc/themes` directory contains the [color *themes*](#themes) used by the project. More than one theme may be used at the same time - `favicon.png` file is placed here because it's considered a project artifact - `custom.css` is intended to contain the styles specific to the project (if required) ## Layout manipulation By **layout** we mean the whole set of artifacts used for generating the writing project results and not belonging to the user-created content. Applying to the [recommended project structure](#typical_project_structure) the layout artifacts are: - the whole `doc/layout` directory, except the `content` subdirectory; - the `doc/themes` directory --- only the used scheme(s) are required; - the `doc_src/templates` directory --- only the used templates are required. The layout is a relatively independent part of the **M2H** project. Currently, newer versions of the program work well with older versions of the layout. The [quick start script]() copies the layout artifacts from the **M2H** home directory to the new writing project. This approach keeps the users' projects independent of the changes made in the **M2H** project. When a newer version of **M2H** provides desired layout changes or fixes, the writing project's layout may be updated manually. Here are the suggested steps for that: - Make sure the writing project's layout was not changed. This is not recommended but there may be cases where the required results cannot be achieved without, e.g., patching the template files. In such cases the layout update will include extra steps for reapplying the local patch. These steps are not discussed here. - Commit/stash the writing project changes if a version control system (Git) is used, or at least save/rename the current layout artifacts. This is not required if losing the previous layout is not an issue. - Copy the layout files listed above from the **M2H** home directory to the new writing project --- only those that are used. - It's probably good to create a separate commit at this point, with a message like "layout updated". - Perform a full project regeneration with the `-f`/`--force` flag. - At this point it may be useful to review the changes in the HTML output files and create a separate commit for these changes, like "documentation regenerated". - Continue working with your writing project.