Používanie prepojení v dokumentácii

Tento článok popisuje používanie hypertextových prepojení zo stránok hosťovaných v službe Microsoft Learn. Prepojenia možno jednoducho pridať do markdownu s niekoľkými rôznymi konvenciami. Prepojenia smerujú používateľov na obsah na tej istej stránke, na ďalších susedných stránkach alebo na externých lokalitách a URL adresách.

Koncový server služby Microsoft Learn používa služby OPS (Open Publishing Services), ktoré podporujú CommonMark zhodný s jazykom Markdown, analyzovaný prostredníctvom nástroja Markdig . Táto konfigurácia jazyka Markdown je kompatibilná najmä s jazykom GitHub Flavored Markdown (GFM), pretože väčšina dokumentov je uložená v GitHube a je možné ich tam upravovať. Ďalšie funkcie sú pridané prostredníctvom rozšírení jazyka Markdown.

Text odkazu

Slová, ktoré použijete v texte odkazu, by mali byť priateľské. Inými slovami, mali by to byť normálne slovenské slová alebo názov stránka, na ktorú odkazujete.

Správne:

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

Nesprávne:

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

Prepojenie z jedného článku do druhého

Systém publikovania podporuje dva typy hypertextových prepojení: URL adresy a prepojenia na súbory.

Prepojenie s URL adresou môže byť cesta URL adresy, ktorá sa týka koreňového adresára https://learn.microsoft.comalebo absolútna URL adresa, ktorá obsahuje úplnú syntax URL adresy (napríklad https://github.com/MicrosoftDocs/PowerShell-Docs).

• Prepojenia s URL adresou používajte pri prepájaní na obsah mimo aktuálneho súboru dokumentácie alebo medzi automaticky generovanými odkazmi a koncepčnými článkami v rámci súboru dokumentácie.
• Najjednoduchším spôsobom vytvorenia relatívneho prepojenia je skopírovanie URL adresy z prehliadača. Potom je potrebné odstrániť https://learn.microsoft.com/en-us z hodnoty vloženej do jazyka Markdown.
• Nezahŕňajte miestne nastavenia do URL adries pre vlastnosti spoločnosti Microsoft (napríklad odstráňte /en-us z URL adresy).

Prepojenie na súbor sa používa na prepojenie z jedného článku na iný v rámci súboru dokumentácie.

• Všetky cesty k súboru používajú znaky lomky (/) namiesto znakov opačnej lomky.

• Článok odkazuje na ďalší článok v rovnakom adresári:

  [link text](article-name.md)

• Článok odkazuje na článok v nadradenom adresári aktuálneho adresára:

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

• Článok odkazuje na článok v podadresári aktuálneho adresára:

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

• Článok odkazuje na článok v podadresári nadradeného adresára aktuálneho adresára:

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

• Niektoré články pozostávajú zo .yml súboru a .md , v .yml ktorom súbor obsahuje metaúdaje a .md obsah. V takom prípade vytvorte .yml prepojenie na súbor:

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

Štruktúra prepojení na Microsoft Learn

Obsah publikovaný na lokalite Microsoft Learn má nasledujúcu štruktúru URL adresy:

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

Príklady:

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

https://learn.microsoft.com/powershell/azure/overview?view=azurermps-5.1.1

• <locale> – identifikuje jazyk článku (príklad: en-us alebo sk-sk)
• <product-service> – názov produktu alebo služby (príklad: powershell, dotnet alebo azure)
• [<feature-service>] – (voliteľné) názov funkcie produktu alebo podradenej služby (príklad: csharp alebo load-balancer)
• [<subfolder>] – (voliteľné) názov podpriečinka v rámci funkcie
• <topic> – názov súboru článku pre danú tému (príklad: load-balancer-overview alebo overview)
• [?view=\<view-name>] – (voliteľné) názov zobrazenia používaný selektorom verzie pre obsah, ktorý má k dispozícii viacero verzií (príklad: azps-3.5.0)

Uloženie záložiek s prepojeniami

Ak chcete vytvoriť záložku s prepojením na nadpis v aktuálnom súbore, použite symbol mriežky a za ním slová nadpisu malým písmom. Z nadpisu odstráňte interpunkciu a medzery nahraďte spojovníkmi:

