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 na webu 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á službu OPS (Open Publishing Services), která podporuje markdown kompatibilní s CommonMark parsováním prostřednictvím modulu pro analýzu Markdig . Tato varianta markdownu je z větší části kompatibilní s verzí GFM (GitHub Flavored Markdown), protože většina dokumentů je uložená v GitHubu, aby bylo možné je upravovat. Další funkce se přidávají prostřednictvím rozšíření Markdownu.

Důležité

Všechny odkazy musí být zabezpečené (https versus http), když to cíl podporuje (což by měla drtivá většina).

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 url může být cesta URL, která je relativní ke kořenovému adresáři https://learn.microsoft.com, 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í ze souboru a .yml.md , 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ý na Webu 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>. Napří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. Adresu URL najdete tak, že na microsoft Learn najedete myší na řádek záhlaví. 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, jak odkazovat na rozhraní API, protože jsou ověřovány při sestavení. 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

Pomocí rozšíření Learn Markdown pro VS Code (součást sady Learn Authoring Pack) můžete vložit odkazy .NET XRref, které se zobrazí v prohlížeči rozhraní .NET API.

Zkontrolujte, jestli je rozhraní API, na které chcete odkazovat, publikováno na Microsoft Learn tak, že do vyhledávacího pole pro rozhraní .NET API nebo windows UPW zadáte celý název nebo jeho část. Pokud se nezobrazují žádné výsledky, typ ještě není na 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 class](xref:System.String) se zobrazí jako String – třída.

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. Členům se ale text odkazu zobrazuje 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 přeloží správně, ale <xref:system.object> ne.

Upozornění sestavení odkazu XRef a přírůstková sestavení

Přírůstkové sestavení (build) sestaví pouze soubory, které byly změněny nebo ovlivněny změnou. Pokud se zobrazí upozornění sestavení týkající se neplatného odkazu XRef, ale odkaz je ve skutečnosti platný, může to být proto, že sestavení bylo přírůstkové. Soubor, který způsobil upozornění, se nezměnil, takže nebyl sestaven a byla znovu přehrána minulá upozornění. Když se soubor změní nebo když spustíte úplné sestavení (úplné sestavení můžete spustit na ops.microsoft.com), upozornění zmizí. To je nevýhoda přírůstkových sestavení, protože DocFX neumí zjistit aktualizaci dat uvnitř služby XREF.

Určení UID

Identifikátor UID je obvykle plně kvalifikovaná třída nebo název člena. Existují alespoň dva způsoby, jak určit UID:

  • Klikněte pravým tlačítkem na stránku Microsoft Learn pro typ nebo člena, vyberte Zobrazit zdroj a zkopírujte hodnotu obsahums.assetid:

    ms.assetid ve zdroji pro webovou stránku

  • Použijte web automatického dokončování připojením části názvu typu nebo celého názvu typu k adrese URL. Například zadáním https://xref.docs.microsoft.com/autocomplete?text=Writeline do panelu Adresa v prohlížeči se zobrazí všechny typy a metody, které v názvu obsahují Writeline, spolu s jejich UID.

Ověření UID

Pokud chcete otestovat, jestli máte správné UID, nahraďte System.String v následující adrese URL vaším UID a pak ho vložte do panelu Adresa v prohlížeči:

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

Tip

V UID v adrese URL se rozlišují velká a malá písmena, a pokud kontrolujete UID přetížení metody, nepoužívejte mezi typy parametrů mezery.

Pokud se zobrazí něco podobného, máte správné UID:

[{"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"}]

Pokud se na stránce zobrazuje jenom [], máte nesprávné UID.

Procentové kódování adres URL

Speciální znaky v UID musí být kódovány ve formátu HTML následujícím způsobem:

Znak Kódování HTML
` %60
# %23
* %2A

Tady najdete úplný seznam procentových kódů.

Příklady kódování:

  • System.Threading.Tasks.Task`1 se kóduje jako System.Threading.Tasks.Task%601 (viz oddíl o obecných typech).

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

  • System.Object.Equals* se kóduje jako System.Object.Equals%2A.

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

Chcete-li vytvořit odkaz na obecný typ, například Seznam<T>, zakódujte znak zpětného znaku ` jako %60, jak je znázorněno v následujícím příkladu:

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

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%2A?displayProperty=nameWithType> bez specifických typů parametrů. Znak hvězdičky je kódován jako %2A. Například:

<xref:System.Object.Equals%2a?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. Napří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, aniž byste museli hledat cesty.

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: Když jde o informace, které má sdílet třetí strana, odkazujte na obsah třetí strany. Ú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: O schválení obsahu třetí strany požádejte Microsoft. Odkazování na takový obsah znamená, že mu důvěřujeme, a zahrnuje odpovědnost, pokud se lidé těmito pokyny budou řídit.
  • Kontroly aktuálnosti: Ověřujte, jestli jsou informace třetí strany stále aktuální, správné a relevantní a jestli 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 z webu Android Studio.“
  • Další kroky: V oddíle Další kroky můžete přidat odkaz například na blog MVP. Jen uživatele znovu nezapomeňte informovat, že budou přesměrováni na jiný web.
  • Právní náležitosti: Jsme právně krytí částí Odkazy na weby třetích stran v Podmínkách použití uvedených v zápatí každé stránky microsoft.com.