english | русский
- Headers
- Styles
- Lists
- Tables
- Links
- Code inserts
- Images
- Notes
- Content reuse
- Tabs
- Cuts
- Variables
- Metadata
To create a header, use the (#) character, for example:
# H1 header
## H2 header
### H3 header
#### H4 headerYFM uses four levels of headers. A page header must be the first level. You can use the second, third, and fourth levels for subsection headers.
Important! Make sure you maintain the nesting structure of headers.
To make text bold, wrap it in double asterisks (*):
This text will be **bold**.To make text italic, wrap it in underscores:
This text will be _italic_.To make text bold and italic, use both double asterisks and underscores:
This text will be _**bold and italic**_.
This text will be **_bold and italic_**.To format characters in superscript, wrap them in ^:
This text is in ^superscript^.To make an unordered bulleted list, use such characters as *, -, or +.
For example, markdown like:
- Element 1
- Element 2
- Element 3will be displayed as:
- Element 1
- Element 2
- Element 3
To make a nested bulleted list, add an indent for items in a child list. The indent can be from two to five spaces. We recommend indenting three spaces.
For example, markdown like:
- Element 1
- Element A
- Element B
- Element 2will be displayed as:
- Element 1
- Element A
- Element B
- Element 2
To make an ordered numbered list, use numbers with the . or ) character. The recommended markdown format is 1 and ..
For example, markdown like:
1. First item
1. Second item
1. Third item
will be displayed as:
- First item
- Second item
- Third item
To make a nested ordered list, add an indent for child list items. The indent can be from two to five spaces. We recommend indenting three spaces.
For example, markdown like:
1. First item
1. Nested item
1. Nested item
1. Second item
will be displayed as:
- First item
- Nested item
- Nested item
- Second item
Tables consist of a single row with headers, a separator row, and rows with data.
Each row in a table consists of cells that are separated from each other by | characters.
The cells of the separator row only allow the - and : characters. The colon (:) is used at the beginning, end, or on both sides of the cell content of the separator row to indicate left, right, or center alignment of text in the corresponding column.
A table should be separated from the surrounding text with empty lines.
For example, markdown like:
Left column | Right column | Center column
:--- | ---: | :---:
Text | Text | Textwill be displayed as:
| Left column | Right column | Center column |
|---|---|---|
| Text | Text | Text |
Links are presented in the format [text](link), where:
[text]is the link text.(link)is the URL or path to the file referenced.
For example, markdown like:
[link to README.md](README.md)will be displayed as:
YFM lets you add links to other MD files without specifying the link text. It's substituted automatically from the header of the specified file.
For example, a link like:
[{#T}](README.md)will be displayed as:
You can insert a piece of code in the text of a paragraph or put it in a separate block.
To insert a code fragment into text, use the ` character.
For example, markdown like:
A sentence with a `code snippet`.will be displayed as:
A sentence with a code snippet.
To format a code fragment as a separate block, place it in triple `. To highlight the syntax, specify the language that the code is written in.
For example, markdown like:
```js
let a= 10;
```
will be displayed as a highlighted code fragment:
let a= 10;To insert an image in a document, use markdown like
![alt text](_assets/image.png "Hint text" =100x200)Where:
-
[alt text]is the alternative text for the image. -
_assets/image.pngis the path to the image file.Important! Images should be stored in a directory whose name starts with
_. Otherwise, they will be deleted when making a build. -
"Hint text": Text of a hint displayed when hovering over the image. -
=100x200: Image size in pixels.
You can declare an image in document text once and then invoke it in the text using a short link. To do this:
-
Declare an image:
[image]: _assets/image.png "Hint text"
-
Insert the image using markdown:
![alt text][image]
This method can be useful when you need to insert the same image multiple times.
A note is a visually highlighted block that lets you draw attention to content.
There are four types of notes: info, tip, warning, and alert.
Don't overuse note blocks, as they may distract the user from the main content. Although these elements may contain YFM, it's better not to overload them. Make them simple and clear.
{% note info %}
This is info.
{% endnote %}
{% note tip %}
This is a tip.
{% endnote %}
{% note warning %}
This is a warning.
{% endnote %}
{% note alert %}
This is an alert.
{% endnote %}
By default, a note has a standard header, but you can override it:
{% note info "Custom title" %}
This is a warning.
{% endnote %}If there is nothing inside the quotes, the note will not have a header:
{% note info "" %}
This is a warning.
{% endnote %}You can store duplicate content in a separate file and insert it into a document using the {% include %} element. This is often more convenient than copying and pasting it.
To use the same content in multiple places:
-
Save this text in a separate MD file.
Important! Make sure these files are stored in a directory whose name starts with
_(for example,_includes). Otherwise, the files are deleted when making a build. -
Insert a link to the file in the document:
{% include notitle [Описание](_includes/file.md) %}Where:
notitle: If the parameter is specified, the file header isn't inserted into the text.[Description]: File description. Doesn't affect the build, used only for document refactoring.(_includes/file.md): File path.
As a result, the file content is inserted into the document while making the build. If the file has relative links to other documents or images, they will be rebuilt.
You can format text as tabs. This can be useful, for example, to distinguish similar content and not to overload the page with text:
To create a tab, use markdown like:
{% list tabs %}
- Name of tab1
Content of tab1.
- You can use lists.
- And **other** markdown.
- Name of tab2
Content of tab2.
{% endlist %}Important! When using tabs, be sure to leave empty lines:
- Before and after lines
{% list tabs %}and{% endlist %}. - Between the text of one tab and the title of the next tab.
You can use YFM inside tabs: lists, tables, images, code, and so on.
Cuts let you hide content ("cut it"). You can use them in long listings, code examples, and so on. You can use YFM inside a cut.
To make a cut, use markdown like:
{% cut "Заголовок ката" %}
Content we want to hide
{% endcut %}In YFM, you can declare and use variables. When making a build, variables are substituted into the text of a document or used to calculate conditions. This is useful, for example, when building the documentation for different versions of a service from the same source files.
To declare and use variables in a document:
-
In the document root directory, create a file named
presets.yaml. -
Declare the variables in
presets.yamlin the following format:default: variable-name-1: value of variable 1 variable-name-2: value of variable 2 -
To insert a variable value into a document as text, use markdown like:
Some text {{ variable-name-1 }} text continued.
You can include a fragment of text in a document build, depending on variable values.
For example, to build two versions of a document for different operating systems, use markdown like:
{% if OS == 'iOS' %}
Download the app from the [App Store](https://www.apple.com/ios/app-store/).
{% else %}
Download the app from [Google Play] (https://play.google.com).
{% endif %}
Available conditional operators are if, else if, and else. Available comparison operators are ==, !=, <, >, <=, and >=.
You can add YAML metadata at the beginning of a file.
---
title: Title
description: Description
---