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

  • Cikk

Ez a cikk a Microsoft Learn által üzemeltetett lapok hivatkozásainak használatát ismerteti. 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 az Open Publishing Services (OPS) szolgáltatást használja, amely támogatja a Markdig-elemzési motoron keresztül elemezett CommonMark-kompatibilis markdownt. Ez a jelölőnyelv-változat nagyrészt kompatibilis a GitHub Flavored Markdown (GFM) jelölőnyelvvel, 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.

Fontos

Minden hivatkozásnak biztonságosnak kell lennie (https, nem pedig http), ha a cél támogatja azt (az esetek többségében igen).

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.

Fontos

Ne használja a "kattintson ide" szöveget hivatkozásszövegként. Ez ugyanis hátrányos a keresőmotor-optimalizálás szempontjából, és nem megfelelően írja le a célt.

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ét hiperhivatkozás-típust támogat: URL-címeket és fájlhivatkozásokat.

Az URL-hivatkozások lehetnek olyan URL-címek, amelyek a gyökeréhez 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ímrő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 egy .yml fájlból állnak, ahol a .yml fájl metaadatokat és a .md tartalmat .md tartalmazza. Ebben az esetben csatolja a .yml fájlt:

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

Megjegyzés

Az előző példák egyikében sem szerepel a ~/ a hivatkozás részeként. Ha a tárház gyökerénél kezdődő abszolút elérési útra szeretne hivatkozni, a hivatkozást / jellel kezdje. A ~/ használata érvénytelen hivatkozást eredményez a GitHub forrástárházaiba valló navigáláskor. A probléma kikerülhető, ha az útvonal elején a / szerepel.

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)

Tipp

A legtöbb esetben az ugyanabban a dokumentumkészletben található cikkek ugyanazzal a <product-service> URL-részlettel rendelkeznek. Példa:

  • Ugyanaz a dokumentumkészlet:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/dotnet/framework/install
  • Különböző dokumentumkészlet:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/visualstudio/whats-new

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 Címsor sor fölé a Microsoft Learnben. Ekkor megjelenik egy hivatkozás ikon:

Hivatkozás ikon a cikk címsorában

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.

Megjegyzés

A Learn Markdown bővítmény olyan eszközökkel is rendelkezik, amelyekkel hivatkozásokat hozhat létre.

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)

Megjegyzés

A horgony szövegének kisbetűkből kell állnia, és nem tartalmazhat szóközöket.

Az XRef-hivatkozások az API-kra való hivatkozás ajánlott formái, mivel ezeket a rendszer még a buildeléskor érvényesíti. 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).

Tipp

A VS Code Learn Markdown bővítményével (a Learn Authoring Pack részeként) .NET XRref hivatkozásokat szúrhat be, amelyek a .NET API-böngészőben jelennek meg.

Ellenőrizze, hogy a hivatkozni kívánt API közzé van-e téve a Microsoft Learnben . Ehhez írja be az összes vagy néhány teljes nevét a .NET API böngészőben vagy a Windows UWP keresőmezőjében. 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> a következőképpen jelenik meg: String

  • <xref:System.String?displayProperty=nameWithType> a következőként jelenik meg: System.String

  • A [String class](xref:System.String)karakterláncosztá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 namespace.classname.membername-ként jelenik meg, ami nem mindig előnyös.

Megjegyzés

Az UID-k megkülönböztetik a kis- és nagybetűket. A rendszer például megfelelően oldja fel a <xref:System.Object> értéket, ezt azonban nem: <xref:system.object>.

XRef-létrehozási figyelmeztetések és növekményes buildek