[Managed Disks](#managed-disks)

Ak chcete vytvoriť prepojenie na záložku s nadpisom v inom článku, použite prepojenie vzťahujúce sa na súbor alebo lokalitu, zaň napíšte znak mriežky a nakoniec slová nadpisu. Z nadpisu odstráňte interpunkciu a medzery nahraďte spojovníkmi:

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

Môžete tiež skopírovať záložku s prepojením z URL adresy. Ak chcete vyhľadať URL adresu, ukážte kurzorom myši na čiaru nadpisu v službe Microsoft Learn. Mala by sa zobraziť ikona prepojenia:

Kliknite na ikonu prepojenia a potom skopírujte text ukotvenia záložky z URL adresy (čiže časť po znaku mriežky).

Explicitné ukotvovacie prepojenia

Pridanie explicitných ukotvovacích prepojení pomocou <a> značiek jazyka HTML nie je povinné ani odporúčané okrem centra a stránok prvého kontaktu. Namiesto toho použite automaticky generované záložky tak, ako je popísané v časti Uloženie záložiek s prepojeniami. Pre centrum a stránky prvého kontaktu deklarujte ukotvenia nasledujúcim spôsobom:

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

alebo

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

Nasledujúce sa týka prepojenie na ukotvenie:

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

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

Prepojenia XRef (krížové odkazy)

Prepojenia XRef sú odporúčaný spôsob prepojenia na rozhrania API, pretože zjednodušujú prispôsobenie textu prepojenia. Okrem toho sú overené v čase zostavenia a ak by sa zmenila URL adresa odkazu na rozhranie API, prepojenie bude naďalej fungovať. Ak chcete vytvoriť prepojenie na automaticky vygenerované referenčné stránky rozhrania API v aktuálnej súprave dokumentov alebo iných súpravách dokumentov, použite prepojenia XRef s jedinečným ID (UID) typu alebo člena.

Skontrolujte, či je rozhranie API, na ktoré chcete vytvoriť prepojenie, publikované v službe Microsoft Learn zadaním celého alebo časti názvu do vyhľadávacieho poľa Prehliadač rozhraní .NET API alebo Windows UWP. Ak sa nezobrazujú žiadne výsledky, typ ešte nie je v službe Microsoft Learn.

Môžete použiť jednu z nasledujúcich syntaxí:

• Automatické prepojenia:

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

  Text prepojenia predvolene zobrazuje iba názov člena alebo typu. Voliteľný parameter dotazu displayProperty=nameWithType vyprodukuje plne kvalifikovaný text prepojenia, čiže namespace.type pre typy a type.member pre členov typu vrátane členov enumerácie.

• Prepojenia v štýle jazyka Markdown:

  [link text](xref:UID)
  

  Ak chcete prispôsobiť zobrazený text prepojenia, použite prepojenia v štýle jazyka Markdown pre XRef.

Príklady:

• <xref:System.String> sa zobrazí ako String

• <xref:System.String?displayProperty=nameWithType> sa zobrazí ako System.String

• [String class] (xref:System.String) zobrazí sa ako String class.

Parameter dotazu displayProperty=fullName funguje rovnakým spôsobom ako displayProperty=nameWithType pre triedy. To znamená, že text prepojenia bude namespace.classname. V prípade členov sa však text prepojenia zobrazí ako namespace.classname.membername, čo môže byť nežiaduce.

Určenie identifikátora UID

Identifikátor UID je zvyčajne plne kvalifikovanou triedou alebo názvom člena. Ak chcete zistiť UID, kliknite pravým tlačidlom myši na stránku Microsoft Learn pre typ alebo člena, vyberte položku Zobraziť zdroj a potom skopírujte hodnotu obsahu pre ms.assetid.

Percentuálne kódovanie URL adries

Špeciálne znaky v identifikátore UID musia byť kódované percentovo nasledovne:

Príklad kódovania:

• System.Exception.#ctor sa kóduje ako System.Exception.%23ctor

Všeobecné typy

Všeobecné typy sú typy ako System.Collections.Generic.List<T>. Ak prejdete na tento typ v prehliadači rozhraní .NET API a pozriete sa na jeho URL adresu, uvidíte, že <T> sa v URL adrese zapisuje ako -1, čo v skutočnosti predstavuje `1:

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

Metódy

Ak chcete vytvoriť prepojenie na metódu, môžete buď prepojiť na všeobecnú stránku metódy pridaním hviezdičky (*) za názov metódy, alebo na konkrétne preťaženie. Všeobecnú stránku môžete použiť napríklad vtedy, keď chcete vytvoriť prepojenie na metódu <xref:System.Object.Equals*?displayProperty=nameWithType> bez konkrétnych typov parametrov. Napríklad:

<xref:System.Object.Equals*?displayProperty=nameWithType> prepája na Object.Equals

Ak chcete vytvoriť prepojenie na konkrétne preťaženie, pridajte okrúhlu zátvorku za názov metódy a zahrňte úplný názov typu každého parametra. Medzi názvy typov neumiestňujte znak medzery, v opačnom prípade prepojenie nebude fungovať. Napríklad:

<xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> prepája na Object.Equals(Object, Object)

Prepojenia od obsiahnutých súborov

Keďže sa obsiahnuté súbory nachádzajú v inom adresári, musíte použiť dlhšie relatívne cesty. V prípade prepojenia na článok zo zahrnutého súboru použite tento formát:

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

Prepojenia v selektoroch

Selektor je komponent navigačného panela, ktorý sa v rámci článku dokumentu zobrazuje ako rozbaľovací zoznam. Keď čitateľ vyberie hodnotu v rozbaľovacom zozname, prehliadač otvorí vybraný článok. Selektor väčšinou obsahuje prepojenia na súvisiace články. Buď ide o rovnakú problematiku vo viacerých programovacích jazykoch, alebo o tesne súvisiace články.

Ak máte selektory, ktoré sú vložené v obsiahnutom súbore, použite nasledujúcu štruktúru prepojenia:

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

Prepojenia s referenčným štýlom

Prepojenia s referenčným štýlom môžete použiť na zlepšenie čitateľnosti zdrojového obsahu. Prepojenia s referenčným štýlom nahradia syntax prepojenia inline so zjednodušenou syntaxou, ktorá umožňuje presunúť dlhé adresy URL na koniec článku. Tu je príklad z Daring Fireball:

Text inline:

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

Referencie prepojenia na konci článku:

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

Uistite sa, že pred prepojením použijete medzeru po dvojbodke. Ak zabudnete pri prepojení na iné technické články použiť medzeru, prepojenie bude v uverejnenom článku poškodené.

Prepojenia na stránky, ktoré nie sú súčasťou súboru technickej dokumentácie

Ak chcete vytvoriť prepojenie na stránku iného vlastníctva Microsoftu (napríklad stránka cenotvorby, stránka SLA alebo čokoľvek, čo nie je dokumentačným článkom), použite absolútnu adresu URL, ale vynechajte miestne nastavenie. Cieľom je, že prepojenia fungujú v GitHube a na vykreslenej stránke:

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

Prepojenia na lokality tretích strán

Najlepší používateľský zážitok minimalizuje odosielanie používateľov na inú lokalitu. Takže prepojte všetky prepojenia na stránky tretích strán, ktoré niekedy potrebujeme, podľa týchto informácií:

• Sledovateľnosť: Prepojenie na obsah tretej strany, keď sa má zdieľať informácia tretej strany. Príklad: Nie je úlohou Microsoftu informovať ľudí o tom, ako používať vývojárske nástroje pre Android. To má na starosť Google. V prípade potreby vieme vysvetliť, ako používať vývojárske nástroje Androidu s Azureom, ale Google by mal vysvetliť, ako používať ich nástroje.
• Odhlásenie PM: Žiadosť o odhlásenie Microsoftu v prípade obsahu tretej strany. Prepojením naň vyjadrujeme našu dôveru v neho a našu povinnosť, ak ľudia budú postupovať podľa pokynov.
• Kontrola aktuálnosti: Uistenie sa, že informácie tretej strany sú stále aktuálne, správne a relevantné a nezmenilo sa prepojenie.
• Opustenie lokality: Upovedomte používateľov, že prechádzajú na inú stránku. Ak to jasne nevyplýva z kontextu, pridajte kvalifikačnú frázu. Príklad: "Predpoklady zahŕňajú vývojárske nástroje Androidu, ktoré si môžete stiahnuť na lokalite Android Studio."
• Ďalšie kroky: Je v poriadku pridať prepojenie napríklad na blog MVP v časti "Ďalšie kroky". Znova sa uistite, či používatelia pochopili to, že opustia stránku.
• Právne informácie: Právne sme krytí v časti Prepojenia na lokality tretích strán v päte Podmienky používania na každej stránke microsoft.com.