diff --git a/Contribute/how-to-write-use-markdown.md b/Contribute/how-to-write-use-markdown.md
index 1b37789..8e81c99 100644
--- a/Contribute/how-to-write-use-markdown.md
+++ b/Contribute/how-to-write-use-markdown.md
@@ -1,4 +1,4 @@
----
+---
title: Использование языка разметки Markdown для написания документации
description: В этой статье приводятся базовые и справочные сведения о языке разметки Markdown, используемом для написания статей на сайте docs.microsoft.com.
ms.date: 07/13/2017
@@ -8,364 +8,364 @@ ms.translationtype: HT
ms.contentlocale: ru-RU
ms.lasthandoff: 06/19/2018
ms.locfileid: "36238973"
----
-# Использование языка разметки Markdown для написания документации
-
-Статьи на сайте docs.microsoft.com написаны на [Markdown](https://daringfireball.net/projects/markdown/) — упрощенном языке разметки, который легко использовать и изучать. Благодаря своей простоте он быстро становится отраслевым стандартом.
-
-Так как документация хранится в репозитории GitHub, для нее можно использовать расширенный набор Markdown под названием [GitHub Flavored Markdown (GFM)](https://help.github.com/categories/writing-on-github/). Этот формат предусматривает дополнительные возможности для решения распространенных задач. Кроме того, службы Open Publishing Services (OPS) используют Markdig, синтаксический анализатор Markdown. Он обеспечивает высокую совместимость с диалектом GitHub Flavored Markdown (GFM), предоставляя дополнительные функции для работы с порталом Docs.
-
-* Markdig — это быстрый и мощный обработчик Markdown для .NET, обеспечивающий соответствие CommonMark и поддержку расширений.
-* https://github.com/lunet-io/markdig
-* Улучшенная поддержка сообщества
-* Улучшенная поддержка стандартов
-
-## Базовые сведения о Markdown
-
-### Заголовки
-
-Чтобы создать заголовок, используйте знак (#), например:
-
-```markdown
- # This is heading 1
- ## This is heading 2
- ### This is heading 3
- #### This is heading 4
-```
-
-### Полужирное начертание и курсив
-
-Чтобы задать для текста **полужирное начертание**, заключите его в двойные звездочки:
-
-```markdown
- This text is **bold**.
-```
-
-Чтобы задать для текста *курсивное начертание*, заключите его в одинарные звездочки:
-
-```markdown
- This text is *italic*.
-```
-
-Чтобы задать для текста ***полужирное и курсивное*** начертание, заключите его в тройные звездочки:
-
-```markdown
- This is text is both ***bold and italic***.
-```
-
-### Списки
-
-#### Неупорядоченный список
-
-Неупорядоченный (маркированный) список можно отформатировать с помощью звездочек или тире. Например, следующая разметка Markdown:
-
-```markdown
-- List item 1
-- List item 2
-- List item 3
-```
-
-будет отображаться как:
-
-- List item 1
-- List item 2
-- List item 3
-
-Чтобы вложить один список в другой, добавьте отступ для элементов дочернего списка. Например, следующая разметка Markdown:
-
-```markdown
-- List item 1
- - List item A
- - List item B
-- List item 2
-```
-
-будет отображаться как:
-
-- List item 1
- - List item A
- - List item B
-- List item 2
-
-#### Упорядоченный список
-
-Упорядоченный (ступенчатый) список можно отформатировать с помощью соответствующих цифр. Например, следующая разметка Markdown:
-
-```markdown
-1. First instruction
-2. Second instruction
-3. Third instruction
-```
-
-будет отображаться как:
-
-1. First instruction
-2. Second instruction
-3. Third instruction
-
-Чтобы вложить один список в другой, добавьте отступ для элементов дочернего списка. Например, следующая разметка Markdown:
-
-```markdown
-1. First instruction
- 1. Sub-instruction
- 2. Sub-instruction
-2. Second instruction
-```
-
-будет отображаться как:
-
-1. First instruction
- 1. Sub-instruction
- 2. Sub-instruction
-2. Second instruction
-
-### Tables
-
-Таблицы не входят в основную спецификацию Markdown, но их поддерживает GFM. Создавать таблицы можно с помощью символов вертикальной черты (|) и дефиса (-). Дефисы позволяют создавать для каждого столбца заголовок. Вертикальные черты разделяют столбцы. Чтобы таблица правильно отображалась, включите перед ней пустую строку.
-
-Например, следующая разметка Markdown:
-
-```markdown
-| Fun | With | Tables |
-| :------------------- | -------------------: |:---------------:|
-| left-aligned column | right-aligned column | centered column |
-| $100 | $100 | $100 |
-| $10 | $10 | $10 |
-| $1 | $1 | $1 |
-```
-
-будет отображаться как:
-
-| Fun | with | Tables |
-| :------------------- | -------------------: |:---------------:|
-| left-aligned column | right-aligned column | centered column |
-| $100 | $100 | $100 |
-| $10 | $10 | $10 |
-| $1 | $1 | $1 |
-
-Дополнительные сведения о создании таблиц:
-
-- [Функция обтекания таблиц](#table-wrapping) в Markdig, которая поможет при форматировании широких таблиц.
-- Статья на сайте GitHub [Organizing information with tables](https://help.github.com/articles/organizing-information-with-tables/) (Упорядочение информации при помощи таблиц).
-- Веб-приложение [Markdown Tables Generator](https://www.tablesgenerator.com/markdown_tables).
-- Статья Адама Притчарда (Adam Pritchard) [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#wiki-tables) (Шпаргалка по Markdown).
-- Статья Майкла Фортина (Michel Fortin) [Markdown Extra](https://michelf.ca/projects/php-markdown/extra/#table) (Расширение Markdown Extra).
-- [Convert HTML tables to Markdown](https://jmalarcon.github.io/markdowntables/) (Преобразование таблиц HTML в Markdown)
-
-### Создание ссылок
-
-Синтаксис Markdown для встроенной ссылки состоит из части `[link text]`, представляющей текст гиперссылки, и части `(file-name.md)` — URL-адреса или имени файла, на который дается ссылка:
-
- `[link text](file-name.md)`
-
-Дополнительные сведения о ссылках:
-
-- [Markdown: Syntax](https://daringfireball.net/projects/markdown/syntax#link) (Руководство по синтаксису Markdown), в котором предоставлена основная информация по поддержке ссылок Markdown.
-- Страница [Ссылки](how-to-write-links.md) в этом руководстве содержит сведения о дополнительном синтаксисе Markdig для ссылок.
-
-### Фрагменты кода
-
-Markdown поддерживает как встраивание фрагментов кода в предложение, так и их размещение между предложениями в виде отдельных огражденных блоков. Дополнительная информация:
-
-- [Сведения о собственной поддержке блоков кода Markdown](https://daringfireball.net/projects/markdown/syntax#precode)
-- [Сведения о поддержке GFM для ограждения кода и выделения синтаксиса](https://help.github.com/articles/creating-and-highlighting-code-blocks/)
-
-Огражденные блоки кода — это простой способ выделить синтаксис для фрагментов кода. Общий формат огражденных блоков кода:
-
- ```alias
- ...
- your code goes in here
- ...
- ```
-
-Псевдоним после трех начальных символов обратной галочки ` определяет использование выделения. Ниже представлен список часто используемых языков программирования для написания документации и приводятся соответствующие метки.
-
-Все эти языки поддерживают понятные имена, а большинство из них — выделение языка в имени.
-
-|Имя|Метка Markdown|
-|-----|-------|
-|.NET Console|dotnetcli|
-|ASP.NET (C#)|aspx-csharp|
-|ASP.NET (VB)|aspx-vb|
-|AzCopy|azcopy|
-|Azure CLI|azurecli|
-|Azure PowerShell|azurepowershell|
-|C++|cpp|
-|C++/CX|cppcx|
-|C++/WinRT|cppwinrt|
-|C#|csharp|
-|CSHTML|cshtml|
-|DAX|dax|
-|F#|fsharp|
-|Go|go|
-|HTML|html|
-|HTTP|http|
-|Java|java|
-|JavaScript|javascript|
-|JSON|json|
-|Markdown|md|
-|NodeJS|nodejs|
-|Objective-C|objc|
-|OData|odata|
-|PHP|php|
-|Power Apps Formula|powerappsfl|
-|PowerShell|powershell|
-|Python|python|
-|Q#|qsharp|
-|Ruby|ruby|
-|SQL|sql|
-|Swift|swift|
-|TypeScript|typescript|
-|VB|vb|
-|VSTS CLI|vstscli|
-|XAML|xaml|
-|XML|xml|
-
-#### Пример: C\#
-
-__Markdown__
-
- ```csharp
- // Hello1.cs
- public class Hello1
- {
- public static void Main()
- {
- System.Console.WriteLine("Hello, World!");
- }
- }
- ```
-
-__Отображение__
-
-```csharp
-// Hello1.cs
-public class Hello1
-{
- public static void Main()
- {
- System.Console.WriteLine("Hello, World!");
- }
-}
-```
-
-#### Пример: SQL
-
-__Markdown__
-
- ```sql
- CREATE TABLE T1 (
- c1 int PRIMARY KEY,
- c2 varchar(50) SPARSE NULL
- );
- ```
-
-__Отображение__
-
-```sql
-CREATE TABLE T1 (
- c1 int PRIMARY KEY,
- c2 varchar(50) SPARSE NULL
-);
-```
-
-## Настраиваемые расширения OPS для Markdown
-
-> [!NOTE]
-> Службы Open Publishing Services (OPS) используют Markdig, синтаксический анализатор Markdown, обеспечивающий высокую совместимость с диалектом GitHub Flavored Markdown (GFM). Markdig добавляет дополнительные функции за счет расширений Markdown. Поэтому для справки мы включили в этот материал некоторые разделы из руководства по разработке OPS. (Например, см. в содержании разделы "Markdig и расширения Markdown" и "Фрагменты кода".)
-
-В статьях документации для общего форматирования, например для создания абзацев, ссылок, списков и заголовков, используется GFM. Для расширенного форматирования в статьях можно использовать следующие функции Markdig:
-
-- Блоки заметок
-- включаемые файлы;
-- селекторы;
-- внедренные видео;
-- фрагменты или примеры кода.
-
-Полный список см. в разделах "Markdig и расширения Markdown" и "Фрагменты кода".
-
-### Блоки заметок
-
-Есть четыре типа блоков заметок, которые позволяют привлечь внимание к определенному содержимому:
-
-- ПРИМЕЧАНИЕ;
-- ПРЕДУПРЕЖДЕНИЕ;
-- СОВЕТ;
-- ВАЖНО.
-
-В целом не следует часто использовать блоки заметок, так как они могут отвлекать пользователя от основного содержимого. Хотя эти элементы также поддерживают блоки кода, изображения, списки и ссылки, лучше не перегружать их, делая простыми и понятными.
-
-### Включаемые файлы
-
-Если вы хотите добавить в файлы статей многократно используемые изображения или текст, воспользуйтесь доступной в Markdig функцией включения ("include") файлов по ссылке. Функция указывает OPS включить файл в файл статьи во время сборки, чтобы он стал частью опубликованной статьи. Существует три типа включаемых файлов для многократного использования содержимого:
-
-- Встроенные — для многократного использования фрагмента стандартного текста путем его встраивания в другое предложение.
-- Блочные — для многократного использования всего файла Markdown в качестве блока путем его вложения в раздел или статью.
-- Изображения — позволяют включать стандартное изображение в документацию.
-
-Встроенные и блочные включаемые файлы — это простые файлы Markdown с расширением .md. Они могут содержать любую допустимую разметку Markdown. Все включаемые файлы Markdown должны быть помещены в [общий подкаталог `/includes`](git-github-fundamentals.md#includes-subdirectory) в корневом каталоге репозитория. Когда статья публикуется, включаемый файл легко интегрируется в нее.
-
-Далее приведены требования по работе с включаемыми файлами.
-
-- Используйте включаемые файлы, если вам нужно, чтобы один и тот же текст отображался в нескольких статьях.
-- Блочные включаемые файлы предназначены для значительных объемов текста: один или два абзаца, общая процедура или общий раздел. Не используйте их для фрагментов текста меньше одного предложения.
-- Включаемые файлы не будут отображаться в представлении статьи на GitHub, так как они работают только с Markdig-расширениями. Они отображаются только после публикации.
-- Весь текст во включаемом файле должен состоять из полноценных предложений или фраз, не зависящих от остального текста статьи, в которую добавляется ссылка на такой файл. Если не следовать этой инструкции, в статье создаются непереводимые строки, которые нарушают процесс локализации.
-- Не внедряйте одни включаемые файлы в другие. Такая возможность не поддерживается.
-- Файлы мультимедиа должны быть помещены в отдельную папку мультимедиа в подкаталоге включаемых файлов. Например, ``/включаемые файлы/папка мультимедиа. В корне каталога мультимедиа не должны содержаться изображения. Если во включаемом файле нет изображений, соответствующий каталог мультимедиа не требуется.
-- Как и в обычных статьях, не используйте общий файл мультимедиа для включаемых файлов. Для каждого включаемого файла в статье должен быть создан отдельный файл мультимедиа с уникальным именем. Файл мультимедиа должен храниться в папке мультимедиа, связанной с включаемым файлом.
-- Не используйте включаемый файл как единственное содержимое статьи. Включаемые файлы предназначены для дополнения основных материалов статьи.
-
-### Селекторы
-
-В технических статьях селекторы применяются для создания разных вариантов содержимого, чтобы проиллюстрировать различия в реализации, связанные с использованием нескольких технологий или платформ. Это в особенности применимо к материалам о мобильных платформах для разработчиков. Сейчас в Markdig есть два типа селекторов: для единичного и множественного выбора.
-
-В каждой статье с возможностью выбора используется одна и та же разметка Markdown для селектора. Поэтому рекомендуется поместить селектор для статьи во включаемый файл. Затем нужно добавить ссылки на этот файл во все статьи, для которых используется селектор.
-
-### Фрагменты кода
-
-В Markdig есть расширение с расширенными функциями для включения в статью фрагментов кода. Этот формат обеспечивает расширенный рендеринг на основе функций GFM, таких как выбор языка программирования и раскраска синтаксиса, а также другие полезные функции, например:
-
-- включение централизованных примеров или фрагментов кода из внешнего репозитория;
-- пользовательский интерфейс с вкладками для отображения нескольких версий примеров кода на разных языках.
-
-## Сбои и устранение неполадок
-
-### Замещающий текст
-
-Замещающий текст, который содержит символы подчеркивания, отображается некорректно. Например, вместо
-
-```markdown
-![ADextension_2FA_Configure_Step4] (./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG)
-```
-
-используйте следующий вариант, позволяющий избежать символов подчеркивания:
-
-```markdown
-![ADextension\_2FA\_Configure\_Step4] (./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG)
-```
-
-### Апострофы и кавычки
-
-Если вы копируете текст из Word в редактор Markdown, он может содержать книжные (изогнутые) апострофы или кавычки. Их нужно заменить кодом или обычными апострофами или кавычками. В противном случае после публикации файла может отобразиться нечитаемый текст, например It’s.
-
-Ниже приведены кодировки для этих знаков пунктуации:
-
-- левая (открывающая) кавычка: `“`;
-- правая (закрывающая) кавычка: `”`;
-- правая закрывающая одинарная кавычка или апостроф: `’`;
-- левая открывающая одинарная кавычка (используется редко): `‘`.
-
-### Угловые скобки
-
-Если в тексте файла (не в коде) используются угловые скобки (например, для обозначения заполнителя), их нужно кодировать вручную. Иначе Markdown распознает их как часть тега HTML.
-
-Например, `