A növekményes build csak olyan fájlokat hoz létre, amelyek módosultak vagy egy módosítás miatt megváltoztak. Ha egy érvénytelen XREF-hivatkozásról szóló buildelési figyelmeztetést kap, a hivatkozás azonban mégis érvényes, ez növekményes buildre utalhat. A figyelmeztetést okozó fájl nem változott, ezért nem jött létre, és megismételte a korábbi figyelmeztetéseket. A figyelmeztetés eltűnik, amint a fájl módosul vagy Ön aktivál egy teljes buildelést (ezt az ops.microsoft.com oldalon teheti meg). Ez a növekményes buildek hátránya, mivel a DocFX nem képes észlelni az adatfrissítéseket az XREF szolgáltatásban.

A UID meghatározása

A UID általában a teljes osztály- vagy tagnév. A UID megállapításának legalább két módja van:

  • Kattintson a jobb gombbal egy típus vagy tag Microsoft Learn-lapjára, válassza a Forrás megtekintése lehetőséget, majd másolja ki az ms.assetidtartalomértékét:

    a weblap forrásának ms.assetid eleme

  • Használja a webhely automatikus kiegészítése funkciót. Ehhez a típus nevének egy részletét vagy a teljes nevet fűzze hozzá az URL-címhez. Ha például a https://xref.docs.microsoft.com/autocomplete?text=Writeline címet adja meg a böngésző címsorában, a Writeline szöveget a nevükben tartalmazó összes típus és metódus megjelenik a UID-val együtt.

A UID ellenőrzése

Ha ellenőrizni szeretné, hogy a megfelelő UID-val rendelkezik-e, cserélje az alábbi URL-cím System.String elemét a UID-ra, majd illessze be egy böngésző címsorába:

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

Tipp

Az URL-cím UID-je megkülönbözteti a kis- és nagybetűket, és ha egy metódustúlterhelési UID-t használ, ne tegyen szóközt a paramétertípusok közé.

Ha a következőhöz hasonló jelenik meg, akkor a megfelelő UID-val rendelkezik:

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

Ha az oldalon csak a [] elem jelenik meg, helytelen UID-t használ.

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

A UID speciális karaktereit az alábbi HTML-kódolással kell ellátni:

Karakter HTML-kódolás
` %60
# %23
* %2A

Tekintse meg a százalékos kódok teljes listáját.

Kódolási példák:

  • A System.Threading.Tasks.Task`1 kódolása: System.Threading.Tasks.Task%601 (lásd az általános típusokról szóló szakaszt)

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

  • A System.Object.Equals* kódolása: System.Object.Equals%2A

Á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

Ha általános típusra szeretne hivatkozni, például a T> listára<, kódolja a ` backtick karaktert %60-ként, az alábbi példában látható módon:

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

Metódusok

Ha egy metódusra szeretne hivatkozni, egy csillagot (*) adhat hozzá metódus nevének végén, így egy általános metóduslapra hivatkozva, vagy egy adott túlterhelésre hivatkozhat. Ha például a <xref:System.Object.Equals%2A?displayProperty=nameWithType> metódusra szeretne hivatkozni adott paramétertípusok nélkül, használja az általános oldalt. A csillag karakter kódolása: %2A. Példa:

A <xref:System.Object.Equals%2a?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)

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)

Tipp

A Visual Studio Code Learn Authoring Pack bővítménye segítségével helyesen szúrhat be relatív hivatkozásokat és könyvjelzőket az elérési utak megállapítása nélkül.

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

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

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.
  • Naprakészségi ellenőrzések: Győződjön meg arról, hogy a harmadik féltől származó adatok még aktuálisak, pontosak és relevánsak, illetve hogy a hivatkozás nem módosult.
  • 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élda: „Az előfeltételek közé tartoznak az androidos fejlesztői eszközök, amelyeket az Android Studio webhelyéről tölthet le.”
  • Következő lépések: Nyugodtan felvehet például egy Következő lépések című szakaszba egy MVP-blogra mutató hivatkozást. Itt is fontos tudatni a felhasználókkal, hogy elhagyják a webhelyet.
  • Jogi tudnivalók: Jogi szempontból az összes microsoft.com-oldal láblécében szereplő Használati feltételekkülső felek webhelyeire mutató hivatkozásokról szóló szakasza vonatkozik ránk.