Metatieto- ja Markdown-malli .NET-ohjeita varten

Tämä dotnet/docs-malli sisältää esimerkkejä Markdown-syntaksista sekä ohjeita metatietojen määrittämiseen.

Kun luot Markdown-tiedostoa, kopioi liitteenä oleva malli uuteen tiedostoon, täytä metatiedot alla olevien ohjeiden mukaan ja määritä artikkelin otsikolle yllä oleva H1-otsikko.

Metatieto

Pakolliset metatiedot on annettu alla olevassa metatietolohkon esimerkissä:

---
title: [ARTICLE TITLE]
description: [usually a summary of your first paragraph. It gets displayed in search results, and can help drive the correct traffic if well written.]
author: [GITHUB USERNAME]
ms.date: [CREATION/UPDATE DATE - mm/dd/yyyy]
---
# The H1 should not be the same as the title, but should describe the article contents

Kaksoispisteen (:) ja metatietoelementin välissä täytyy olla välilyönti.
Arvon (esimerkiksi otsikon) sisäiset kaksoispisteet rikkovat metatietojen jäsennyksen. Jos haluat käyttää kaksoispistettä otsikossa, käytä otsikon ympärillä kaksoispisteitä (esimerkiksi title: "Writing .NET Core console apps: An advanced step-by-step guide").
title: Näkyy hakukoneiden tuloksissa. Tässä oleva otsikko ei saa olla täsmälleen sama kuin H1-otsikko, ja siinä voi olla korkeintaan 60 merkkiä.
description: Yhteenveto artikkelin sisällöstä. Se näkyy yleensä haun tulossivulla, mutta se ei vaikuta hakutulosten keskinäiseen järjestykseen. Kuvauksen pituus voi olla 115–145 merkkiä välilyönnit mukaan lukien.
author: Author-kentässä tulee olla artikkelin kirjoittajan GitHub-käyttäjänimi.
ms.date: Viimeisimmän merkittävän päivityksen päivämäärä. Päivitä tämä nykyisissä artikkeleissa, jos olet tarkistanut ja päivittänyt koko artikkelin. Pieniä muutoksia, kuten kirjoitusvirheiden korjauksia, ei lasketa merkittäviksi päivityksiksi.

Jokaiseen artikkeliin kuuluu muutakin metatietoa, mutta suurin osa metatietoarvoista lisätään kansiotasolla määrittämällä ne docfx.json-tiedostossa.

Markdownin perusteet, GFM ja erikoismerkit

Voit opetella Markdownin, GFM:n (GitHub Flavored Markdown) ja OPS-kohtaisten laajennusten perustiedot Markdownin viitetiedot -artikkelista.

Markdown käyttää muotoilussa erikoismerkkejä, kuten *, 'ja #. Jos haluat käyttää jotakin näistä merkeistä sisällössäsi, sinun on tehtävä jompi kumpi seuraavista:

Lisää kenoviiva erikoismerkin eteen (esimerkiksi \* *).
Käytä HTML-entiteetin koodia merkkiä varten (esimerkiksi * *).

Tiedostonimet

Tiedostonimissä noudatetaan seuraavia sääntöjä:

Nimessä saa olla ainoastaan pieniä kirjaimia, numeroita ja tavuviivoja.
Ei välilyöntejä tai välimerkkejä. Erota tiedostonimessä esiintyvät sanat ja numerot toisistaan tavuviivoilla.
Käytä selkeitä toiminnallisia verbejä, kuten develop (kehitä), buy (osta), build (luo), troubleshoot (vianmääritys). Ei -ing-sanoja.
Ei pieniä sanoja, kuten ja, tai sekä englannin artikkelit.
Nimissä on käytettävä Markdown-merkintätapaa ja .md-tiedostotunnistetta.
Pidä tiedostonimet suhteellisen lyhyinä. Ne ovat osa artikkeleidesi URL-osoitteita.

Otsikot

Kirjoita isolla alkukirjaimella vain otsikon ensimmäinen sana ja erisnimet. Otsikon ensimmäinen sana kirjoitetaan aina isolla alkukirjaimella.

Tekstin muotoilu

Kursivointi
Käytä tiedostojen, kansioiden, polkujen (erota pitkät kohteet omalle rivilleen) ja uusien termien kohdalla.

