Hivatkozások használata a dokumentációban

Ez a cikk bemutatja, hogyan használhatja a Microsoft Learnben üzemeltetett oldalakra mutató hivatkozásokat. A hivatkozások Markdown jelölőnyelven való hozzáadása egyszerű: csupán néhány konvenciót kell követnie. A hivatkozások mutathatnak ugyanannak a lapnak egy másik részére, egy másikra egy szomszédos lapon, vagy külső webhelyekre és URL-címekre is.

A Microsoft Learn háttérrendszere Open Publishing Servicest (OPS) használ, amely támogatja a CommonMark-kompatibilis Markdown-elemzést a Markdig-elemzési motoron keresztül. Ez a Markdown-íz leginkább a GitHub Flavored Markdown (GFM) szolgáltatással kompatibilis, mivel a legtöbb dokumentum a GitHubon van tárolva, és ott szerkeszthető. Ez néhány Markdown-bővítményeken keresztül hozzáadott funkcióval egészül ki.

Hivatkozás szövege

A hivatkozásszövegbe foglalt szavaknak érthetőnek kell lenniük, azaz mindennapos angol szavakat célszerű használni, vagy a hivatkozott oldal címének kell lenniük.

Megfelelő:

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

Nem megfelelő:

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

Az egyik cikkből a másikra mutató hivatkozások

A közzétételi rendszer kétféle hivatkozást támogat: URL-címeket és fájlhivatkozásokat.

Az URL-hivatkozások lehetnek olyan URL-címek, amelyek a gyökértartományhoz https://learn.microsoft.comviszonyítva találhatók, vagy egy abszolút URL-cím, amely tartalmazza a teljes URL-szintaxist (például https://github.com/MicrosoftDocs/PowerShell-Docs).

• URL-linkeket az aktuális dokumentumkészleten kívüli tartalomhoz való csatoláskor, vagy a dokumentumkészlet automatikusan létrehozott referencia- és fogalmi cikkei között használhat.
• Relatív linkek létrehozásának legegyszerűbb módja az URL-cím kimásolása a böngészőből, majd a https://learn.microsoft.com/en-us rész eltávolítása az értékből.
• Ne tartalmazzon területi beállításokat a Microsoft-tulajdonságok URL-címeiben (például távolítsa el /en-us az URL-címből).

Fájlhivatkozásokkal a dokumentumkészlet két cikkét kapcsolhatja össze.

• Az összes fájlelérési út perjelet (/) használ a fordított perjel helyett.

• Egy cikk az ugyanabban a könyvtárban lévő másik cikkre mutat:

  [link text](article-name.md)

• Egy cikk az aktuális könyvtár szülő könyvtárában található cikkre hivatkozik:

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

• Egy cikk az aktuális könyvtár alkönyvtárában található cikkre hivatkozik:

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

• Egy cikk az aktuális könyvtár szülőkönyvtárának alkönyvtárában található cikkre hivatkozik:

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

• Egyes cikkek egy és .md fájlból .yml is állnak, ahol a .yml fájl metaadatokat és a .md tartalmat tartalmazza. Ebben az esetben hivatkozik a .yml fájlra:

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

Hivatkozások felépítése a Microsoft Learnben

A Microsoft Learnben közzétett tartalom URL-struktúrája a következő:

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

Példák:

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

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

• <locale> – a cikk nyelvét azonosítja (például en-us vagy de-de)
• <product-service> – a termék vagy szolgáltatás neve (például powershell, dotnet vagy azure)
• [<feature-service>] – (nem kötelező) a termék funkciójának vagy alszolgáltatásának neve (például csharp vagy load-balancer)
• [<subfolder>] – (nem kötelező) a funkció egy almappájának neve
• <topic> – a cikk fájljának vagy témakörének neve (például load-balancer-overview vagy overview)
• [?view=\<view-name>] – (nem kötelező) a verzióválasztó nézetneve olyan tartalom esetén, amely több elérhető verzióval rendelkezik (például azps-3.5.0)

Könyvjelző-hivatkozások

Az aktuális fájl egy címsorára való könyvjelző-hivatkozáshoz egy kettőskereszt jel után írja be kisbetűkkel a címsor szövegét. Távolítsa el a fejléc írásjeleit, a szóközöket pedig cserélje kötőjelekre:

