Sdílet prostřednictvím

Použití odkazů v dokumentaci

  • Článek

Tento článek popisuje, jak používat hypertextové odkazy ze stránek hostovaných v Microsoft Learn. Odkazy se snadno přidávají do markdownu pomocí několika různých konvencí. Odkazy směrují uživatele na obsah na stejné stránce, na jiné sousední stránky nebo na externí weby a adresy URL.

Back-end Microsoft Learn používá open publishing Services (OPS), který podporuje Markdown kompatibilní s CommonMark parsovacím modulem. Tato varianta Markdownu je většinou kompatibilní s GitHub Flavored Markdownem (GFM), protože většina dokumentů je uložená na GitHubu a dá se tam upravit. Další funkce se přidávají prostřednictvím rozšíření Markdownu.

Důležité

Všechna propojení musí být zabezpečená (https vs http. ) vždy, když cíl podporuje.

Text odkazu

Slova, která použijete v textu odkazu, by měla být popisná. Jinými slovy by mělo jít o normální slova nebo název stránky, na kterou odkazujete.

Důležité

Jako text odkazu nepoužívejte "klikněte sem". Je to špatné pro optimalizaci vyhledávacího webu a adekvátně to nepopisuje cílovou stránku.

Správně:

  • 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ávně:

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

Odkazy z jednoho článku na druhý

Systém publikování podporuje dva typy hypertextových odkazů: adresy URL a odkazy na soubory.

Odkaz na adresu URL může být cesta url relativní ke kořenovému https://learn.microsoft.comadresáři nebo absolutní adresa URL, která obsahuje úplnou syntaxi adresy URL (například https://github.com/MicrosoftDocs/PowerShell-Docs).

  • Použijte odkazy URL při odkazování na obsah mimo aktuální sadu dokumentace (docset) nebo mezi automaticky generovanými referenčními a koncepčními články v rámci sady dokumentace.
  • Nejjednodušší způsob, jak vytvořit relativní odkaz, je zkopírovat adresu URL z prohlížeče a pak z hodnoty, kterou vložíte do markdownu, odebrat https://learn.microsoft.com/en-us.
  • Nezahrnujte národní prostředí do adres URL pro vlastnosti Microsoftu (například odebrat /en-us z adresy URL).

Odkaz na soubor se používá k propojení mezi jedním článkem a jiným v rámci sady dokumentace.

  • Všechny cesty k souborům používají znaky lomítka (/) místo znaků zpětného lomítka.

  • Článek odkazuje na jiný článek ve stejném adresáři:

    [link text](article-name.md)

  • Článek odkazuje na článek v nadřazeném adresáři aktuálního adresáře:

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

  • Článek odkazuje na článek v podadresáři aktuálního adresáře:

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

  • Článek odkazuje na článek v podadresáři nadřazeného adresáře aktuálního adresáře:

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

  • Některé články se skládají z souboru .yml i .md souboru, kde .yml soubor obsahuje metadata a .md obsah. V takovém případě vytvořte odkaz na .yml soubor:

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

Poznámka:

V žádném z předchozích příkladů se jako součást odkazu nepoužívá ~/. Pokud chcete vytvořit odkaz na absolutní cestu, která začíná v kořenovém adresáři úložiště, začněte odkaz znakem /. Při zahrnutí řetězce ~/ vznikají neplatné odkazy pro navigaci do zdrojových úložišť na GitHubu. Problém se vyřeší, když bude cesta začínat znakem /.

Obsah publikovaný v Microsoft Learn má následující strukturu adres URL:

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

Pří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 (příklad: en-us nebo cs-cz).
  • <product-service> – Název produktu nebo služby (příklad: powershell, dotnet nebo azure).
  • [<feature-service>] – (nepovinné) Název funkce nebo dílčí služby produktu (například: csharp nebo load-balancer).
  • [<subfolder>] – (nepovinné) Název podsložky v rámci funkce.
  • <topic> – Název souboru článku pro téma (například: prehled-nastroje-pro-vyrovnavani-zatizeni nebo prehled).
  • [?view=\<view-name>] – (nepovinné) Název zobrazení používaný selektorem verzí pro obsah, který má více dostupných verzí (například: azps-3.5.0).

Tip

Ve většině případů mají články ve stejné sadě docset stejný fragment adresy URL <product-service>. Příklad:

  • Stejná sada dokumentů:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/dotnet/framework/install
  • Jiná sada dokumentů:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/visualstudio/whats-new