Lihavointi
Käytä viitatessa käyttöliittymäelementteihin.

Code
Käytä tekstin sisäiseen koodiin, kielen avainsanoihin, NuGet-pakettien nimiin, komentorivin komentoihin, tietokantataulukoihin ja sarakkeiden nimiin sekä URL-osoitteisiin, jos haluat, ettei niitä voi napsauttaa.

Linkit

Linkit-yleisartikkelista saat lisätietoja ankkureista, sisäisistä linkeistä, muihin asiakirjoihin osoittavista linkeistä, koodisisällöistä ja ulkoisista linkeistä.

.NET-ohjetiimi noudattaa seuraavia tapoja:

Käytämme yleensä suhteellisia linkkejä ja kehotamme välttämään ~/:n käyttöä linkeissä, koska suhteelliset linkit selvitetään GitHubissa lähteessä. ~/-merkkiä käytetään kuitenkin polun ilmaisemiseen linkitettäessä riippuvaisessa säilössä olevaan tiedostoon. Koska riippuvaisen säilön tiedostot ovat eri sijainnissa GitHubissa, linkit eivät toimi oikein suhteellisilla linkeillä riippumatta siitä, miten ne on kirjoitettu.
C#:n kielimääritykset ja Visual Basicin kielimääritykset sisältyvät .NET-asiakirjoihin, kun lähde sisällytetään kielisäilöistä. Markdown-lähteitä hallitaan csharplang- ja vblang-säilöissä.

Määrityksen linkkien on osoitettava niihin lähdehakemistoihin, joihin kyseiset määritykset kuuluvat. C#:n osalta kyseessä on ~/_csharplang/spec ja VB:n ~/_vblang/spec, kuten seuraavassa esimerkissä:

