diff --git a/docs/pages/docs/best-practices.mdx b/docs/pages/docs/best-practices.mdx
index 4fab5c2ae48..9be9fdbf87c 100644
--- a/docs/pages/docs/best-practices.mdx
+++ b/docs/pages/docs/best-practices.mdx
@@ -24,6 +24,8 @@ Use include directives for repeated content. Remove backslash before the exclama
(\!CHANGELOG.md\!)
```
+Filepath should be relative to the repository root folder.
+
## Diagrams
Use [Teleport's lucidchart library](https://app.lucidchart.com/lucidchart/dfcf1f4a-5cf0-4758-8ebb-f6ea86900aba/edit)
@@ -67,3 +69,114 @@ For production, upload to the website and refer from there:
Your browser does not support the video tag.
```
+
+## Custom syntax used in the docs
+
+### Varibles
+
+To prevent updating links and code examples after each release, we can replace them with
+variables. This way, it will be enough to update them in one place.
+
+Variables are stored in the `docs/config.json` file under the key `variables`.
+Variables can be nested inside the config.
+
+To insert variabe to the page use `(\= path.to.variable \=)` syntax
+(remove backslashes in actual code).
+
+Variables will be linted on CI. If the variable didn't exist in the config, it would cause an error.
+
+### Includes
+
+To prevent content duplication, it may be useful to include code examples or other
+MDX files inside the current page. To do it use `(\! path-to-file.mdx \!)` syntax (remove
+backslashes in actual code).
+
+Paths are resolved from the root of the repository.
+
+Includes will only work in these two cases:
+
+1. Include surrounded by newlines. E. g.:
+
+ ```md
+ Some text.
+
+ (\! include.mdx \!)
+
+ Some other text.
+ ```
+
+ If the include is an `mdx` file, it will be parsed and rendered as a markdown. In other cases
+ it will be included as-is.
+
+2. Include inside the code blocks. E. g.:
+
+ ````md
+ ```bash
+ # Code example below
+
+ (\! include.sh \!)
+
+ ```
+ ````
+
+ These will be inserted as-is, even in the case of the `mdx` files.
+
+Includes in any other places will not be resolved and will be left as is.
+
+Includes will be linted on CI. If the file didn't exist in the repository,
+it would cause an error. Wrong placement of includes will also cause errors.
+
+### Image pixel density marker
+
+The browser can't distinguish between retina-ready and not retina-ready images.
+Because of this, screenshots made on the retina screens may look large on the page.
+
+To hint to the browser that the images are meant for retina display, we can add
+the suffix `@Nx` to the image's file name. For example, screenshots made on macOS
+should have the suffix `filename@2x.png`. It will tell the browser to scale images
+down twice to show them in their actual size. Different OSes may require different
+suffixes based on which logical and physical resolutions their screens have.
+
+### Admonitons
+
+
+ Admontion content.
+
+
+If you want to add admonition like the one above to the page use this syntax:
+
+```jsx
+
+ Admontion content.
+
+```
+
+`type` can be one of the following values: `warning`, `tip`, `note`, `danger`.
+Different types will result in different colors for the header. Omitting the type
+or using some other value will result in resetting it to the `tip`.
+
+If `title` is omitted, `type` will be used instead as the title value.
+
+### Tabs
+
+
+
+ First tab.
+
+
+ Second tab.
+
+
+
+To inser tabs block like the one above use this syntax:
+
+```jsx
+
+
+ First tab.
+
+
+ Second tab.
+
+
+```