Поделиться через

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

  • Статья

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

Серверная часть Microsoft Learn использует открытые службы публикации (OPS), которая поддерживает синтаксический анализ Markdown, совместимый с CommonMark, с помощью подсистемы синтаксического анализа Markdig. Этот вкус Markdown в основном совместим с 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

or

## <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, так как они упрощают настройку текста ссылки. Кроме того, они проверяются во время сборки, и если URL-адрес ссылки на API был изменен, ссылка по-прежнему будет работать. Для ссылки на автоматически создаваемые страницы справочных материалов по API в текущем или другом наборе документации используйте ссылки XRef с уникальным идентификатором (UID) типа или члена.

Совет

Расширение справки по ссылке API для VS Code упрощает вставку ссылок API .NET в файлы Markdown и XML.

Убедитесь, что 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 для классов. То есть текст ссылки принимает вид пространство_имен.имя_класса. Однако для членов текст ссылки отображается как namespace.classname.membername, который может быть нежелательным.

Примечание.

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

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

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

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

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

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

Символ Кодирование HTML
* *

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

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

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

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

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

Методы

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

<xref:System.Object.Equals*?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 для Visual Studio Code помогает правильно вставлять относительные ссылки и закладки без tedium поиска путей.

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

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

> [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.