[C# Query Expressions](~/_csharplang/spec/expressions.md#query-expressions)

Ohjelmointirajapintoihin viittaavat linkit

Osa koontijärjestelmän laajennuksista mahdollistaa linkittämisen .NET-ohjelmointirajapintoihin ilman ulkoisia linkkejä. Voit käyttää jompaa kumpaa seuraavista syntakseista:

Automaattinen linkki: <xref:UID> tai <xref:UID?displayProperty=nameWithType>

Kyselyparametri displayProperty tuottaa täysin toimivan linkkitekstin. Oletusarvoisesti linkkitekstissä näkyy vain jäsenen tai tyypin nimi.
Markdown-linkki: [link text](xref:UID)

Käytä tätä vaihtoehtoa, kun haluat mukauttaa näkyviin tulevaa linkkitekstiä.

Esimerkkejä:

<xref:System.String> hahmontuu muotoon String
<xref:System.String?displayProperty=nameWithType> hahmontuu muotoon System.String
[String class](xref:System.String) hahmontuu muotoon String class

Lisätietoja tämän merkintätavan käytöstä on artikkelissa Ristiviitteiden käyttö.

Jotkin UID-tunnukset sisältävät erikoismerkit ', # tai *, UID-arvo on HTML-koodattava %60vastaavasti seuraavasti: , %23 tai %2A *. Joskus myös sulkeet koodataan, mutta tämä ei ole välttämätöntä.

Esimerkkejä:

System.Threading.Tasks.Task'1 muuttuu muotoon System.Threading.Tasks.Task%601
System.Exception.#ctor muuttuu muotoon System.Exception.%23ctor
System.Lazy'1.#ctor(System.Threading.LazyThreadSafetyMode) muuttuu muotoon System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

Voit hakea tyyppien, jäsenen ylikuormitusluettelon tai tietyn ylikuormitetun jäsenen UID:t osoitteesta https://xref.learn.microsoft.com/autocomplete. Kyselymerkkijono ?text=*\<type-member-name>* määrittää tyypin tai jäsenen, jonka UID:t haluat hakea. Esimerkiksi https://xref.learn.microsoft.com/autocomplete?text=string.format noutaa String.Format-ylikuormitukset. Työkalu hakee annettua text-kyselyparametria mistä tahansa UID:n osasta. Voit esimerkiksi hakea jäsenen nimellä (ToString), puutteellisella jäsenen nimellä (ToStri), tyypin ja jäsenen nimellä (Double.ToString) jne.

Jos lisäät * (tai %2A) UID:n perään, linkki edustaa ylikuormitussivua tietyn ohjelmointirajapinnan sijaan. Voit käyttää tätä esimerkiksi silloin, kun haluat linkittää T-luetteloon<>. BinarySearch Method -sivu yleisellä tavalla tietyn ylikuormituksen, kuten T-luettelon<>, sijaan. BinarySearch(T, IComparer<T>). Voit myös käyttää *-linkkiä jäsensivuun, kun jäsentä ei ole ylikuormitettu. Tämä tallentaa, että sinun ei tarvitse sisällyttää parametriluetteloa UID:hen.

Jos haluat linkittää tietyn menetelmän ylikuormitukseen, sinun on annettava menetelmän jokaisen parametrin kelvollinen tyypin nimi. Esimerkiksi <xref:System.DateTime.ToString> linkittää parametrittomaan DateTime.ToString-menetelmään , kun taas <xref:System.DateTime.ToString(System.String,System.IFormatProvider)> linkittää DateTime.ToString(String,IFormatProvider) -menetelmään.

Jos haluat linkittää yleiseen tyyppiin, kuten System.Collections.Generic.List<T>, käytä -merkkiä (%60) ja kirjoita sen jälkeen yleisen tyypin parametrien määrä. Esimerkiksi <xref:System.Nullable%601> linkittää tyyppiin System.Nullable<T> , kun taas <xref:System.Func%602> linkittää edustajaan System.Func<T,TResult> .

Koodi

Paras tapa sisällyttää koodi on sisällyttää koodikatkelmia työnäytteestä. Voit luoda esimerkkisovelluksen .NETin kehittämiseen osallistumista koskevan artikkelin ohjeiden mukaan. Kun koodikatkelmia lisätään kokonaisista ohjelmista, varmistetaan samalla, että kaikki koodi suoritetaan CI-järjestelmämme (Continuous Integration) läpi. Jos kuitenkin haluat näyttää lukijalle jotakin, josta aiheutuu käännösaika- tai suorituspalveluvirheitä, voit käyttää tekstiin sidottuja koodilohkoja.

Jos haluat tietoja Markdown-syntaksista, jonka avulla koodia voi näyttää asiakirjoissa, katso Koodin sisällyttäminen asiakirjoihin.

Kuvat

Staattinen kuva tai animoitu GIF

![this is the alt text](../images/Logo_DotNet.png)

Linkitetty kuva

[![alt text for linked image](../images/Logo_DotNet.png)](https://dot.net)

Videot

Voit upottaa YouTube-videoita Markdown-tiedostoon. Voit hakea videon oikean URL-osoitteen napsauttamalla videota hiiren kakkospainikkeella, valitsemalla Kopioi upotuskoodi ja kopioimalla sitten URL-osoitteen <iframe>-elementistä.

> [!VIDEO <youtube_video_link>]

Esimerkki:

> [!VIDEO https://www.youtube.com/embed/Q2mMbjw6cLA]

learn.microsoft-laajennukset

learn.microsoft tarjoaa muutamia lisälaajennuksia GitHub Flavored Markdowniin.

Tarkistusmerkeillä merkityt luettelot

Luetteloille on käytettävissä mukautettu tyyli. Voit hahmontaa luettelot vihreillä tarkistusmerkeillä.

> [!div class="checklist"]
> * How to create a .NET Core app
> * How to add a reference to the Microsoft.XmlSerializer.Generator package
> * How to edit your MyApp.csproj to add dependencies
> * How to add a class and an XmlSerializer
> * How to build and run the application

Tämä hahmontuu seuraavasti:

.NET Core -sovelluksen luominen
Viittauksen lisääminen Microsoft.XmlSerializer.Generator-pakettiin
Riippuvuuksien lisääminen muokkaamalla MyApp.csproj-tiedostoa
Luokan ja XmlSerializerin lisääminen
Sovelluksen koonti ja suorittaminen

Aidon esimerkin tarkistusmerkeillä merkityistä luetteloista saat .NET Core -ohjeista.

Painikkeet

Painikelinkit:

> [!div class="button"]
> [button links](dotnet-contribute.md)