fragment` `` | |
escaped <code> fragment | `escaped <code> fragment` | 1
deleted | `deleted` | 2
inserted | `inserted` | 2
stricken through | `stricken through` | 3
Normal textsubscript | `Normal textsubscript` | 3
Normal textsuperscript | `Normal textsuperscript` | 3
--- (em-dash, `—`) | `---` | |
!!! note "Comments"
1. This method was used as a workaround for preventing conflicts with the plugin markers
preprocessing. As for now, there's
[the "ignore" plugin](#ignore_plugin) that is easier to use.
2. Special markdown syntax for inserted (`++inserted++`) and deleted (`~~deleted~~`)
text is not activated in this program. First, these effects must not be required very
often. Second, such markup may cause problems if we write text like "C++", or `++i`.
The used direct HTML markup lets achieve these effects more safely.
3. Stricken through text, subscript and superscript are not in the Markdown syntax.
Here direct HTML markup is used as a possible workaround.
----------------------------------------------------------------------------------------------------
# Horizontal line
Horizontal line (`
`) may be inserted by placing several dashes (`----`).
----------------------------------------------------------------------------------------------------
# Paragraphs and line breaks
A paragraph (``) is inserted by an empty line.
A line break (`
`) 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 `
` to `` respectively. Other ways are described
[here](https://daringfireball.net/projects/markdown/syntax#header).
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 {id=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](#headers) found on the page.
!!! note "Notes"
1. Unfortunately by now there's no way to insert a local ToC, i.e. a ToC for a certain header
that would contain only the sub-headers of this header.
1. The Python and the Java versions give slightly different ToC appearance. The Java version
preserves the header text formatting while the Python version removes this formatting. So
if a header contains e.g. an `inline code block` the Python version will reflect this
code block as unformatted text in the corresponding ToC item.
----------------------------------------------------------------------------------------------------
# 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:
````
````
that will make the link text equal the link location.
!!! tip
[The "page-links" plugin](#page_links_plugin) may be used for creating
relative internal links within the documentation.
[*Attribute lists*](#attribute_lists) may be used with links the following ways:
- `[Some title](https://some.url.org){attributes}`
- `{attributes}`
The following classes are defined in the provided CSS:
Link example | Attributes
----|-----
[HTML class Attribute](https://www.w3schools.com/html/html_classes.asp){.external} | `{.external}`
[HTML 4.0 Specification (PDF)](https://www.w3.org/TR/1998/REC-html40-19980424/html40.pdf){.doc} | `{.doc}`
A picture is inserted the following ways:
- `` --- the simplest form;
- `` --- 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:
````
Here is the text that must wrap around the image on the left.
````
!!! important
The image tag is enclosed by a paragraph that is required for the currently used styles.
The Python version does this enclosing itself, but the Java version does not. Though the
Python version does not do extra enclosing if it's already done. So it's better to always
add the paragraph.
!!! note
This example also uses a path substitution ``.
See ["relative-paths" plugin](#relative_paths_plugin) for more details.
To stop the text float the `` HTML element was used.
An image may be used as a link text like this:
````
[](page.html)
````
Then we will get a clickable image that works as a link:
[](https://en.wikipedia.org/wiki/Penrose_tiling "Penrose")
When an image is too wide we may want it to fit into the page width.
[*Attribute lists*](#attribute_lists) may be used for this with the following classes defined
in the provided CSS:
````
{.w-fit .img-frame}
````
The result is:
{.w-fit .img-frame}
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:
{#fake_image}
{.img-frame width=285px} --- for the [light scheme](#fake_image).
{.img-frame width=285px} --- for the [dark scheme](#fake_image).
And here how it's done:
````
{.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*](#themes), some images may not look well on a dark background.
Such images may be marked the following way:
````
````
Alternatively the class `light_only` may be added to the `![]()
` 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](#images_on_dark_background_example).
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 ``, 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 ``, 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__ _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 `blockquote`s:
>
> - Here's a link with a clickable image:
> [](#anchor_demo "How to add an anchor.")
> - 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:
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
In this example, using [*attribute lists*](#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 `` 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:
````
````
Will give the following table style:
|Item No | Name | Description | Price |
|:------:|:------|:--------------|------:|
|1 | Chair | Kitchen chair | 87.50|
|2 | Table | Kitchen table | 450.00|
|3 | Lamp | Standard lamp | 120.75|
If we want a table without a header, we can use:
````
| | | | |
|---:|---: |---: |---: |
| 10 | 20 | 30 | 40 |
| 50 | 60 | 70 | 80 |
| 90 | 100 | 110 | 120 |
````
This will give:
| | | | |
|---:|---: |---: |---: |
| 10 | 20 | 30 | 40 |
| 50 | 60 | 70 | 80 |
| 90 | 100 | 110 | 120 |
We also can combine the CSS classes like this:
````
````
| | | | |
|---:|---: |---: |---: |
| 10 | 20 | 30 | 40 |
| 50 | 60 | 70 | 80 |
| 90 | 100 | 110 | 120 |
----------------------------------------------------------------------------------------------------
# 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:
````text
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`):
````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`):
````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](#other_fenced_block_styles).
!!! note
Program language source code syntax highlighting is not implemented yet.
> Fenced blocks may be inserted inside other blocks, like `blockquote`s:
>
> ````shell
> $ echo Fenced blocks inside a blockquote
> Fenced blocks inside a blockquote
> ````
>
> Also, for instance, lists inside `blockquote`s 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:
````wrapped-code
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:
````code
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
!!! note
As for now, there's [the "ignore" plugin](#ignore_plugin) that is easier
to use. So the following method must be needed less often.
The following code may be used in order to avoid plugin substitutions:
````
````
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:
`````
Sample.java
````code
...
System.out.println("This block demonstrates " +
"a source code in a program language.");
...
````
`````
The result will look like this:
Sample.java
````code
...
System.out.println("This block demonstrates " +
"a source code in a program language.");
...
````
!!! note
A link may be inserted inside the `` but due to specific Markdown processing this link
may be defined only using pure HTML.
## The other fenced block styles {#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.
py
````py
def factorial(n):
if n == 0:
return 1
return factorial(n - 1) * n
````
java
````java
BiPredicate bp1 = String::startsWith;
System.out.println(bp1.test("abcde", "abc")); // true
````
kt
````kt
val bp1: BiPredicate = BiPredicate { str, prefix -> str.startsWith(prefix) }
println(bp1.test("abcde", "abc")) // true
````
c
````c
#include
int main(void) {
printf("hello, world\n");
}
````
cpp
````cpp
#include
int main() {
std::cout << "Hello, world!\n";
}
````
js
````js
let testSuite = [
{label: "Summing zeros", body: () => {return sum(0, 0) == 0}},
{label: "Summing non-zeros", body: () => {return sum(1, 1) == 2}}
]
````
sql
````sql
create table employee (
dept_id int,
employee_id int primary key,
salary decimal
);
````
alg
````alg
DFS(s): // s is the starting node
mark s as explored
for each unexplored neighbor v of s:
DFS(v)
````
xml
````xml
junit
junit
3.8.1
test
````
html
````html
Hello world!
Hello
Hello world!
````
css
````css
pre>code, div.code {
display: block;
white-space: pre;
padding: 10px;
overflow-x: auto;
}
````
json
````json
{
"name": "Kitchen chair",
"price": 87.5,
"available": true
}
````
ini
````ini
[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"
````
prop
````prop
# 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
````
jaml
````jaml
services:
frontend:
image: example/webapp
networks:
- front-tier
- back-tier
````
Here is a configuration of some other kind:
conf
````conf
UAT_DB =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = UATSERVER)(PORT = 1521))
)
(CONNECT_DATA =
(SERVICE_NAME = UAT_DB)
)
)
````
unixscript
````unixscript
#!/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}"
````
bash
````bash
#!/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"
````
cmd
````cmd
@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
````
bat
````bat
@echo off
echo BAT and CMD files are considered to be the same.
````
unixshell
````unixshell
$ for i in {1..6..2}; do echo "Welcome person #$i!"; done
Welcome person #1!
Welcome person #3!
Welcome person #5!
````
winshell
````winshell
>cd %TEMP%
>echo I write a file > temp_file.txt
>type temp_file.txt
I write a file
````
shell-error
````wrapped-shell-error
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
!!! info
Admonitions are specially formatted blocks whose purpose is drawing attention to some pieces
of information. To add such a block the following syntax is used:
````
!!! qualifier "Optional title"
block content
with 4 space indent on each line
````
!!! note
There are defined the following qualifiers:
- `note`;
- tips: `tip`, `hint`, `important`;
- danger: `danger`, `error`;
- warning: `warning`, `attention`, `caution`.
!!! important
Other qualifiers may be used (like `info` qualifier above). CSS need to be edited to
add special formatting for this admonitions, otherwise the default formatting is used.
!!! warning "Don't overuse!"
This highlighting method should not be overused. If there are a lot of such blocks then
important information may be easily missed by the reader.
BTW, in this block a custom title is used.
!!! hint ""
To place an admonition without a header empty quotes may be set as the title:
````
!!! hint ""
This admonition will not have a title.
````
!!! danger
Admonitions are not supported in GitHub and StackOverflow.
!!! note
When a default title is used, its first character is capitalized.
----------------------------------------------------------------------------------------------------
# Attribute lists {#attribute_lists}
Attribute lists let add attributes to HTML tags. More details may be found at:
- [Attribute Lists extension](https://python-markdown.github.io/extensions/attr_list/)
for the Python library;
- [Attributes Extension](https://github.com/vsch/flexmark-java/wiki/Extensions#attributes)
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:
````
Header title
````
!!! important
Mind the space between the header title and the opening curly brace `{` --- it's mandatory.
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](#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:
````html
Paragraph content.
- List item 1
- List item 2
````
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.
!!! note
To make the document be rendered similarly in the Python and the Java versions, it's better
to follow the examples above. See the above links at the extensions (libraries)
descriptions.
Here's a way a table cell may be formatted:
````
Header 1 | Header 2
---------|--------
Cell 1 {style="background-color: cadetblue;"} | Cell 2 {name=cell2}
````
!!! important
Mind the space between the header title and the opening curly brace `{` --- it's mandatory.
The generated HTML code will be like this:
````html
Header 1 Header 2
Cell 1
Cell 2
````
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:
Header 1 | Header 2
---------|--------
Cell 1 {style="background-color: cadetblue;"} | Cell 2 {name=cell2}
Attribute lists may be used with images:
````
{.light_only style="border: solid orange 5px; padding: 5px;"}
````
The generated HTML code will be like this:
````wrapped-html
````
And it will look like this:
{.light_only style="border: solid orange 5px; padding: 5px"}
!!! important
The opening curly brace must follow right after the closing round brace, otherwise the
attributes will be assigned to the enclosing paragraph.
## Some useful classes defined
> If the fool would persist in his folly, he would become wise.
>
> --- *William Blake, "Proverbs of Hell"*
> {.right}
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**{.hide}?
But it still exists!_ Here's what actually was written:
````
_Do you see a **gopher**{.hide}? But it still exists!_
````