Linkkien käyttäminen ohjeissa

Tässä artikkelissa kerrotaan, miten voit käyttää hyperlinkkejä Microsoft Learnissa isännöidyistä sivuista. Linkit on helppo lisätä merkintöihin erilaisilla keinoilla. Linkeillä käyttäjä voidaan ohjata samalla sivulla olevaan sisältöön, viereisiin sivuihin tai ulkoisiin sivustoihin ja URL-osoitteisiin.

Microsoft Learn -taustapalvelu käyttää Open Publishing Services (OPS) -palvelua, joka tukee CommonMark-yhteensopivaa Markdown-merkintää Markdig-jäsennyksellä . Tämä Markdown-versio on enimmäkseen yhteensopiva GitHub Flavored Markdown (GFM) -merkinnän kanssa, sillä useimmat asiakirjat on tallennettu GitHubiin, jossa niitä voidaan muokata. Muita toimintoja lisätään Markdown-laajennusten kautta.

Tärkeä

Kaikkien linkkien on oltava suojattuja (https vs http) aina, kun kohde tukee sitä.

Linkin teksti

Linkin tekstin tulee olla sävyltään ystävällinen. Sen on siis koostuttava normaaleista suomenkielistä sanoista tai linkitettävän sivun otsikosta.

Tärkeä

Älä käytä "napsauta tästä" -komentoa linkin tekstinä. Se heikentää hakukoneoptimoinnin tuloksia ja kuvailee kohdetta huonosti.

Oikein:

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

Väärin:

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

Artikkelien väliset linkit

Julkaisujärjestelmä tukee kahdenlaisia hyperlinkkejä: URL-osoitteita ja tiedostolinkkejä.

URL-osoite voi olla URL-polku, joka on suhteessa :n https://learn.microsoft.compääkansioon, tai absoluuttinen URL-osoite, joka sisältää täyden URL-osoitteen syntaksin (esimerkiksi https://github.com/MicrosoftDocs/PowerShell-Docs).

• Käytä URL-linkkejä, kun linkität nykyisen asiakirjajoukon ulkopuoliseen sisältöön tai asiakirjajoukon sisällä automaattisesti luodun viittauksen ja käsitteellisen artikkelin välillä.
• Yksinkertaisin tapa luoda suhteellinen linkki on kopioida URL-osoite selaimesta ja poistaa sitten https://learn.microsoft.com/en-us arvosta, jonka liität markdowniin.
• Älä sisällytä Microsoftin URL-osoitteiden ominaisuuksiin aluekohtaisia arvoja (poista esimerkiksi /en-us URL-osoitteesta).

Tiedostolinkkiä käytetään yhden artikkelin linkittämiseksi toiseen asiakirjajoukon sisällä.

• Kaikki tiedostopolut käyttävät vinoviivoja (/) kenoviivojen sijasta.

• Artikkeli sisältää linkin samassa hakemistossa olevaan toiseen artikkeliin:

  [link text](article-name.md)

• Artikkeli sisältää linkin nykyisen hakemiston päähakemistossa olevaan artikkeliin:

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

• Artikkeli sisältää linkin nykyisen hakemiston alihakemistossa olevaan artikkeliin:

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

• Artikkeli sisältää linkin nykyisen hakemiston päähakemiston alihakemistossa olevaan artikkeliin:

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

• Jotkin artikkelit koostuvat sekä - .yml .md tiedostosta että -tiedostosta, joissa .yml tiedosto sisältää metatietoja ja .md sisältöä. Tässä tapauksessa linkki tiedostoon .yml :

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

Muistiinpano

Missään edellisistä esimerkeistä ei ole käytetty merkkejä ~/ linkin osana. Jos haluat linkittää absoluuttiseen polkuun, joka alkaa säilön pääkansiosta, aloita linkki merkeillä /. Merkkien ~/ sisällyttäminen saa aikaan virheellisiä linkkejä siirryttäessä lähdesäilöjen välillä GitHubissa. Kun polku aloitetaan merkillä /, se määrittyy oikein.

Linkkien rakenne Microsoft Learnissa