[Managed Disks](#managed-disks)

Egy másik cikk könyvjelzőfejlécére való hivatkozást kezdje a fájlra vagy webhelyre mutató relatív hivatkozással és a kettőskereszt jellel, majd folytassa a fejléc szövegével. Távolítsa el a fejléc írásjeleit, a szóközöket pedig cserélje kötőjelekre:

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

Az URL-címből is kimásolhatja a könyvjelző hivatkozását. Az URL-cím megkereséséhez vigye az egérmutatót a Microsoft Learn címsorára. Ekkor megjelenik egy hivatkozás ikon:

Kattintson a hivatkozás ikonra, majd másolja ki a könyvjelző rögzített szövegét (a kivonat utáni részt) az URL-címből.

Explicit horgonyhivatkozások

Az <a> HTML-címkével készíthető explicit horgonyhivatkozások hozzáadása nem szükséges és nem is ajánlott, csak a főoldalak és kezdőlapok esetében. Ehelyett használjon automatikusan generált könyvjelzőket a könyvjelző-hivatkozások szakaszban leírtak szerint. A főoldalaknál és kezdőlapoknál a következő módon deklarálhatja a horgonyokat:

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

vagy

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

Adja hozzá a következő hivatkozást a horgonyhoz:

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

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

XRef-hivatkozások (kereszthivatkozások)

Az XRef-hivatkozások az API-kra mutató hivatkozások ajánlott módjai, mivel megkönnyítik a hivatkozás szövegének testreszabását. Emellett a létrehozáskor érvényesítik őket, és ha az API-referencia URL-címe módosulna, a hivatkozás továbbra is működni fog. Az aktuális dokumentumkészletben vagy más dokumentumkészletekben szereplő, automatikusan generált API-referenciaoldalakra mutató hivatkozás létrehozásához használjon XRef-hivatkozásokat a típus vagy tag egyedi azonosítójával (UID).

Ellenőrizze, hogy a hivatkozni kívánt API közzé van-e téve a Microsoft Learnben. Ehhez írja be a teljes nevét a .NET API böngészőbe vagy a Windows UWP keresőmezőbe. Ha nem jelenik meg találat, a típus még nem szerepel a Microsoft Learnben.

Az következő szintaxisok egyikét használhatja:

• Automatikus hivatkozások:

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

  Alapértelmezés szerint a hivatkozás szövegében csak a tag vagy a típus neve jelenik meg. A választható displayProperty=nameWithType lekérdezési paraméter teljes mértékben minősített hivatkozásszöveget hoz létre, azaz a namespace.type szöveget típusokhoz, és a típus.members szöveget a típustagokhoz, így az enumerálási típustagokhoz is.

• Markdown stílusú hivatkozások:

  [link text](xref:UID)
  

  Markdown stílusú XRef-hivatkozásokat a megjelenített hivatkozásszöveg testreszabásához használhat.

Példák:

• <xref:System.String>String

• <xref:System.String?displayProperty=nameWithType>System.String

• [Sztringosztály] (xref:System.String) sztringosztályként jelenik meg.

A displayProperty=fullName lekérdezési paraméter ugyanúgy működik, mint az osztályok esetében a displayProperty=nameWithType. A hivatkozás szövege így namespace.classname lesz. A tagok esetében azonban a hivatkozás szövege névtér.classname.membername néven jelenik meg, ami nem feltétlenül kívánatos.

A UID meghatározása

A UID általában a teljes osztály- vagy tagnév. A UID meghatározásához kattintson a jobb gombbal a Microsoft Learn lapra egy típushoz vagy taghoz, válassza a Forrás megtekintése lehetőséget, majd másolja az ms.assetid tartalomértékét.

URL-címek százalékos kódolása

A UID speciális karaktereit az alábbiak szerint kell százalékban kódolni :

Kódolási példa:

• A System.Exception.#ctor kódolása: System.Exception.%23ctor

Általános típusok

Az általános típusok a következőhöz hasonlóak: System.Collections.Generic.List<T>. Ha megkeresi ezt a típust a .NET API-böngészőben, és megvizsgálja az URL-címét, láthatja, hogy a <T> -1 formában szerepel, amely a következőt jelöli: `1:

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

Metódusok

Ha egy metódusra szeretne hivatkozni, egy csillagot (*) adhat hozzá a metódusnév végéhez, így egy általános metóduslapra hivatkozhat. Egy adott túlterhelésre is hivatkozhat. Ha például a <xref:System.Object.Equals*?displayProperty=nameWithType> metódusra szeretne hivatkozni adott paramétertípusok nélkül, használja az általános oldalt. Példa:

A <xref:System.Object.Equals*?displayProperty=nameWithType> a következőre hivatkozik: Object.Equals

Ha egy adott túlterhelésre szeretne hivatkozni, a metódus neve után adjon hozzá egy zárójelet, és adja meg az egyes paraméterek teljes típusnevét. A típusnevek közé ne helyezzen szóközt, különben a hivatkozás nem fog működni. Példa:

A <xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> a következőre hivatkozik: Object.Equals(Object, Object)

Beágyazásokhoz tartozó hivatkozások

A beágyazott fájlok másik könyvtárban találhatók, ezért hosszabb relatív elérési utakat kell használnia. Ha beágyazott fájlból szeretne cikkre mutató hivatkozást létrehozni, használja a következő formátumot:

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

A választókban lévő hivatkozások

A kiválasztó egy navigációs összetevő, amely legördülő lista formájában jelenik meg a Docs-cikkekben. Amikor az olvasó kiválaszt egy értéket a legördülő listából, a böngészőben megnyílik a kiválasztott cikk. A kiválasztó-lista általában a szorosan kapcsolódó cikkekre, például ugyanarra a témára több programnyelven, vagy egy szorosan kapcsolódó cikksorozatra mutató hivatkozásokat tartalmaz.

Ha beágyazásba ágyazott kiválasztókkal rendelkezik, akkor a következő hivatkozásszerkezetet kell használnia:

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

Referencia típusú hivatkozások

Referencia típusú hivatkozások használatával leegyszerűsíthető a forrástartalom olvasása. A referencia típusú hivatkozások olyan egyszerűsített szintaxissal váltják fel a szövegbeli hivatkozásszintaxist, amely lehetővé teszi a hosszú URL-címek cikk végére való áthelyezését. Íme a Daring Fireball példája:

Beágyazott szöveg:

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

Cikk végén található hivatkozások:

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

Ügyeljen arra, hogy a kettőspont és a hivatkozás között szóközt hagyjon. Ha más műszaki cikkekre mutató hivatkozást hoz létre, és elfelejt szóközt hagyni, akkor a hivatkozás hibásan szerepel majd a közzétett cikkben.

Hivatkozás a műszaki dokumentációkészlet részét nem képező lapokra

Ha a Microsoft tulajdonában lévő másik lapra mutató hivatkozást szeretne létrehozni (például az egyik díjszabási lapra, SLA-lapra vagy bármi olyanra, amely nem dokumentációs cikk), használjon abszolút URL-címet, de hagyja ki a területi kódot. A cél itt az, hogy a hivatkozások működjenek a GitHubban és a megjelenített webhelyen:

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

Harmadik fél webhelyeire mutató hivatkozás

A legjobb felhasználói környezet az, amely minimális szintre csökkenti a felhasználók másik webhelyre való küldését. Ezért a (néha valóban szükséges) külső webhelyekre mutató hivatkozásokat a következő információk alapján hozza létre:

• Felelősség: Akkor hivatkozzon külső tartalomra, ha az külső fél megosztani kívánt információja. Például nem a Microsoft feladata tájékoztatni a felhasználókat az androidos fejlesztői eszközök használatának módjáról (illetve nem a Microsoft a megfelelő platform erre). Ez ugyanis a Google dolga. Ha szükséges, el tudjuk magyarázni az androidos fejlesztői eszközök Azure-ral való használatának módját, de a Google feladata ismertetni az eszközeik használatát.
• PM-jóváhagyás: Külső tartalmakra való hivatkozáshoz kérje a Microsoft jóváhagyását. Az ilyen tartalomra mutató hivatkozás létrehozása az abba vetett bizalmunkról tanúskodik, és felelősségvállalást jelent arra az esetre, ha a felhasználók követik az ott szereplő utasításokat.
• Frissesség-felülvizsgálatok: Győződjön meg arról, hogy a külső féltől származó információk továbbra is aktuálisak, helyesek és relevánsak, és hogy a hivatkozás nem változott.
• Külső webhely: Tudassa a felhasználókkal, hogy másik webhelyet keresnek fel. Ha a kontextusból nem derül ki világosan, biztosítson valamilyen tájékoztató szöveget. Például: "Az előfeltételek közé tartoznak az Android Fejlesztői eszközök, amelyeket az Android Studio webhelyén tölthet le."
• Következő lépések: Nem gond, ha például egy MVP-blogra mutató hivatkozást ad hozzá a "Következő lépések" szakaszban. Itt is fontos tudatni a felhasználókkal, hogy elhagyják a webhelyet.
• Jogi: Jogi szempontból a Használati feltételek láblécében található, külső webhelyekre mutató hivatkozások vonatkoznak minden microsoft.com oldalon.