Pro odkaz na záložku na nadpis v aktuálním souboru použijte symbol hash následovaný slovy nadpisu malými písmeny. Odeberte z nadpisu interpunkci a nahraďte mezery pomlčkami:

[Managed Disks](#managed-disks)

K odkazu na nadpis záložky v jiném článku použijte odkaz na daný soubor nebo web, za kterým bude následovat symbol hash a text nadpisu. Odeberte z nadpisu interpunkci a nahraďte mezery pomlčkami:

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

Odkaz na záložku můžete také zkopírovat z adresy URL. Pokud chcete najít adresu URL, najeďte myší na řádek nadpisu v Microsoft Learn. Měla by se zobrazit ikona odkazu:

Ikona odkazu v nadpisu článku

Klikněte na ikonu odkazu a pak zkopírujte text ukotvení záložky z adresy URL (tj. část za znakem hash).

Poznámka:

Rozšíření Learn Markdown obsahuje také nástroje, které vám pomůžou vytvářet odkazy.

Explicitní odkazy na ukotvení používající značku <a> jazyka HTML není nutné přidávat a ani se to nedoporučuje, s výjimkou centra a cílových stránek. Místo toho použijte automaticky generované záložky, jak je popsáno v části odkazy na záložky. Pro centrum a cílové stránky deklarujte ukotvení následujícím způsobem:

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

nebo

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

A následující text k propojení na ukotvení:

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

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

Poznámka:

Text ukotvení musí být vždycky malými písmeny a nesmí obsahovat mezery.

Odkazy XRef jsou doporučeným způsobem propojení s rozhraními API, protože usnadňují přizpůsobení textu odkazu. Kromě toho se ověřují v době sestavení a pokud by se změnila adresa URL odkazu na rozhraní API, odkaz by stále fungoval. K odkazování na automaticky generované referenční stránky rozhraní API v aktuální sadě dokumentace nebo v jiných sadách dokumentace použijte odkazy XRef s jedinečným ID (UID) typu nebo člena.

Tip

Rozšíření pomocné rutiny reference k rozhraní API pro VS Code usnadňuje vkládání odkazů .NET API Xref do souborů Markdown a XML.

Zkontrolujte, jestli je rozhraní API, na které chcete odkazovat, publikováno v Microsoft Learn tak, že do vyhledávacího pole rozhraní .NET API nebo windows UPW zadáte celý název nebo jeho úplný název. Pokud se nezobrazují žádné výsledky, typ ještě není v Microsoft Learn.

Můžete použít jednu z následujících syntaxí:

  • Automatické odkazy:

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

    Ve výchozím nastavení text odkazu zobrazuje pouze název člena nebo typu. Volitelný parametr dotazu displayProperty=nameWithType vytvoří plně kvalifikovaný text odkazu, tj. namespace.type, pro typy a type.member pro členy typu, včetně členů výčtového typu.

  • Odkazy ve stylu Markdownu:

    [link text](xref:UID)

    Použijte odkazy ve stylu Markdownu pro odkazy XRef, když chcete přizpůsobit zobrazený text odkazu.

Příklady:

  • <xref:System.String> se zobrazí jako String

  • <xref:System.String?displayProperty=nameWithType> se zobrazí jako System.String

  • [String – třída] (xref:System.String) zobrazí jako Třídu String.

Parametr dotazu displayProperty=fullName funguje stejným způsobem jako displayProperty=nameWithType pro třídy. To znamená, že text odkazu se změní na namespace.classname. U členů se ale text odkazu zobrazí jako namespace.classname.membername, což může být nežádoucí.

Poznámka:

U identifikátorů UID se rozlišuje velikost písmen. Například <xref:System.Object> se správně vyřeší, ale <xref:system.object> ne.

Určení UID

Identifikátor UID je obvykle plně kvalifikovaná třída nebo název člena. Pokud chcete zjistit UID, klikněte pravým tlačítkem myši na stránku Microsoft Learn pro typ nebo člena, vyberte Zobrazit zdroj a zkopírujte hodnotu obsahu pro ms.assetid.

ms.assetid ve zdroji pro webovou stránku

Procentové kódování adres URL

Speciální znaky v UID musí být kódované v procentech následujícím způsobem:

Znak Kódování HTML
* *

Příklad kódování:

  • System.Exception.#ctor se kóduje jako System.Exception.%23ctor.

Obecné typy

Obecné typy jsou tyto typy jako například System.Collections.Generic.List<T>. Pokud přejdete na tento typ v prohlížeči .NET API a podíváte se na jeho adresu URL, uvidíte, že <T> je v adrese URL napsáno jako -1, což ve skutečnosti představuje `1:

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

Metody

Pokud chcete vytvořit odkaz na metodu, můžete buď vytvořit odkaz na obecnou stránku metody přidáním hvězdičky (*) za název metody, nebo na konkrétní přetížení. Obecnou stránku například použijte, když chcete vytvořit odkaz na metodu <xref:System.Object.Equals*?displayProperty=nameWithType> bez specifických typů parametrů. Příklad:

<xref:System.Object.Equals*?displayProperty=nameWithType> je odkaz na Object.Equals.

Jestliže chcete vytvořit odkaz na konkrétní přetížení, přidejte za název metody závorky a doplňte úplný název typu každého parametru. Nedávejte mezeru mezi názvy typů, jinak odkaz nebude fungovat. Příklad:

<xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> je odkaz na Object.Equals(Object, Object).

Jelikož jsou vložené soubory umístěné v jiném adresáři, musíte použít delší relativní cesty. Pokud chcete vytvořit odkaz na článek z vloženého souboru, použijte tento formát:

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

Tip

Rozšíření Learn Authoring Pack pro Visual Studio Code pomáhá správně vkládat relativní odkazy a záložky bez tedium zjišťování cest.

Volič je součást navigace, která se v článku dokumentace zobrazuje ve formě rozevíracího seznamu. Když čtenář vybere nějakou hodnotu v tomto rozevíracím seznamu, otevře prohlížeč vybraný článek. Seznam voliče zpravidla obsahuje odkazy na související články, například na stejnou problematiku v několika programovacích jazycích nebo na úzce související sérii článků.

Pokud máte voliče, které jsou začleněné ve vloženém souboru, použijte následující strukturu odkazu:

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

Pokud chcete, aby byl váš zdrojový obsah lépe čitelný, můžete použít odkazy z referencí. Odkazy z referencí nahradí syntax hotlinku jednodušší syntaxí, která vám umožní přesunout dlouhé adresy URL na konec článku. Zde je příklad z webu Daring Fireball:

Vložený text:

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

Odkazy referencí na konci článku:

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

Nezapomeňte mezi dvojtečkou a odkazem vytvořit mezeru. Pokud odkazujete na ostatní technické články a zapomenete mezeru vytvořit, odkaz nebude v publikovaném článku fungovat.

Pokud chcete vytvořit odkaz na jiný web ve vlastnictví Microsoftu (jako je stránka s ceníkem, stránka SLA nebo cokoli jiného, co není článek dokumentace), použijte absolutní adresu URL, ale vynechejte národní prostředí. Cílem je, aby odkazy fungovaly v GitHubu a na zobrazené stránce:

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

Nejlepší uživatelské prostředí minimalizuje odchod uživatelů na jiný web. Odkazy na weby třetích stran, které jsou občas potřeba, proto vytvářejte na základě těchto informací:

  • Odpovědnost: Na obsah třetích stran odkazujte, když jde o informace, které má sdílet třetí strana. Úkolem Microsoftu například není říkat lidem, jak používat vývojářské nástroje pro Android – to má udělat Google. Pokud je to potřeba, můžeme vysvětlit, jak vývojářské nástroje pro Android používat se službou Azure, ale jak tyto nástroje celkově používat by měl vysvětlit Google.
  • Schválení od PM: Požádejte Microsoft o schválení obsahu třetí strany. Odkazování na takový obsah znamená, že mu důvěřujeme, a zahrnuje odpovědnost, pokud se lidé těmito pokyny budou řídit.
  • Recenze aktuálnosti: Ujistěte se, že informace třetích stran jsou stále aktuální, správné a relevantní a že se odkaz nezměnil.
  • Přesměrování ven: Informujte uživatele, že budou přesměrováni na jiný web. Pokud to není jasné z kontextu, přidejte vysvětlení. Například: Požadavky zahrnují Vývojářské nástroje pro Android, které si můžete stáhnout na webu Android Studio.
  • Další kroky: Je v pořádku přidat odkaz na blog MVP v části Další kroky. Jen uživatele znovu nezapomeňte informovat, že budou přesměrováni na jiný web.
  • Právní informace: V zápatí Podmínek použití na každé stránce microsoft.com jsme právně pokryti odkazy na weby třetích stran.