Introduction

Markdown is a lightweight markup language that can be used to add formatting elements to text documents. It is Markdown, with some of its own modifications, that is used by the TheHost team to write our materials.

This technical guide is intended to introduce the Markdown elements and TheHost standards for their use. Using standardized markup will help you write articles faster and make them more intuitive and readable for future readers.

We will use new and new Markdown elements, the definition and standard for which we will describe as we get acquainted with the material.

Markdown Basics

Headings

Markdown supports the use of several levels of headings. TheHost standard uses two of them – H2 and H3, which mark topics and subtopics of the material, respectively.

Their usage looks like this:

## Important main topic
### Still important subtopic #1
### Still important subtopic #2
## Important main topic, second step

Which is transformed into the following:

For more details on the formation of the structure, see the General Guidelines.

Each H2 and H3 heading forms a clickable hyperlink to the right of its title. This hyperlink can then be given to a potential reader so that he can open the material immediately on the desired subtopic. Keep this in mind!

Text formatting

Markdown allows you to use _italic_, **bold**, __underlined__ and ~~strikethrough~~ text.

It looks like this:

Markdown allows you to use italics, bold, underlined and strikethrough text.

However, according to the current TheHost standard, you will have to use mostly bold text format.

Bold should be used to highlight:

• Names of information that is important for understanding the material, such as buttons used in step-by-step instructions:

… in the upper right corner, click Repeat…

• First mention of proper names or terms, such as the protocol that the material is written about:

SSH – cryptographic protocol…

• As a separator between paragraphs that are part of a single heading and whose division into separate headings is not inappropriate:

For export, do… For import, do…

• As a highlight when using many other elements, such as collouts (more on that later):

Advice: read this article to the end.

• List numbering, for example in step-by-step instructions:

1. Step one…

2. Step two…

• And also to highlight other important phrases in the article if there is an urgent need:

The main thing in bold is to keep it in moderation.

Lists

Above, we used the unnumbered list element. In Markdown, it looks like this:

* First.
* Second.

Or, a list can be numbered:

1. Second?
2. First!

Which in practice will look like this:

• First.
• Second.

1. Second?
2. First!

Their use is intuitive: you will need numbering if you need to number a list (step-by-step instructions). In case of listing without any structure, use a list without numbers.

According to the current standard, lists should end with a period, semicolon, or other sentence-ending marks.

Quotes

Usage is as simple as possible:

>Very Important Quote
>> From **Very** Important Document

Quotes according to the current standard are used when citing, mainly related to legal information or technical documentation. Quotes support inline and standard formatting, but using both is not recommended:

Very Important Quote

From Very Important Document

Inline

Inline is another way to `highlight text`.

Inline is another way to highlight text. Yellow highlighting is achieved by framing the text with <^> symbols.

According to the standard, it is used to highlight variables, mention commands outside code blocks, and technical information such as plugin names that is too abundant in the text to be bolded.

As you can see, allows to highlight formatted text in various combinations. Text formatting is supported by inline, but it should be done outside the markup:

**`Bold`** and _`italic`_.

Bold and italic.

An important aspect of inline is the ability to use it inside code blocks, which we will discuss later.

Tables

If necessary, describe in detail how to create a table with a custom number of tables and columns:

| Tables | are also | supported | Markdown | and | will | adapt | to | the | size | of the | page |
|--------|--------|----------|---------|---------|---------|---------|---------|
| col 1 | col 2 | col 3 | col 4 | col 5 | col 6 | col 7 | col 8 | col 9 | col 10 |
| col 1 | col 2 | col 3 | col 4 | col 5 | col 6 | col 7 | col 8 | col 9 | col 10 |
| col 1 | col 2 | col 3 | col 4 | col 5 | col 6 | col 7 | col 8 | col 9 | col 10 |
| col 1 | col 2 | col 3 | col 4 | col 5 | col 6 | col 7 | col 8 | col 9 | col 10 |
| col 1 | col 2 | col 3 | col 4 | col 5 | col 6 | col 7 | col 8 | col 9 | col 10 |

| Tables | are | also | supported | Markdown | and | will | adapt | to | the | size | of the | page | |--------|-------|---------|---------|---------|----------|----------|---------|---------| | Col 1 | Col 2 | Col 3 | Col 4 | Col 5 | Col 6 | Col 7 | Col 8 | Col 9 | Col 10 | | Col 1 | Col 2 | Col 3 | Col 4 | Col 5 | Col 6 | Col 7 | Col 8 | Col 9 | Col 10 | | Col 1 | Col 2 | Col 3 | Col 4 | Col 5 | Col 6 | Col 7 | Col 8 | Col 9 | Col 10 | | Col 1 | Col 2 | Col 3 | Col 4 | Col 5 | Col 6 | Col 7 | Col 8 | Col 9 | Col 10 | | Col 1 | Col 2 | Col 3 | Col 4 | Col 5 | col 6 | col 7 | col 8 | col 9 | col 10 | | col 1 | col 2 | col 3 | col 4 | col 5 | col 6 | col 7 | col 8 | col 9 | col 10 |

