Udostępnij za pośrednictwem

Używanie linków w dokumentacji

  • Artykuł

W tym artykule opisano sposób używania hiperlinków ze stron hostowanych w witrynie Microsoft Learn. Linki można łatwo dodawać do znaczników markdown za pomocą kilku różnych konwencji. Linki wskazują użytkownikom zawartość na tej samej stronie lub stronach sąsiednich albo na zewnętrznych witrynach lub pod zewnętrznymi adresami URL.

Zaplecze usługi Microsoft Learn używa usług Open Publishing Services (OPS), które obsługują język Markdown zgodny ze standardem CommonMark analizowane za pośrednictwem aparatu analizowania języka Markdig . Ten smak języka Markdown jest w większości zgodny z językiem GitHub Flavored Markdown (GFM), ponieważ większość dokumentów jest przechowywanych w usłudze GitHub i można je tam edytować. Dodatkowe funkcje są dodawane za pośrednictwem rozszerzeń języka Markdown.

Ważne

Wszystkie linki muszą być bezpieczne (https vs http) zawsze, gdy obiekt docelowy go obsługuje.

Tekst linku

Wyrazy, które umieścisz w tekście linku, powinny być przyjazne. Innymi słowy powinny one być normalnymi wyrazami lub tytułem strony, do której prowadzi link.

Ważne

Nie używaj ciągu "kliknij tutaj" jako tekstu linku. Nie jest ono dobre z punktu widzenia optymalizacji aparatu wyszukiwania, a ponadto nie opisuje odpowiednio miejsca docelowego.

Odpowiedź prawidłowa:

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

Odpowiedź nieprawidłowa:

  • 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).

Linki z jednego artykułu do innego

Istnieją dwa typy hiperlinków obsługiwanych przez system publikowania: adresy URL i linki do plików.

Link adresu URL może być ścieżką adresu URL względną względem katalogu głównego lub bezwzględnego adresu URL zawierającego https://learn.microsoft.compełną składnię adresu URL (na przykład https://github.com/MicrosoftDocs/PowerShell-Docs).

  • Użyj linków w postaci adresu URL, jeśli chcesz dodać link do zawartości spoza bieżącego zestawu dokumentów lub przełączać się pomiędzy automatycznie wygenerowanym dokumentem referencyjnym a artykułami koncepcyjnymi w ramach zestawu dokumentów.
  • Najprostszym sposobem utworzenia linku względnego jest skopiowanie adresu URL z przeglądarki, a następnie usunięcie ciągu https://learn.microsoft.com/en-us z wartości wklejonej do znacznika markdown.
  • Nie dołączaj ustawień regionalnych do adresów URL dla właściwości firmy Microsoft (na przykład usuń /en-us z adresu URL).

Link pliku jest używany do przechodzenia pomiędzy dwoma artykułami w ramach zestawu dokumentów.

  • We wszystkich ścieżkach plików używane są kreski ukośne (/) zamiast ukośników odwrotnych.

  • Link w artykule prowadzący do innego artykułu w tym samym katalogu:

    [link text](article-name.md)

  • Link w artykule prowadzący do artykułu w katalogu nadrzędnym bieżącego katalogu:

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

  • Link w artykule prowadzący do artykułu w podkatalogu bieżącego katalogu:

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

  • Link w artykule prowadzący do artykułu w podkatalogu katalogu nadrzędnego bieżącego katalogu:

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

  • Niektóre artykuły składają się zarówno z pliku , jak .yml i , gdzie .yml plik zawiera metadane i .md zawiera .md zawartość. W takim przypadku połącz się z plikiem .yml :

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

Uwaga

Element ~/ nie jest używany jako część linku w żadnym z powyższych przykładów. Aby utworzyć link do ścieżki bezwzględnej rozpoczynającej się od katalogu głównego repozytorium, rozpocznij link znakiem /. Uwzględnienie elementu ~/ powoduje utworzenie nieprawidłowych linków podczas poruszania się między repozytoriami źródłowymi w witrynie GitHub. Rozpoczęcie ścieżki od znaki / umożliwia jej prawidłowe rozpoznanie.

Zawartość opublikowana w witrynie Microsoft Learn ma następującą strukturę adresów URL:

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

Przykłady:

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

https://learn.microsoft.com/powershell/azure/overview?view=azurermps-5.1.1
  • <locale> — określa język artykułu (na przykład: en-us lub de-de)
  • <product-service> — nazwa produktu lub usługi (na przykład: powershell, dotnet lub azure)
  • [<feature-service>] — (opcjonalnie) nazwa funkcji produktu lub podusługi (na przykład: csharp lub load-balancer)
  • [<subfolder>] — (opcjonalnie) nazwa podfolderu w ramach funkcji
  • <topic> — nazwa pliku artykułu dla danego tematu (na przykład: load-balancer-overview lub overview)
  • [?view=\<view-name>] — (opcjonalnie) nazwa widoku używana przez selektor wersji dla zawartości z wieloma dostępnymi wersjami (na przykład azps-3.5.0)

Napiwek

