Использование ссылок в документации

  • Статья

В этой статье описывается использование гиперссылок со страниц, размещенных в Microsoft Learn. Добавление ссылок в Markdown не представляет труда, но следует придерживаться ряда определенных правил. Ссылки могут указывать на содержимое на той же странице, на соседних страницах или на внешних сайтах и URL-адресах.

Серверная часть Microsoft Learn использует открытые службы публикации (OPS), которые поддерживают Markdown, совместимые с CommonMark, анализируемые с помощью механизма синтаксического анализа Markdig . Такой тип разметки совместим с GitHub Flavored Markdown (GFM), так как большинство документов хранятся на GitHub, где их можно править. Дополнительные функции добавляются с помощью расширений Markdown.

Важно!

Все ссылки должны быть безопасными (с протоколом https вместо http), если целевой объект поддерживает такой протокол (большинство целевых объектов поддерживают).

Текст ссылки

Фраза для ссылки должна быть понятной. Иными словами, это должен быть полноценный текст или название страницы, на которую указывает ссылка.

Важно!

Не используйте "щелкните здесь" в качестве текста ссылки. Она плохо сказывается на оптимизации для поисковых систем и не дает адекватного представления о целевой странице.

Правильно:

  • For more information, see the [contributor guide index](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

  • For more details, see the [SET TRANSACTION ISOLATION LEVEL](/sql/t-sql/statements/set-transaction-isolation-level-transact-sql) reference.

Неправильно:

  • For more details, see [https://msdn.microsoft.com/library/ms173763.aspx](https://msdn.microsoft.com/library/ms173763.aspx).

  • For more information, click [here](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

Ссылки для перехода от одной статьи к другой

Система публикации поддерживает два типа гиперссылок: URL-адреса и ссылки на файлы.

URL-ссылкой может быть URL-путь относительно корня https://learn.microsoft.com или абсолютный URL-адрес с синтаксисом полного URL-адреса (например, https://github.com/MicrosoftDocs/PowerShell-Docs).

  • Используйте URL-адреса для ссылки на содержимое за пределами текущего набора документации или для ссылок между автоматически создаваемой справкой и концептуальными статьями в наборе документации.
  • Самый простой способ создать относительную ссылку — скопировать URL-адрес в браузере, а затем удалить часть https://learn.microsoft.com/en-us из значения, вставленного в разметку Markdown.
  • Не включайте коды языковых стандартов в URL-свойства Документации Майкрософт (например, исключите /en-us из URL-адреса).

Ссылка на файл служит для перехода от одной статьи к другой в наборе документации.

  • В путях к файлам используются прямые (/), а не обратные косые черты.

  • Для статьи, в которую добавляется ссылка на другую статью в том же каталоге:

    [link text](article-name.md)

  • Для статьи, в которую добавляется ссылка на статью в родительском каталоге текущего каталога:

    [link text](../article-name.md)

  • Для статьи, в которую добавляется ссылка на статью в подкаталоге текущего каталога:

    [link text](directory/article-name.md)

  • Для статьи, в которую добавляется ссылка на статью в подкаталоге родительского каталога текущего каталога:

    [link text](../directory/article-name.md)

  • Некоторые статьи состоят из .yml файлов и .md , где .yml файл содержит метаданные, а .md содержит содержимое. В этом случае укажите ссылку на .yml файл :

    [link text](../directory/article-name.yml) (не[link text](../directory/article-name-content.md))

Примечание

Ни в одном из предыдущих примеров ~/ не используется в качестве части ссылки. Если вы ссылаетесь на абсолютный путь в корне репозитория, начните с /. Добавление ~/ приведет к формированию недопустимых ссылок при навигации по репозиториям исходного кода на GitHub. Если начать путь с /, разрешение происходит успешно.

Содержимое, опубликованное в Microsoft Learn, имеет следующую структуру URL-адресов:

https://learn.microsoft.com/<locale>/<product-service>/[<feature-service>]/[<subfolder>]/<topic>[?view=<view-name>]

Примеры:

https://learn.microsoft.com/azure/load-balancer/load-balancer-overview

https://learn.microsoft.com/powershell/azure/overview?view=azurermps-5.1.1
  • <locale> — определяет язык статьи (например, en-us или ru-ru).
  • <product-service> — название продукта или службы (например, powershell, dotnet или azure).
  • [<feature-service>] — (необязательно) имя компонента или подслужбы продукта (например, csharp или load-balancer).
  • [<subfolder>] — (необязательно) имя подпапки компонента.
  • <topic> — имя файла статьи (например, load-balancer-overview или overview).
  • [?view=\<view-name>] — (необязательно) имя представления, используемое средством выбора версии для содержимого, имеющего несколько версий (например, azps-3.5.0).

Совет

В большинстве случаев для статей в одном наборе документации указывается один и тот же фрагмент URL-адреса <product-service>. Например:

  • Тот же набор документов:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/dotnet/framework/install
  • Другой набор документов:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/visualstudio/whats-new

Чтобы добавить ссылку закладки на заголовок в текущем файле, используйте символ решетки, за которым следует текст заголовка в нижнем регистре. Удалите знаки препинания из заголовка и замените пробелы дефисами.

[Managed Disks](#managed-disks)

Чтобы добавить ссылку закладки на заголовок в другой статье, используйте относительную ссылку на файл или сайт, после которой укажите символ решетки и текст заголовка. Удалите знаки препинания из заголовка и замените пробелы дефисами.

[Managed Disks](../../linux/overview.md#managed-disks)

Можно также скопировать ссылку закладки из URL-адреса. Чтобы найти URL-адрес, наведите указатель мыши на строку заголовка в Microsoft Learn. Должен появиться значок ссылки:

Значок ссылки в заголовке статьи

Щелкните значок ссылки, а затем скопируйте текст закладки из URL-адреса (то есть часть после символа решетки).

Примечание

Расширение Learn Markdown также содержит инструменты для создания ссылок.

Добавлять явные ссылки привязки, использующие HTML-тег <a>, не требуется и не рекомендуется, за исключением страниц-концентраторов и целевых страниц. Вместо них используйте автоматически созданные закладки, как описано в этом разделе. Для страниц-концентраторов и целевых страниц привязки объявляются следующим образом:

## <a id="anchortext" />Header text

или

## <a name="anchortext" />Header text

Ссылка на привязку добавляется следующим образом:

To go to a section on the same page:
[text](#anchortext)

To go to a section on another page.
[text](filename.md#anchortext)

Примечание

Текст привязки должен всегда быть в нижнем регистре и не содержать пробелов.

Ссылки XRef — это рекомендуемый способ ссылки на интерфейсы API, так как они проверяются во время сборки. Для ссылки на автоматически создаваемые страницы справочных материалов по API в текущем или другом наборе документации используйте ссылки XRef с уникальным идентификатором (UID) типа или члена.

Совет

Вы можете использовать расширение Learn Markdown для VS Code (часть пакета разработки Learn) для вставки ссылок .NET XRref, отображаемых в браузере API .NET.

Убедитесь, что API, на который вы хотите создать ссылку, опубликован в Microsoft Learn , введя его полное имя в браузере API .NET или в поле поиска Windows UWP . Если результаты не отображаются, тип еще не указан в Microsoft Learn.

Можно выбрать один из следующих вариантов синтаксиса:

  • Автоматические ссылки:

    <xref:UID>
<xref:UID?displayProperty=nameWithType>

    По умолчанию в тексте ссылки отображается только имя члена или типа. Необязательный параметр запроса displayProperty=nameWithType создает полный текст ссылки, то есть namespace.type для типов и type.member для членов типов, включая перечисления.

  • Ссылки в стиле Markdown:

    [link text](xref:UID)

    Ссылки в стиле Markdown используются, когда требуется настроить отображаемый текст ссылки.

Примеры:

  • <xref:System.String> отображается как String.

  • <xref:System.String?displayProperty=nameWithType> отображается как System.String.

  • [String class](xref:System.String) отображается как String class.

Параметр запроса displayProperty=fullName работает так же, как displayProperty=nameWithType для классов. То есть текст ссылки принимает вид пространство_имен.имя_класса. Однако для членов текст ссылки отображается в виде пространство_имен.имя_класса.имя_члена, что может быть нежелательным.

Примечание

Регистр в уникальных идентификаторах учитывается. Например, <xref:System.Object> разрешается успешно, а <xref:system.object> нет.

Предупреждения сборки XRef и добавочные сборки

При добавочной сборке выполняется сборка только тех файлов, которые были изменены или затронуты изменением. Если выводится предупреждение о недействительной ссылке XRef, которая на самом деле действительна, это может быть вызвано тем, что сборка была добавочной. Файл, вызвавший предупреждение, не изменялся, поэтому его сборка не выполнялась и были повторно выданы прошлые предупреждения. Предупреждение исчезнет после изменения файла или запуска полной сборки (запустить ее можно на сайте ops.microsoft.com). Это недостаток добавочных сборок, так как DocFX не может обнаружить изменение данных в службе XREF.

Определение уникального идентификатора

Уникальный идентификатор обычно совпадает с полным именем класса или члена. Определить уникальный идентификатор можно по крайней мере двумя способами.

  • Щелкните правой кнопкой мыши страницу Microsoft Learn для типа или члена, выберите Просмотреть источник, а затем скопируйте значение содержимогодля ms.assetid:

    ms.assetid в исходном коде веб-страницы

  • Используйте сайт автозаполнения, добавив к URL-адресу имя типа или его часть. Например, если ввести https://xref.docs.microsoft.com/autocomplete?text=Writeline в адресной строке браузера, будут выведены все типы и методы, в именах которых есть строка Writeline, а также их уникальные идентификаторы.

Проверка уникального идентификатора

Чтобы проверить правильность уникального идентификатора, замените строку System.String в следующем URL-адресе на свой уникальный идентификатор, а затем вставьте получившийся адрес в адресной строке браузера:

https://xref.docs.microsoft.com/query?uid=System.String

Совет

Регистр в уникальном идентификаторе в URL-адресе учитывается. Если вы проверяете уникальный идентификатор перегрузки метода, не включайте пробелы между типами параметров.

Если результат будет следующим, значит уникальный идентификатор правилен:

[{"uid":"System.String","name":"String","fullName":"System.String","href":"https://learn.microsoft.com/dotnet/api/system.string","tags":",/dotnet,netframework-4.5.1,netframework-4.5.2,netframework-4.5,...xamarinmac-3.0,public,","vendor":null,"hash":null,"commentId":"T:System.String","nameWithType":"System.String"},{"uid":"System.String","name":"String","fullName":"System.String","href":"https://learn.microsoft.com/dotnet/api/system.string","tags":",/dotnet,netframework-4.5.1,netframework-4.5.2,netframework-4.5,netframework-4.6,netframework-4.6.1,...,xamarinmac-3.0,public,","vendor":null,"hash":null,"commentId":"T:System.String","nameWithType":"System.String"}]

Если на странице отображается просто [], значит уникальный идентификатор неправилен.

Кодирование URL-адресов с помощью символа процента

Специальные символы в уникальном идентификаторе должны быть закодированы в формате HTML следующим образом:

Символ Кодирование HTML
` %60
# %23
* %2A

См. полный список кодов с символом процента.

Примеры кодирования:

  • System.Threading.Tasks.Task`1 кодируется как System.Threading.Tasks.Task%601 (см. раздел об универсальных типах).

  • System.Exception.#ctor кодируется как System.Exception.%23ctor.

  • System.Object.Equals* кодируется как System.Object.Equals%2A.

Универсальные типы

Универсальные типы — это такие типы, как System.Collections.Generic.List<T>. При переходе к этому типу в обозревателе API .NET и просмотре его URL-адреса вы увидите, что <T> записывается в URL-адресе как -1, что фактически представляет `1:

https://learn.microsoft.com/dotnet/api/system.collections.generic.list-1

Чтобы создать ссылку на универсальный тип, например List<T>, закодируйте символ обратного апострофа ` как %60, как показано в следующем примере:

<xref:System.Collections.Generic.List%601>

Методы

Чтобы создать ссылку на метод, можно использовать ссылку либо на общую страницу метода (при этом после имени метода нужно добавить звездочку (*)), либо на конкретную перегрузку. Например, используйте общую страницу, если нужно указать ссылку на метод <xref:System.Object.Equals%2A?displayProperty=nameWithType> без конкретных типов параметров. Символ звездочки кодируется как %2A. Например:

<xref:System.Object.Equals%2a?displayProperty=nameWithType> указывает на Object.Equals.

Чтобы сослаться на конкретную перегрузку, добавьте скобки после имени метода и включите полное имя типа каждого параметра. Не ставьте пробелы между именами типов, иначе ссылка не будет работать. Например:

<xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> указывает на Object.Equals(Object, Object).

Включаемые файлы содержатся в другом каталоге, поэтому для них используются более длинные относительные пути. Чтобы добавить ссылку на статью во включаемый файл, используйте следующий формат:

[link text](../articles/folder/article-name.md)

Совет

Расширение Learn Authoring Pack для Visual Studio Code помогает правильно вставлять относительные ссылки и закладки без необходимости выяснить пути.

Селектор — это компонент навигации, который отображается в статье в документации как раскрывающийся список. Когда читатель выбирает значение в раскрывающемся списке, браузер открывает выбранную статью. Обычно список в селекторе содержит ссылки на связанные статьи, например, та же тема на разных языках программирования или тесно связанная серия статей.

Если во включаемый файл внедрены селекторы, используйте следующую структуру ссылки:

> [AZURE.SELECTOR-LIST (Dropdown1 | Dropdown2 )]
- [(Text1 | Example1 )](../articles/folder/article-name1.md)
- [(Text1 | Example2 )](../articles/folder/article-name2.md)
- [(Text2 | Example3 )](../articles/folder/article-name3.md)
- [(Text2 | Example4 )](../articles/folder/article-name4.md)

Ссылки типа сносок используются для того, чтобы пользователю было легче воспринимать содержимое источника. Для ссылок типа сносок синтаксис встроенной ссылки заменяется упрощенным вариантом, который позволяет переместить длинные URL-адреса в конец статьи. Ниже приведен пример от Daring Fireball.

Встроенный текст:

I get 10 times more traffic from [Google][1] than from [Yahoo][2] or [MSN][3].

Ссылки типа сносок в конце статьи:

<!--Reference links in article-->
[1]: http://google.com/
[2]: http://search.yahoo.com/
[3]: http://search.msn.com/

Обязательно используйте пробел после двоеточия перед ссылкой. Если при добавлении ссылок на другие технические статьи вы забудете включить пробел, ссылка не будет работать в опубликованной статье.

Чтобы добавить ссылку на страницу корпорации Майкрософт другого характера (например, на страницу с ценами, страницу соглашения об уровне обслуживания или любую другую страницу, не являющуюся статьей документации), используйте абсолютный URL-адрес без указания языка. Такие ссылки работают на сайте GitHub и на отображаемом сайте:

[link text](https://azure.microsoft.com/pricing/details/virtual-machines/)

Лучше избегать перенаправления пользователей на другие сайты. Но иногда это необходимо. При размещении ссылок на сторонние сайты руководствуйтесь следующей информацией:

  • Отслеживаемость. Добавляйте ссылки на содержимое сторонних поставщиков, если именно к нему требуется предоставить общий доступ. Например, предоставлять описание того, как использовать средства разработчика Android, не входит в обязанности корпорации Майкрософт. Это задача Google. При необходимости мы можем объяснить, как использовать средства разработчика Android с Azure, но руководство по применению этих средств должна предоставить корпорация Google.
  • Утверждение руководителем проектов. Запрашивайте в корпорации Майкрософт утверждение ссылок на содержимое сторонних поставщиков. Такие ссылки предполагают определенный уровень ответственности за надежность информации и выполнение инструкций пользователем.
  • Проверки актуальности. Следите за актуальностью, правильностью и релевантностью информации. Регулярно проверяйте, не изменилась ли ссылка.
  • Информация о переходе на сайт стороннего поставщика. Обязательно уведомляйте пользователей о том, что они переходят на другой сайт. Если это не следует из контекста, добавьте соответствующую фразу. Например: "Предварительные требования включают установку средств для разработчиков Android, которые вы можете скачать на сайте Android Studio".
  • Дальнейшие действия. Неплохим решением будет добавить ссылку, скажем, на блог MVP в разделе "Дальнейшие действия". Опять же, при этом пользователь должен понимать, что он покидает текущий сайт.
  • Юридическая информация. Юридическая информация предоставляется в разделе Ссылки на веб-сайты третьих лиц на странице условий использования. Ссылка на нее размещена в нижнем колонтитуле каждой страницы сайта microsoft.com.