Microsoft Learnissa julkaistulla sisällöllä on seuraava URL-rakenne:

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

Esimerkkejä:

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

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

• <locale> - määrittää artikkelin kielen (esimerkki: en-us tai de-de)
• <product-service> - tuotteen tai palvelun nimi (esimerkki: powershell, dotnet tai azure)
• [<feature-service>] - (valinnainen) tuotteen ominaisuuden tai alipalvelun nimi (esimerkki: csharp tai load-balancer)
• [<subfolder>] - (valinnainen) ominaisuuden sisäisen alikansion nimi
• <topic> - aiheen artikkelitiedoston nimi (esimerkki: load-balancer-overview tai overview)
• [?view=\<view-name>] - (valinnainen) näkymänimi, jota versionvalitsin käyttää useina versioina saatavalle sisällölle (esimerkki: azps-3.5.0)

Vihje

Useimmissa tapauksissa saman asiakirjajoukon artikkeleilla on sama <product-service>-URL-osoitteen osa. Esimerkkejä:

• Sama ohjesarja:
  • https://learn.microsoft.com/dotnet/core/get-started
  • https://learn.microsoft.com/dotnet/framework/install
• Eri asiakirjajoukko:
  • https://learn.microsoft.com/dotnet/core/get-started
  • https://learn.microsoft.com/visualstudio/whats-new

Kirjanmerkkilinkit

Kun kyseessä on kirjanmerkkilinkki, joka osoittaa nykyisen tiedoston otsikkoon, käytä ristikkomerkkiä ja sen perässä seuraavia otsikon sanoja pienin kirjaimin. Poista otsikosta välimerkit ja korvaa välilyönnit yhdysmerkeillä:

[Managed Disks](#managed-disks)

Jos haluat linkittää toisen artikkelin kirjanmerkkiotsikkoon, käytä tiedostokohtaista tai sivustokohtaista linkkiä sekä tunnistemerkkiä, jonka perässä on otsikon sanat. Poista otsikosta välimerkit ja korvaa välilyönnit yhdysmerkeillä:

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

Voit myös kopioida kirjanmerkkilinkin URL-osoitteesta. Löydät URL-osoitteen viemällä hiiren Microsoft Learnin otsikkorivin päälle. Tällöin sinun pitäisi nähdä linkkikuvake:

Napsauta linkkikuvaketta ja kopioi sitten kirjanmerkkiankkuriteksti URL-osoitteesta (ts. ristikkomerkin jälkeinen osa).

Muistiinpano

Learn Markdown -laajennukseen kuuluu myös työkaluja, joiden avulla voit luoda linkkejä.

Eksplisiittiset ankkurilinkit

Eksplisiittisten ankkurilinkkien lisääminen käyttämällä HTML-tunnistetta <a> ei ole välttämätöntä eikä suositeltavaa, paitsi keskuksessa ja saapumissivuilla. Käytä sen sijaan automaattisesti luotuja kirjanmerkkejä, jotka on kuvattu kohdassa kirjanmerkkilinkit. Esittele keskuksissa ja saapumissivuilla ankkurit seuraavasti:

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

or

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

Lisää seuraava linkki ankkuriin:

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

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

Muistiinpano

Ankkuritekstin on aina oltava pienin kirjaimin eikä se saa sisältää välilyöntejä.

XRef-linkit (ristiviittaus)

XRef-linkit ovat suositeltu tapa linkittää ohjelmointirajapintoihin, koska niiden avulla linkin tekstiä on helppo mukauttaa. Lisäksi ne vahvistetaan muodostamisaikana, ja jos ohjelmointirajapintaviittauksen URL-osoite muuttuisi, linkki toimisi edelleen. Voit linkittää automaattisesti luotuja ohjelmointirajapinnan viittaussivuja nykyisessä asiakirjajoukossa tai muissa asiakirjajoukoissa käyttämällä XRef-linkkejä, joissa on yksilöivä tyypin tai jäsenen tunnus (UID).

Vihje

VS Coden API Reference Link Helper - laajennuksen avulla .NET API Xref -linkkien lisääminen Markdown- ja XML-tiedostoihin on erittäin helppoa.

Tarkista, onko ohjelmointirajapinta, johon haluat linkittää, julkaistu Microsoft Learnissa kirjoittamalla sen koko nimen tai osan siitä .NET-ohjelmointirajapinnan selaimeen tai Windows UWP -hakuruutuun. Jos et näe mitään tuloksia, tyyppiä ei vielä ole Microsoft Learnissa.

Voit käyttää jotakin seuraavista syntakseista:

• Automaattiset linkit:

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

  Oletusarvoisesti linkkitekstissä näkyy vain jäsenen tai tyypin nimi. Valinnainen displayProperty=nameWithType-kyselyparametri tuottaa täysin määriteltyä linkkitekstiä, ts. nimitila.tyyppi tyypeille ja tyyppi.jäsen tyypin jäsenille.

• Markdown-tyyliset linkit:

  [link text](xref:UID)
  

  Käytä Markdown-tyylisiä linkkejä XRefille, kun haluat mukauttaa näyttöön tulevan linkkitekstin.

Esimerkkejä:

• <xref:System.String> näytetään muodossa String

• <xref:System.String?displayProperty=nameWithType> näytetään muodossa System.String

• [String class] (xref:System.String) näkyy Muodossa String class.

displayProperty=fullName-kyselyparametri toimii samalla tavalla kuin luokkien displayProperty=nameWithType. Linkki saa siis muodon nimitila.luokkanimi. Kuitenkin jäsenillä linkkiteksti näkyy muodossa nimitila.luokkanimi.jäsennimi, mikä voi olla epätoivottua.

Muistiinpano

Yksilöivän tunnuksen kirjainkoko on merkitsevä. Esimerkiksi <xref:System.Object> selvittuu oikein, mutta <xref:system.object> ei.

Yksilöivän tunnisteen määrittäminen

Yksilöivä tunniste on yleensä sama kuin täydellinen luokan tai jäsenen nimi. Voit määrittää yksilöivän tunnisteen napsauttamalla hiiren kakkospainikkeella tyypin tai jäsenen Microsoft Learn -sivua, valitsemalla Näytä lähde ja kopioimalla sitten sisältöarvon ms.assetidille.

URL-osoitteiden prosenttikoodaus

Yksilöivän tunnisteen erikoismerkit on koodattava prosenttilukuna seuraavasti:

Merkki	HTML-koodaus
*	*

Koodausesimerkki:

• System.Exception.#ctor koodataan muodossa System.Exception.%23ctor

Yleiset tyypit

Yleisiä tyyppejä ovat sellaiset tyypit kuin System.Collections.Generic.List<T>. Jos siirryt tähän tyyppiin .NET-ohjelmointirajapinnan selaimessa ja katsot sen URL-osoitetta, huomaat, että <T> kirjoitetaan URL-osoitteessa muodossa -1, joka oikeastaan tarkoittaa `1:

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

Menetelmät

Voit linkittää menetelmään joko linkittämällä yleiselle menetelmäsivulle niin, että lisäät tähtimerkin (*) menetelmän nimen perään, tai linkittämällä tiettyyn ylikuormitukseen. Käytä yleistä sivua esimerkiksi halutessasi linkittää menetelmään <xref:System.Object.Equals*?displayProperty=nameWithType> ilman erityisiä parametrityyppejä. Esimerkkejä:

<xref:System.Object.Equals*?displayProperty=nameWithType> linkittyy kohteeseen Object.Equals

Kun haluat linkittää tiettyyn ylikuormitukseen, lisää sulkumerkki menetelmän nimen perään ja sisällytä jokaisen parametrin täysi tyyppinimi. Älä jätä välilyöntiä tyyppinimien väliin, tai linkki ei toimi. Esimerkkejä:

<xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> linkittyy kohteeseen Object.Equals(Object, Object)

Linkit sisällytetyistä tiedostoista

Koska sisällytetyt tiedostot sijaitsevat toisessa hakemistossa, sinun on käytettävä pidempiä suhteellisia polkuja. Käytä seuraavaa muotoa, kun haluat linkittää sisällytetystä tiedostosta:

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

Vihje

Visual Studio Coden Learn Authoring Pack -laajennus auttaa lisäämään suhteelliset linkit ja kirjanmerkit oikein ilman polkujen selvittämisen vaivannäytymistä.

Linkit valitsimissa

Valitsin on siirtymiseen tarkoitettu komponentti, joka tulee ohjeartikkelissa näkyviin avattavana luettelona. Kun lukija valitsee arvon avattavasta luettelosta, selain avaa valitun artikkelin. Yleensä valitsimen luettelossa on linkkejä aiheeseen läheisesti liittyviin artikkeleihin, esimerkiksi samaa aihealuetta mutta eri ohjelmointikieltä käsitteleviin artikkeleihin tai toisiinsa liittyvien artikkeleiden sarjaan.

Jos sinulla on valitsimia, jotka on upotettu sisällytettyyn tiedostoon, käytä seuraavaa linkkirakennetta:

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

Viitetyyliset linkit

Viitetyylisten linkkien avulla voit helpottaa lähdesisällön luettavuutta. Viitetyyliset linkit korvaavat sidottujen linkkien syntaksin yksinkertaistetulla syntaksilla, jonka avulla pitkät URL-osoitteet voidaan siirtää artikkelin loppuun. Tässä on esimerkki, jonka Daring Fireball loi:

Sidottu teksti:

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

Viitelinkit artikkelin lopussa:

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

Muista sisällyttää kaksoispisteen jälkeen tuleva, linkkiä edeltävä välilyönti. Jos unohdat välilyönnin linkittäessäsi muihin teknisiin artikkeleihin, julkaistun artikkelin linkki ei toimi.

Linkit sivuille, jotka eivät kuulu teknisten ohjeiden sarjaan

Jos haluat linkittää toiselle Microsoftin omistamalle sivulle (esim. hinnastosivu, palvelutasosopimuksen sivu tai muu sivu, joka ei sisällä ohjeartikkelia), käytä absoluuttista URL-osoitetta, mutta poista aluetunnus. Tässä tavoitteena on, että linkit toimivat GitHubissa ja hahmonnetulla sivustolla:

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

Linkit kolmansien osapuolten sivustoille

Paras käyttäjäkokemus on sellainen, jossa vältetään ohjaamasta käyttäjä toiselle sivustolle. Kolmansien osapuolen sivustoille linkittämistä ei voi aina välttää, joten perusta tällaisille sivustoille johtavat linkit seuraaviin tietoihin:

• Vastuullisuus: Linkitä kolmannen osapuolen sisältöön, kun kyseisen tiedon jakaminen on kolmannen osapuolen vastuulla. Esimerkiksi Android-kehittäjätyökalujen käytön kuvailu on Googlen tehtävä, ei Microsoftin. Voimme tarvittaessa kertoa, miten Android-kehittäjätyökaluja käytetään Azuren kanssa, mutta Googlen on annettava ohjeet omien työkalujensa käyttöön.
• Projektipäällikön hyväksyntä: Pyydä Microsoftia hyväksymään kolmannen osapuolen sisältö. Sisältöön linkittäminen ilmaisee luottamuksemme ja vastuumme ihmisten noudattaessa annettuja ohjeita.
• Oikeellisuustarkastelut: Varmista, että kolmannen osapuolen tiedot ovat ajantasaiset, paikkaansa pitävät ja asianmukaiset eikä linkki ole muuttunut.
• Sivustolta poistuminen: Varmista, että käyttäjä tietää siirtyvänsä toiselle sivustolle. Jos tämä ei ilmene asiayhteydestä, lisää selventävä lause. Esimerkki: "Toimet edellyttävät Android-kehittäjätyökaluja, jotka voit ladata Android Studio -sivustolta."
• Seuraavat vaiheet: Voit lisätä linkin esimerkiksi MVP-blogiin "Seuraavat vaiheet" -osiossa. Varmista jälleen, että käyttäjät ymmärtävät poistuvansa sivustolta.
• Oikeudelliset tiedot: Jokaisen microsoft.com sivun alaviitteessä olevien KäyttöehtojenLinkit kolmansien osapuolten sivustoille -osio koskee oikeudelliset ehdot.