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 of now, there is
[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 text like "C++" or `++i` is used.
Direct HTML markup allows these effects to be achieved 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 a 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}
The `[TOC]` element in the Markdown document resolves 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 not be visible.
There is another syntax:
````
````
that makes the link text equal to the link location.
!!! tip
[The "page-links" plugin](#page_links_plugin) may be used for creating
relative internal links within the writing project.
[*Attribute lists*](#attribute_lists) may be used with links in the following ways:
- `[Some title](https://some.url.org){attributes}`
- `{attributes}`
The following classes are defined in the provided CSS to indicate link kinds
([light scheme](#link_markers),
[dark scheme](#link_markers)):
{#link_markers}
Link example | Attributes
----|-----
[HTML class Attribute](https://www.w3schools.com/html/html_classes.asp){.away} | `{.away}`, `{.external}` \*
[HTML 4.0 Specification (PDF)](https://www.w3.org/TR/1998/REC-html40-19980424/html40.pdf){.doc} | `{.doc}`
The wrapping paragraph test.
````
The `![]()
` tag is enclosed into 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 already exists. So it's better
to always add the paragraph.
## Fit inside and framing
When an image is too wide, we may want to fit it 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}
````
## Image expanding
If an image is large enough but not expected to be observed often, it may be good to place an icon
on the page and make it expandable on click. A relatively complex JavaScript solution may be
implemented, but it's not yet done here. Anyway there's a simpler alternative that may be
sufficient in some cases:
[{width=160px}](wide_image.png
"Click to expand"){target=_blank}
Clicking the icon opens the image in a separate tab. Here's how this can be done:
````
[{width=160px}](wide_image.png
"Click to expand"){target=_blank}
````
## Color theme and images
One point should be taken into account when working with images. Often images are
intended to be shown on a light background. If a [*dark theme*](#themes)
is used, some images may not look well in the dark.
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:
[light scheme](#images_on_dark_background_example) |
[dark scheme](#images_on_dark_background_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 a 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, we use [*attribute lists*](#attribute_lists) to 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 a simple trick may be used to achieve
this. An invisible element (an empty `` in this case) can be added right before the table,
and the appearance can then be defined with a small 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 |
It is also possible to 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 is required to have long lines inside code blocks wrapped, but the above code blocks
don't wrap the lines automatically. Of course, lines can be broken manually, but this may make the
content inconvenient for copy-pasting. To address these 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 non-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 of now, there is [the "ignore" plugin](#ignore_plugin) that is easier
to use, so the following method is expected to 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
The following qualifiers are defined:
- `note`;
- tips: `tip`, `hint`, `important`;
- danger: `danger`, `error`;
- warning: `warning`, `attention`, `caution`.
!!! important
Other qualifiers may be used (like `info` qualifier above). CSS needs to be edited to
add special formatting for these admonitions, otherwise the default formatting is used.
!!! warning "Don't overuse!"
This highlighting method should not be overused. If there are many such blocks, then
important information may be easily missed by the reader.
In this block, a custom title is used.
!!! hint ""
To place an admonition without a header, empty quotes may be used 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 allow adding 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 examples below are expected to work the same way.
The following header:
````
# Header title {#custom_id}
````
will be converted into something like:
````
Header title
````
!!! important
Note 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 also be 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 shown above, a dot `.` may be replaced by `class=` with optional single or double quotes.
Also note that attributes must be specified on a separate line at 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.
A table cell can be formatted as follows:
````
Header 1 | Header 2
---------|--------
Cell 1 {style="background-color: cadetblue;"} | Cell 2 {name=cell2}
````
!!! important
Note the space between the cell content 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 either of them *must* be used if the attribute
value contains spaces. Of course, 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!_
````