HomeInstallationUsageIndexGitHub </> Page content

Page content

About this section

This section describes documentation source text writing and covers such topics as Markdown syntax, formatting examples and tricks. The templates and styling, as well as the documentation structuring, are discussed in the other sections.

The complete Markdown guide is not provided here, so see the original syntax description for more details.

Example source texts

This documentation is written solely using the M₂H program and itself demonstrates the possible obtainable result. The source Markdown text files might be viewed using the "Source text" link ("</>") in the page title block... But not for this page. This page is generated in in two color schemes using inclusion, so the actual source text may be viewed only here.

The two versions of this page are:

• in the light color scheme;
• in the dark color scheme.

Text effects

Horizontal line

Horizontal line (<hr />) may be inserted by placing several dashes (----).

Paragraphs and line breaks

A paragraph (<p>) is inserted by an empty line.
A line break (<br />) may be inserted by leaving more than two spaces at the end of line (as it's done in the previous line).

Headers

Headers are inserted using one to six pound symbols (#) at the beginning of line. This makes headers from <h1> to <h6> respectively. Other ways are described here.

Dashes and equal signs may be interpreted as header marks of the previous line, so to avoid this markup it's better, and sometimes required, to leave an empty line before these sequences.

Table of contents

[TOC] element in the Markdown document will resolve into the document's table of contents in the generated HTML. The example can be seen at the top of this and other pages. The ToC is composed of the headers found on the page.

Links

The link syntax is:

[link text](path/to/doc.html "title")

where "title" is not required. If link text is omitted the link will be not visible. There's the other syntax:

<path/to/doc.html>

that will make the link text equal the link location.

Attribute lists may be used with links the following ways:

• [Some title](https://some.url.org){attributes}
• <https://some.url.org>{attributes}

The following classes are defined in the provided CSS:

Anchors

The header tags have their automatically generated ids so they can be referenced by the links. But these ids are uncontrolled and will change if the the header changes. Anchors may be added at the arbitrary places on the page with the syntax:

<a name="anchor_name"></a>

id attribute instead of name attribute will also work. Then this anchor may be referenced as:

[link text](#anchor_name)

from the same page, or:

[link text](this_page.html#anchor_name)

from the same or the other page.

Images

A picture is inserted the following ways:

• ![](path/to/image.png) — the simplest form;
• ![ALT](path/to/image.png "title") — with optional alternative text and hint.

The above syntax is simple enough so it's not going to be demonstrated here. Instead, the other method was used above that allows placing images on the page side with the text wrapping around. That may be very useful with small images. This method uses direct HTML inclusion:

<p><img src="<!--path pict-->target.png" class="floatRight" /></p>

Here is the text that must wrap around the image on the left.

<p style="clear: both;"></p>

To stop the text float the <p style="clear: both;"></p> HTML element was used.

An image may be used as a link text like this:

[![](../../pict/target.png)](page.html)

Then we will get a clickable image that works as a link:

When an image is too wide we may want it to fit into the page width. Attribute lists may be used for this with the following classes defined in the provided CSS:

![](<!--path pict-->wide_image.png){.w-fit .img-frame}

The result is:

The img-frame class is optional. An image may have the same background as the page and because of its content its borders may be unclear. In such cases a frame may show it explicitly. Here are the other examples:

— for the light scheme.

— for the dark scheme.

And here how it's done:

![](<!--path pict-->light_fake_text.png){.img-frame width=285px}

There's one point that should be taken into account when working with images. Often images are intended to be shown on a light background. If we use a dark theme, some images may not look well on a dark background. Such images may be marked the following way:

<div class="light_only"></div>

![](path/to/image.png)

Alternatively the class light_only may be added to the <img> HTML tag. In dark themes these images may be put on a white background (particularly, this is defined in the dark theme).

Here is an example:

The first picture has thin black elements (arms, hands, feet and hair) that don't look well on the dark background. The second picture has local white underlying plate and probably looks better.

Lists

The following markup:

1. This is a __first-level__ _ordered_ list item.

    Another paragraph may be added by adding one empty line above and indenting by 4 spaces.

    > Other elements, like `<blockquote>`, may be included into a list item.

    - This is a __second-level__ _unordered_ list sub-item. The long lines may be wrapped
        with extra 4 space indent without an empty line above.
        3. This is a __third-level__ _ordered_ list sub-item. Any numbers may be used as
            _ordered_ list item markers.
        3. This is another __third-level__ _ordered_ list sub-item.
    - This is another __second-level__ _unordered_ list sub-item.

1. This is another __first-level__ _unordered_ list item. Though `1.` is used as the
    item number this item marker will be "2.".

gives the following output:

1. This is a first-level ordered list item.

   Another paragraph may be added by adding one empty line above and indenting by 4 spaces.

   Other elements, like <blockquote>, may be included into a list item.

   • This is a second-level unordered list sub-item. The long lines may be wrapped with extra 4 space indent without an empty line above.
     1. This is a third-level ordered list sub-item. Any numbers may be used as ordered list item markers.
     2. This is another third-level ordered list sub-item.
   • This is another second-level unordered list sub-item.

2. This is another first-level ordered list item. Though 1. is used as the item number this item marker will be "2.".

Blockquotes

Blockquotes are inserted by starting each line with >.

Links, images and some other Markdown elements may be used inside blockquotes:

• Here's a link with a clickable image:
  
• Also a list inside this blockquote is used for demonstration.

Tables

Tables are added with the syntax like this:

Item No | Name  | Description   | Price
:------:|-------|---------------|------:
1 {.th} | Chair | Kitchen chair |  87.50
2 {.th} | Table | Kitchen table | 450.00
3 {.th} | Lamp  | Standard lamp | 120.75

Currently used styles define the following default table appearance:

In this example, using attribute lists we specify the class {.th} that makes the table sidebar have the same format as the table header. The class .th is defined in the provided CSS.

Markdown doesn't have syntax for different table styles, but some trick may be used to achieve this. We can add an invisible element (an empty <div> in this case) right before the table and then define the appearance using some simple CSS magic. So the following invisible element right before a table:

<div class="tableLight"></div>

Will give the following table style:

If we want a table without a header, we can use:

<div class="tableHeaderless"></div>

| | | | |
|---:|---: |---: |---: |
| 10 | 20  | 30  | 40  |
| 50 | 60  | 70  | 80  |
| 90 | 100 | 110 | 120 |

This will give:

We also can combine the CSS classes like this:

<div class="tableLight tableHeaderless"></div>

Fenced code blocks

Fenced code blocks may be set up by four-space indent, or by four backticks (````), i.e. the following markup:

````
Example of
    preformatted 
    text
````

will look like:

Example of
    preformatted 
    text

This type of block visually correlates with inline code fragments.

Style may be specified the following way:

````text
This is a light code block example.
    It is also preformatted
    but has no background (and probably no border).
````

The result will be:

This is a light code block example.
    It is also preformatted
    but has no background (and probably no border).

There are also the following block types.

Shell code block (marked as shell):

>>> print("This may be any shell where Python IDLE works.")
This may be any shell where Python IDLE works.

Program language code block (marked as code):

System.out.println("This block demonstrates " + 
    "a source code in SOME program language.");

The above are the basic code blocks styles defined by default. The other styles will be discussed later.

Fenced blocks may be inserted inside other blocks, like blockquotes:

$ echo Fenced blocks inside a blockquote
Fenced blocks inside a blockquote

Also, for instance, lists inside blockquotes may contain fenced code blocks:

• Item 1:

  Fenced block, line 1
  Fenced block, line 2

• Item 2

Wrapping

Sometimes it's required to have long lines inside code blocks wrapped, but the above code blocks don't wrap the lines automatically. Of cause we can break the lines manually but this may make the content inconvenient for copy-pasting. To address this cases, additional markers wrapped, wrapped-code and wrapped-shell were defined. Here's an example:

This is a long line that doesn't contain line breaks inside itself and that we want to be automatically wrapped so that the fenced code block is not scrolled.

Just for comparison, a similar content will be scrolled in not wrapped fenced blocks:

This is a long line that doesn't contain line breaks inside itself and that we want to be scrolled so that the fenced code block doesn't exceed the page width.

Using HTML

The following code may be used in order to avoid plugin substitutions:

<div class="code">![](&lt;!--path pict--&gt;logo.png)</div>

The result will be like this:

Fenced block source specification

Sometimes it's useful to specify the file or some other source of the code inside the fenced block. This may be done the following way:

<div class="blockSrc">Sample.java</div>

````code
...
System.out.println("This block demonstrates " + 
    "a source code in a program language.");
...
````

The result will look like this:

...
System.out.println("This block demonstrates " + 
    "a source code in a program language.");
...

The other fenced block styles

The following is the extended set of fenced block styles that are enabled by default but may be disabled by setting the variable "add_more_prog_langs": false in the argument file. If the writing work does not need these styles, disabling them may give slightly faster pages rendering in the browser.

The corresponding markers are shown under the blocks.

def factorial(n):
    if n == 0:
        return 1
    return factorial(n - 1) * n

BiPredicate<String, String> bp1 = String::startsWith;
System.out.println(bp1.test("abcde", "abc")); // true

val bp1: BiPredicate<String, String> = BiPredicate { str, prefix -> str.startsWith(prefix) }
println(bp1.test("abcde", "abc")) // true

#include <stdio.h>

int main(void) {
    printf("hello, world\n");
}

#include <iostream>

int main() {
    std::cout << "Hello, world!\n";
}

let testSuite = [
    {label: "Summing zeros",      body: () => {return sum(0, 0) == 0}},
    {label: "Summing non-zeros",  body: () => {return sum(1, 1) == 2}}
]

create table employee (
    dept_id      int,
    employee_id  int primary key,
    salary       decimal
);

DFS(s): // s is the starting node
    mark s as explored 
    for each unexplored neighbor v of s:
        DFS(v) 

<dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>3.8.1</version>
    <scope>test</scope>
</dependency>

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>Hello world!</title>
    </head>
    <body>
        <h1>Hello</h1>
        <p>Hello world!</p>
    </body>
</html>

pre>code, div.code {
    display: block;
    white-space: pre;
    padding: 10px;
    overflow-x: auto;
}

{
    "name": "Kitchen chair",
    "price": 87.5,
    "available": true
}

[owner]
name = John Doe
organization = Acme Widgets Inc.

[database]
; use IP address in case network name resolution is not working
server = 192.0.2.62     
port = 143
file = "bom.dat"

# A .properties file example
website=https://en.wikipedia.org/
language:English
# Keys with the same name will be overwritten by the key that is the furthest in a file
duplicateKey = first
duplicateKey = second

services:
  frontend:
    image: example/webapp
    networks:
      - front-tier
      - back-tier

Here is a configuration of some other kind:

UAT_DB =
  (DESCRIPTION =
    (ADDRESS_LIST =
      (ADDRESS = (PROTOCOL = TCP)(HOST = UATSERVER)(PORT = 1521))
    )
    (CONNECT_DATA =
      (SERVICE_NAME = UAT_DB)
    )
  )

#!/bin/sh
if [ -z $1 ]; then
    echo a{1,2,3}
else
    echo b{5,6,7}
fi
# will output: "a{1,2,3}" or "b{5,6,7}"

#!/bin/bash
if [ -z $1 ]; then
    echo a{1,2,3}
else
    echo b{5,6,7}
fi
# will output: "a1 a2 a3" or "b5 b6 b7"

@echo off

set CANNOT_PROCEED=
call :check_file_or_dir doc_src
if [%CANNOT_PROCEED%]==[Y] (
    echo Some problems found (see above^). Nothing has been done
    exit /b
)
xcopy %MD2HTML_HOME%\bin\new_project\doc_src doc_src\ /e
exit /b

:check_file_or_dir
if exist %1 (
    echo File or directory '%1' already exists
    set CANNOT_PROCEED=Y
)
exit /b

@echo off
echo BAT and CMD files are considered to be the same.

$ for i in {1..6..2}; do echo "Welcome person #$i!"; done
Welcome person #1!
Welcome person #3!
Welcome person #5!

>cd %TEMP%

>echo I write a file > temp_file.txt

>type temp_file.txt
I write a file

Exception in thread "main" java.lang.IllegalArgumentException: Cannot invoke beanutilsdemo.MyBean.setEnumValue on bean class 'class beanutilsdemo.MyBean' - argument type mismatch - had objects of type "java.lang.String" but expected signature "beanutilsdemo.MyEnum"

Admonitions

!!! qualifier "Optional title"
    block content
    with 4 space indent on each line

!!! hint ""
    This admonition will not have a title.

Attribute lists

Attribute lists let add attributes to HTML tags. More details may be found at:

• Attribute Lists extension for the Python library;
• Attributes Extension for the Java library.

The above libraries have some differences in their interpretation, so Python and Java versions may work differently. The below are the usage examples that must work the same way.

The following header:

# Header title {#custom_id}

will be converted into something like:

<h1 id="custom_id">Header title</h1>

Alternatively an ID may be assigned by expression {id=custom_id} or {id='custom_id'} or {id="custom_id"}.

This id will be also set in the corresponding table of contents item.

A paragraph and a list item may be styled by assigning CSS classes like this:

Paragraph content.
{ .blue .underlined }

- List item 1
    { class=blue }
- List item 2
    { class='green' }

The generated HTML will be like:

<p class="blue underlined">Paragraph content.</p>
<ul>
<li class="blue">List item 1</li>
<li class="green">List item 2</li>
</ul>

As we can see, a dot . may be replaced by class= with optional single or double quotes. Also note that the attributes must be specified at a separate line in the end of the element.

Here's a way a table cell may be formatted:

Header 1 | Header 2
---------|--------
Cell 1 {style="background-color: cadetblue;"} | Cell 2 {name=cell2}

The generated HTML code will be like this:

<table>
<thead>
<tr><th>Header 1</th><th>Header 2</th></tr>
</thead>
<tbody>
<tr>
<td style="background-color: cadetblue;">Cell 1</td>
<td name="cell2">Cell 2</td>
</tr>
</tbody>
</table>

In this example an arbitrary attribute name=cell2 is added. This may be done for other elements as well. Single or double quotes may be used, and ether of them must be used if the attribute value contains spaces. Of cause alternatively a class might be assigned instead of the direct CSS parameters.

The table will look like this:

Attribute lists may be used with images:

![](../../pict/light_only.png
){.light_only style="border: solid orange 5px; padding: 5px;"}

The generated HTML code will be like this:

<img alt="" class="light_only" src="../../pict/light_only.png" style="border: solid orange 5px; padding: 5px;">

And it will look like this:

Some useful classes defined

If the fool would persist in his folly, he would become wise.

— William Blake, "Proverbs of Hell"

The source of the above quote is aligned to the right. Here's how it is done:

> If the fool would persist in his folly, he would become wise.
> 
> --- *William Blake, "Proverbs of Hell"*
> {.right}

In some cases an element must be hidden. For example: Do you see a gopher? But it still exists! Here's what actually was written:

_Do you see a **gopher**{.hide}? But it still exists!_