W większości przypadków artykuły w tym samym zestawie dokumentów mają taki sam fragment adresu URL <product-service>. Na przykład:

  • Ten sam zestaw dokumentów:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/dotnet/framework/install
  • Inny zestaw dokumentów:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/visualstudio/whats-new

W przypadku linku zakładki do nagłówka w bieżącym pliku użyj symbolu krzyżyka, a po nim wstaw wyrazy nagłówka pisane małą literą. Usuń znaki interpunkcyjne z nagłówka i zastąp spacje kreskami:

[Managed Disks](#managed-disks)

Aby utworzyć link zakładki do nagłówka w innym artykule, użyj linku względnego w stosunku do pliku lub witryny, a następnie wstaw symbol krzyżyka i wyrazy nagłówka. Usuń znaki interpunkcyjne z nagłówka i zastąp spacje kreskami:

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

Możesz również skopiować link zakładki z adresu URL. Aby znaleźć adres URL, umieść wskaźnik myszy nad wierszem nagłówka w witrynie Microsoft Learn. Powinna pojawić się ikona linku:

Ikona linku w nagłówku artykułu

Kliknij ikonę linku, a następnie skopiuj tekst kotwicy zakładki z adresu URL (czyli fragment po krzyżyku).

Uwaga

Rozszerzenie Learn Markdown zawiera również narzędzia ułatwiające tworzenie linków.

Dodawanie jawnych linków kotwiczących z użyciem tagu HTML <a> nie jest wymagane ani zalecane poza stronami centrum i stronami docelowymi. Zamiast tego użyj automatycznie generowanych zakładek, zgodnie z opisem w części linki zakładek. Dla stron centrum i stron docelowych zadeklaruj następujące kotwice:

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

lub

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

Oraz dodaj następujący ciąg, aby utworzyć link do kotwicy:

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

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

Uwaga

Tekst kotwicy musi być zawsze pisany małymi literami i nie może zawierać spacji.

Linki XRef są zalecanym sposobem łączenia się z interfejsami API, ponieważ ułatwiają dostosowanie tekstu linku. Ponadto są weryfikowane w czasie kompilacji, a jeśli adres URL odwołania do interfejsu API zostanie zmieniony, link nadal będzie działać. Aby utworzyć link do wygenerowanych automatycznie stron dokumentacji interfejsu API w bieżącym zestawie dokumentów lub innych zestawach dokumentów, użyj linków XRef z unikatowym identyfikatorem (UID) typu lub elementu członkowskiego.

Napiwek

Rozszerzenie Pomocnika linku interfejsu API dla programu VS Code ułatwia wstawianie linków Xref interfejsu API platformy .NET do plików Markdown i XML.

Sprawdź, czy interfejs API, do którego chcesz utworzyć link, został opublikowany w witrynie Microsoft Learn , wpisując wszystkie lub jego pełną nazwę w przeglądarce interfejsu API platformy .NET lub w polu wyszukiwania windows UWP . Jeśli nie widzisz żadnych wyników, typ nie jest jeszcze wyświetlany w witrynie Microsoft Learn.

Można użyć jednej z następujących składni:

  • Linki automatyczne:

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

    Domyślnie tekst linku zawiera tylko nazwę elementu członkowskiego lub typu. Opcjonalny parametr zapytania displayProperty=nameWithType umożliwia uzyskanie tekstu w pełni kwalifikowanego linku, czyli przestrzeń_nazw.typ w przypadku typów oraz typ.element_członkowski w przypadku elementów członkowskich typu, w tym elementów członkowskich typu wyliczenia.

  • Linki języka Markdown:

    [link text](xref:UID)

    Użyj języka Markdown w przypadku linków XRef, jeśli chcesz dostosować wyświetlany tekst linku.

Przykłady:

  • <xref:System.String> jest wyświetlany jako String

  • <xref:System.String?displayProperty=nameWithType> wyświetla jako System.String

  • [String, klasa] (xref:System.String) wyświetla jako klasę String.

Parametr zapytania displayProperty=fullName działa w ten sam sposób co parametr displayProperty=nameWithType w przypadku klas. Oznacza to, że tekst linku staje się ciągiem przestrzeń_nazw.nazwa_klasy. Jednak w przypadku elementów członkowskich tekst linku jest wyświetlany jako namespace.classname.membername, co może być niepożądane.

Uwaga

W identyfikatorach UID jest uwzględniana wielkość liter. Na przykład poprawnie rozwiązuje problem <xref:System.Object> , ale <xref:system.object> nie.

Określanie identyfikatora UID

Identyfikator UID to zwykle w pełni kwalifikowana nazwa klasy lub elementu członkowskiego. Aby określić identyfikator UID, kliknij prawym przyciskiem myszy stronę Microsoft Learn dla typu lub elementu członkowskiego, wybierz pozycję Wyświetl źródło, a następnie skopiuj wartość zawartości ms.assetid.

Identyfikator ms.assetid w źródle strony internetowej

Kodowanie procentowe adresów URL

Znaki specjalne w identyfikatorze UID muszą być zakodowane w procentach w następujący sposób:

Znak Kodowanie HTML
* *

Przykład kodowania:

  • Wartość System.Exception.#ctor jest kodowana jako System.Exception.%23ctor

Typy ogólne

Typy ogólne to na przykład System.Collections.Generic.List<T>. Jeśli przejdziesz do tego typu w przeglądarce interfejsów API platformy .NET i spojrzysz na adres URL, zobaczysz, że element <T> jest zapisany jako -1 w adresie URL, co tak naprawdę odpowiada wartości `1:

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

Metody

Aby utworzyć link do metody, możesz utworzyć link do ogólnej strony metod, dodając znak gwiazdki (*) po nazwie metody, lub do konkretnego przeciążenia. Ogólnej strony możesz na przykład użyć, jeśli chcesz utworzyć link do metody <xref:System.Object.Equals*?displayProperty=nameWithType> bez podawania konkretnych typów parametrów. Na przykład:

Wartość <xref:System.Object.Equals*?displayProperty=nameWithType> tworzy link do Object.Equals

Aby utworzyć link do konkretnego przeciążenia, dodaj nawias po nazwie metody i dołącz pełną nazwę typu każdego parametru. Nie umieszczaj spacji pomiędzy nazwami typów — link wtedy nie zadziała. Na przykład:

Wartość <xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> tworzy link do Object.Equals(Object, Object)

Pliki dołączania znajdują się w innym katalogu, dlatego należy użyć dłuższych ścieżek względnych. Aby utworzyć link do artykułu z pliku dołączania, użyj następującego formatu:

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

Napiwek

Rozszerzenie Learn Authoring Pack dla programu Visual Studio Code ułatwia poprawne wstawianie linków względnych i zakładek bez konieczności określania ścieżek.

Selektor jest składnikiem nawigacji wyświetlanym w artykule w postaci listy rozwijanej. Wybranie wartości na liście rozwijanej powoduje otwarcie odpowiedniego artykułu w przeglądarce. Lista selektora często zawiera linki do ściśle powiązanych artykułów, na przykład takich, w których omawiane jest to samo zagadnienie w wielu językach programowania, lub do serii artykułów, które mają bliski związek ze sobą.

Jeśli masz selektory, które są osadzone w pliku dołączania, użyj następującej struktury linku:

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

Aby zawartość źródłowa była łatwiejsza do odczytania, możesz użyć linków w stylu odwołania. Linki w stylu odwołania zastępują składnię linków w tekście składnią uproszczoną, która umożliwia przeniesienie długich adresów URL na koniec artykułu. Oto przykład ze strony Daring Fireball:

Tekst wbudowany:

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

Odwołania do linków na końcu artykułu:

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

Upewnij się, że po dwukropku (przed linkiem) znajduje się spacja. Jeśli zapomnisz o wstawieniu spacji, tworząc linki do innych artykułów technicznych, w opublikowanym artykule linki te będą uszkodzone.

Aby utworzyć link do strony w innej witrynie firmy Microsoft (na przykład do strony cennika, umowy SLA lub czegokolwiek innego, co nie jest artykułem dokumentacji), użyj bezwzględnego adresu URL, ale pomiń ustawienia regionalne. Należy tak zrobić, aby linki działały w usłudze GitHub i na renderowanej stronie:

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

Aby środowisko użytkownika było jak najlepsze, należy zminimalizować odsyłanie do innych witryn. Z tego powodu linki do witryn innych firm, których czasami potrzebujemy, należy tworzyć, uwzględniając:

  • Odpowiedzialność: utwórz link do zawartości innej firmy, jeśli informacje są informacjami udostępnianymi przez tę firmę. Na przykład nie jest zadaniem firmy Microsoft informowanie o tym, jak używać narzędzi deweloperskich dla systemu Android — należy to do firmy Google. W razie potrzeby możemy wyjaśnić, jak używać narzędzi deweloperskich systemu Android za pomocą platformy Azure, ale to firma Google powinna opowiedzieć o tym, jak korzystać z jej narzędzi.
  • Zatwierdzenie przez kierowników projektów: zawartość innych firm powinna być zatwierdzana przez firmę Microsoft. Tworząc link do takiej zawartości, potwierdzamy niejako nasze zaufanie do niej oraz zobowiązanie, jeśli użytkownicy wykonają opisane instrukcje.
  • Przeglądy aktualności: upewnij się, że informacje innych firm są nadal aktualne, poprawne i istotne oraz że link nie został zmieniony.
  • Opuszczanie witryny: uświadom użytkownikom, że przechodzą do innej witryny. Jeśli kontekst wyraźnie tego nie stwierdza, dodaj frazę objaśniającą. Na przykład: "Wymagania wstępne obejmują narzędzia deweloperskie systemu Android, które można pobrać w witrynie programu Android Studio".
  • Następne kroki: Dodanie linku do bloga MVP można dodać w sekcji "Następne kroki". Pamiętaj jednak, aby upewnić się, że użytkownicy wiedzą, że opuszczają witrynę.
  • Prawne: Opisano to prawnie w obszarze Linki do witryn innych firm w stopce Warunki użytkowania na każdej stronie microsoft.com.