Hyperlinks

In Markdown, hyperlinks in the middle of the text are created as follows:

[Text](https://link)

Which ultimately transforms into Text.

Links to articles in our WIKI must be localized. If the link goes outside the article, it is good practice to use {target="_blank"} to open the link in a new tab, which converts the existing format to:

[Text](https://link){target="_blank"}

A hyperlink can and sometimes should be highlighted: Text.

Markdown Elements

Images

Similarly, Markdown also supports images.

It is enough to put the ! sign at the beginning of the hyperlink:

![TheHost Logo](https://static.thehost.ua/ads/logo-308-111.png "Logo **TheHost**")

Where:

• [TheHostLogo] – this part is their description, primarily for search engines.
• https://static.thehost.ua/ads/logo-308-111.png – direct link to the image.
• “Logo TheHost” – description in the form of an element enclosing the image.

And finally, it looks like this:

TheHost uses the {fancy} argument to be able to rotate the image to full screen. It is optional and does not support joint use with the description element (**TheHost** Logo in the previous example). It looks like this:

![TheHost Logo](https://static.thehost.ua/ads/logo-308-111.png){fancy}

Now, about the usage standard:

• The width of the image should not exceed 1024 pixels. If it is still unavoidable to exceed it, the {fancy} argument must be used.
• Try to avoid excessively wide images in relation to their own height. A size ratio of 3:1 or more is strictly not recommended for use.
• The images used must be authentic – do not use images found on the Internet with an uncertain legal status.
• If you have any personal information (such as your server’s IP address), it is recommended that you blur it for your safety.

Callouts

Callouts are used as notes to highlight information. They improve the visibility and readability of the article.

<$>[note]
**Advice:** additional information relevant to the topic, but not directly part of it.
<$>

<$>[warning]
**Warning:** important and critical information that the reader must read.
<$>

<$>[info]
**Information:** advanced information on the topic, not required for reading to complete the task set by the material.
<$>

<$>[draft]
**Note/Characteristics:** listing the characteristics/capabilities of a previously defined entity, as well as use as a note that is not suitable for any of the above cases.
<$>

In practice:

The callout title must be in **Bold:** format, with a colon at the end.

Callouts can be combined with other elements, but not with the callouts themselves.

Spoiler

A spoiler is used to minimize the initially visible size of an article while preserving its full content.

[details Very important information
A lot of very important information.
]

A spoiler consists of the details header with arguments: closed – for closed by default, open – for open by default. closed is used without specifying.

After that comes the spoiler header and its content.

And in practice it looks like this:

Information: very important

A lot of very important information.

Spoilers are strongly recommended to be combined with collouts corresponding to the topic of the information in the spoiler. For example:

<$>[info]
[details closed **Information:** not very important, but very interesting
On October 29, 1969, the first communication session on **ARPANET** took place between Stanford and California universities -- the negotiators were able to transmit the message `LOGIN` over a distance of 640 km.

This day is considered the official founding date of the Internet.
]
<$>

Which in practice looks like this:

Similar to collouts, spoiler titles are in the format **Bold:** title, but the period at the end of the title is not required. However, the use of a question mark, if the title has a question form, is allowed.

Spoilers themselves fully support Markdown markup, with the exception of nesting a spoiler within a spoiler.

Code Block

Code blocks exist to highlight, well, code. Their support for the Markdown text format is limited to inline for obvious reasons.

Code blocks also support many different markup recognition modes, which can be specified immediately after its declaration using ```, such as ```nginx or ```js.

An example of a configuration file with a [label] label, which allows you to “name” your code block:

server {
listen 80 default_server;
. . .
}

Table of Contents nginx defines the format of the block below it. The full list of supported formats can be found at link.

If the format definition is used, the code block will also have a Copy button:

const print = 'hello';
const ln = 'world';
console.log(print, ln);

Example command output with an additional label using [secondary_label]:

Output
Unable to connect to MySQL on 127.0.0.1:3306: Connection refused

Example command as a normal user with the command argument:

sudo apt-get update
sudo apt-get install apache2 -y

Example command from the superuser with the super_user argument:

adduser exampleuser
shutdown

Example command with a custom prefix:

FLUSH PRIVILEGES;
SELECT * FROM wp_posts;

A custom prefix can contain a space:

FLUSH PRIVILEGES;
SELECT * FROM wp_posts;

Using the [environment] tag, code blocks can be made to look significantly different. This is especially useful for materials that perform actions on several servers at once (e.g. rsync):

ssh root@server_ip

echo "Second server"

echo "Third server"

echo "Fourth server"

echo "Fifth server"

And all this, if desired, can be combined:

<html>
<body>
<head>
<title>My title</title>
</head>
<body>
. . .
</body>
</html>

Conclusion

Adhering to TheHost’s technical standards for using Markdown will significantly reduce the time and improve productivity when writing content for our Wiki. Standardization of articles is one of our priorities, so failure to comply with the standards may result in the material being sent back for further revision.

After reading this guide along with the General Guide, you will have the basic qualifications for writing user content. And the rest is a matter of experience!