Osvědčené postupy pro Markdown

Tento článek obsahuje konkrétní pokyny k používání Markdownu v naší dokumentaci. Nejedná se o kurz pro Markdown. Pokud potřebujete návod pro Markdown, podívejte se na tuto příručku Markdownu.

Kanál buildu, který sestaví naši dokumentaci, používá markdig ke zpracování dokumentů Markdownu. Markdig analyzuje dokumenty na základě pravidel nejnovější specifikace CommonMark . OPS se řídí specifikací CommonMark a přidává některá rozšíření pro funkce specifické pro platformu, jako jsou tabulky a výstrahy.

Specifikace CommonMark je přísnější o konstrukci některých prvků Markdownu. Věnujte pozornost podrobnostem, které jsou uvedeny v tomto dokumentu.

Pomocí rozšíření Markdownlint v editoru VS Code vynucujeme naše pravidla stylu a formátování. Toto rozšíření se nainstaluje jako součást balíčku Learn Authoring Pack.

Prázdné řádky, mezery a tabulátory

Prázdné čáry také signalizují konec bloku v Markdownu.

  • Vložte jednu prázdnou hodnotu mezi bloky Markdownu různých typů; Například mezi odstavcem a seznamem nebo záhlavím.
  • Nepoužívejte více než jeden prázdný řádek. Více prázdných řádků se v HTML vykresluje jako jeden prázdný řádek, takže nadbytečné prázdné řádky nejsou potřeba.
  • Nepoužívejte několik po sobě jdoucích prázdných řádků do bloku kódu, po sobě jdoucí prázdné řádky přeruší blok kódu.

Mezery jsou v Markdownu významné.

  • Odeberte nadbytečné mezery na konci řádků. Koncové mezery můžou změnit způsob vykreslování Markdownu.
  • Vždy používejte mezery místo tabulátorů (pevné tabulátory).

Tituly a nadpisy

Používejte pouze nadpisy ATX (# styl, na rozdíl od = nebo - stylu záhlaví).

  • Používejte psaní vět s malými písmeny – pouze vlastní názvy a první písmeno nadpisu nebo záhlaví by mělo být velké.
  • Zahrňte jednu mezeru mezi # prvním písmenem nadpisu.
  • Oddělte nadpisy jedním prázdným řádkem
  • Nepoužívejte více než jeden H1 na dokument.
    • Mělo by to být první záhlaví.
    • Měl by odpovídat názvu článku.
  • Zvýšení úrovní záhlaví o jednu – nepřeskočte úrovně.
  • Omezení hloubky na H3 nebo H4
  • Nepoužívejte tučné písmo nebo jiné značky v záhlavích.

Omezení délky řádku na 100 znaků

V případě koncepčních článků a odkazů na cmdlety omezte řádky na 100 znaků. U about_ článků omezte délku řádku na 79 znaků. Omezení délky řádků zlepšuje čitelnost git rozdílů a historie. Také usnadňuje ostatním autorům vytváření příspěvků.

Pomocí rozšíření Reflow Markdown v editoru VS Code přeformátujte odstavce tak, aby odpovídaly předepsané délce řádku.

Některé typy obsahu se nedají snadno přeformátovat. Například kód uvnitř bloků kódu může být také obtížné přeformátovat v závislosti na obsahu a jazyce kódu. Tabulku nejde přeformátovat. V těchto případech použijte svůj nejlepší úsudek, abyste zachovali obsah co nejblíže limitu 100 znaků.

Zvýraznění

Pro zdůraznění markdown podporuje tučné písmo a kurzívu. Markdown umožňuje použít buď * nebo _ označit zvýraznění. Chcete-li však být konzistentní a zobrazit záměr:

  • Použití ** pro tučné písmo
  • Použijte _ pro kurzívu

Pokud je v dokumentu kombinace tučného písma a kurzívy, následování tohoto vzoru usnadní ostatním pochopení úmyslu značkování.

Seznamy

Pokud seznam obsahuje více vět nebo odstavců, zvažte místo seznamu použití záhlaví podúrovňové úrovně.

Obklopujte seznamy jedním prázdným řádkem.

Neuspořádané seznamy

  • Neukončí položky seznamu s tečkou, pokud neobsahují více vět.
  • Pomocí znaku spojovníku (-) u odrážek položek seznamu se vyhnete nejasnostem se zvýrazněnou značkou, která používá hvězdičku (*).
  • Pokud chcete do položky odrážky zahrnout odstavec nebo jiné prvky, vložte konec řádku po odrážce a zarovnejte odsazení s prvním znakem po odrážce.

Například:

This is a list that contains child elements under a bullet item.

- First bullet item

  Sentence explaining the first bullet.

  - Child bullet item

    Sentence explaining the child bullet.

- Second bullet item
- Third bullet item

Toto je seznam, který obsahuje podřízené prvky pod položkou odrážky.

  • První položka odrážky

    Věta vysvětlující první odrážku.

    • Podřízená položka odrážky

      Věta vysvětlující podřízenou odrážku

  • Druhá položka odrážky

  • Třetí bod odrážky

Seřazené seznamy

  • Všechny položky v číslovaném seznamu by měly používat číslo 1. namísto zvyšování každé položky.
    • Vykreslování Markdownu automaticky zvýší hodnotu.
    • To usnadňuje uspořádání položek a standardizuje odsazení podřízeného obsahu.
  • Pokud chcete do číslování položky zahrnout odstavec nebo jiné prvky, zarovnejte odsazení s prvním znakem za číslem položky.

Například:

1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to
   the next line and must line up with the first character after the numbered list marker.

   To include a second element, insert a line break after the first and align indentations. The
   indentation of the second element must line up with the first character after the numbered list
   marker.

1. The next numbered item starts here.

Výsledný Markdown se vykreslí takto:

  1. Pro první prvek vložte jednu mezeru za znak 1. Dlouhé věty musí být zabaleny na další řádek a musí se zarovnat s prvním znakem za značkou číslovaného seznamu.

    Pokud chcete zahrnout druhý prvek, vložte zalomení řádku za první prvek a zarovnejte odsazení. Odsazení druhého prvku musí být zarovnáno s prvním znakem za znakem číslování seznamu.

  2. Začíná zde další číslovaná položka.

Obrázky

Syntaxe pro zahrnutí obrázku je:

![[alt text]](<folderPath>)

Example:
![Introduction](./media/overview/Introduction.png)

Kde alt text je stručný popis obrázku a <folderPath> je relativní cestou k obrázku.

  • Alternativní text je vyžadován pro podporu čteček obrazovky pro zrakově postižené.
  • Obrázky by měly být uložené ve media/<article-name> složce, která obsahuje článek.
    • Vytvořte složku, která odpovídá názvu souboru vašeho článku ve media složce. Zkopírujte obrázky pro tento článek do této nové složky.
  • Nesdílejte obrázky mezi články.
    • Pokud obrázek používá více článků, musí mít každá složka kopii tohoto obrázku.
    • Tím zabráníte, aby změna obrázku v jednom článku ovlivnila jiný článek.

Podporují se následující typy souborů obrázků: *.png, *.gif, *.jpeg, *.jpg, *.svg

Rozšíření Markdown – výstražná pole

Sada Learn Authoring Pack obsahuje nástroje, které podporují funkce jedinečné pro náš systém publikování. Výstrahy jsou rozšíření Markdownu pro vytváření blokových citací, které se vykreslují pomocí barev a ikon, které zvýrazňují význam obsahu. Podporují se následující typy výstrah:

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

Tato upozornění vypadají v Microsoft Learn takto:

Blok poznámek

Poznámka:

Informace, které by si uživatel měl všimnout, i když je přehlédne.

Blok tipu

Návod

Volitelné informace, které uživateli pomůžou být úspěšnější.

Důležitý blok

Důležité

Základní informace potřebné pro úspěch uživatele

Blok upozornění

Upozornění

Negativní potenciální důsledky akce.

Blok upozornění

Výstraha

Nebezpečné určité důsledky akce.

Rozšíření Markdown – tabulky

Tabulka je uspořádání dat s řádky a sloupci skládajícími se z:

  • Jeden řádek záhlaví
  • Řádek oddělovače oddělující záhlaví od dat
  • Nula nebo více řádků dat

Každý řádek se skládá z buněk obsahujících libovolný text oddělený kanály (|). Pro přehlednost se také doporučuje přední a koncová trubka. Mezery mezi kanály a obsahem buňky jsou oříznuté. Prvky na úrovni bloku nelze vložit do tabulky. Veškerý obsah řádku musí být na jednom řádku.

Řádek oddělovače se skládá z buněk, jejichž jediným obsahem jsou spojovníky (-) a volitelně i počáteční nebo koncové dvojtečky (:) nebo obojí, které označují zarovnání doleva, doprava nebo na střed.

U malých tabulek zvažte místo toho použití seznamu. Seznamy jsou:

  • Snadnější údržba a čtení
  • Lze přeformátovat, aby vyhovoval limitu 100 znaků na řádek.
  • Přístupnější pro uživatele, kteří používají čtečky obrazovky pro vizuální pomoc

Další informace najdete v části Tabulky v referenci pro Markdown na Microsoft Learn.

  • Hypertextové odkazy musí používat syntaxi Markdownu [friendlyname](url-or-path).

  • Systém publikování podporuje tři typy odkazů:

    • Odkazy na adresu URL
    • Odkazy na soubory
    • Křížové odkazy

  • Všechny adresy URL externích webů by měly používat protokol HTTPS, pokud to není platné pro cílový web.

  • Odkazy musí mít popisný název, obvykle název propojeného článku.

  • Nepoužívejte zpětné apostrofy (backticks), tučné písmo nebo jiné značky uvnitř závorek hypertextového odkazu.

  • Holé adresy URL mohou být použity při dokumentaci konkrétního identifikátoru URI, ale musí být uzavřeny v zpětných úvozovkách. Například:

    By default, if you don't specify this parameter, the DMTF standard resource URI
`http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/` is used and the class name is appended to it.

  • Použijte odkazy na odkazy , kde jsou povoleny. Odkazy na odkazy v odstavcích umožňují, aby byly odstavce čitelnější.

    Odkazy na odkazy v Markdownu rozdělují odkaz na dvě části:

    • odkazový odkaz - [friendlyname][id]
    • definice odkazu - [id]: url-or-path
  • Odkazy na adresy URL na jiné články na learn.microsoft.com musí používat cesty relativní k webu. Nejjednodušší způsob, jak vytvořit odkaz relativní vzhledem k webu, je zkopírovat adresu URL z prohlížeče a pak odebrat https://learn.microsoft.com/en-us z hodnoty, kterou vložíte do markdownu.
  • Nezahrnujte lokalizace do adres URL na webech Microsoftu (odeberte /en-us z adresy URL) ani odkazy na Wikipedia.
  • Odeberte všechny nepotřebné parametry dotazu z adresy URL. Příklady, které by se měly odebrat:
    • ?view=powershell-5.1 – používá se k propojení s konkrétní verzí PowerShellu.
    • ?redirectedfrom=MSDN - přidáno na adresu URL při přesměrování z původního článku do nového umístění
  • Pokud potřebujete vytvořit odkaz na konkrétní verzi dokumentu, musíte do řetězce dotazu přidat &preserve-view=true parametr. Příklad: ?view=powershell-5.1&preserve-view=true
  • Na webech Microsoftu odkazy url neobsahují přípony souborů (například ne .md)
  • Odkaz na soubor slouží k propojení z jednoho referenčního článku na jiný nebo z jednoho koncepčního článku do jiného ve stejné sadě docset.
    • Pokud potřebujete vytvořit odkaz z koncepčního článku na referenční článek, musíte použít odkaz na adresu URL.
    • Pokud potřebujete odkazovat na článek v jiné sadě dokumentace nebo v různých úložištích, musíte použít odkaz url.
  • Používejte relativní cesty k souborům (například: ../folder/file.md)
  • Všechny cesty k souborům používají znaky lomítka (/)
  • Zahrnout příponu souboru (například .md)

Křížové odkazy jsou speciální funkcí podporovanou systémem publikování. Křížové odkazy v koncepčních článcích můžete použít k propojení s rozhraním .NET API nebo s referencí na rutiny (cmdlet).

  • Odkazy na referenční informace k rozhraní .NET API najdete v tématu Použití odkazů v dokumentaci v průvodci centrálním přispěvatelem.

  • Odkazy na odkazy na rutiny mají následující formát: xref:<module-name>.<cmdlet-name>. Pokud chcete například vytvořit odkaz na rutinu Get-Content v modulu Microsoft.PowerShell.Management .

    [Get-Content](xref:Microsoft.PowerShell.Management.Get-Content)

Přímé propojení

Přímé odkazy jsou povolené na odkazech URL i souborů.

  • Ukotvující text musí být psán malými písmeny.
  • Přidejte ukotvení na konec cílové cesty. Například:
    • [about_Splatting](about_Splatting.md#splatting-with-arrays)
    • [custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)

Další informace najdete v tématu Použití odkazů v dokumentaci.

Rozsahy kódu

Rozsahy kódu se používají pro vložené fragmenty kódu v odstavci. Pomocí jednoduchých zpětných apostrofů označte rozsah kódu. Například:

PowerShell cmdlet names use the `Verb-Noun` naming convention.

Tento příklad se vykreslí takto:

Názvy rutin PowerShellu Verb-Noun používají konvenci vytváření názvů.

Bloky kódu

Bloky kódu se používají pro příklady příkazů, ukázky víceřádkového kódu, dotazovací jazyky a výstupy. Oddíl textu v souboru článku můžete označit dvěma způsoby: ohraničením v trojitých zpětných znacích (```) nebo jeho odsazením.

Nikdy nepoužívejte odsazení, protože je snadné udělat chybu a pro jiného spisovatele může být obtížné pochopit váš záměr, když potřebují upravit váš článek.

Ohraničené bloky kódu mohou obsahovat volitelnou značku, která označuje syntaxi jazyka obsaženou v bloku. Platforma publikování podporuje seznam značek jazyka. Značka jazyka slouží ke zvýraznění syntaxe při vykreslení článku na webové stránce. Značka jazyka nerozlišuje malá a velká písmena, ale měli byste používat malá písmena, s výjimkou několika speciálních případů.

  • Ploty kódu bez značek lze použít pro bloky syntaxe nebo jiné typy obsahu, u kterých není vyžadováno zvýraznění syntaxe.
  • Při zobrazení výstupu příkazu použijte označený blok kódu s označením jazyka Output. Vykreslené pole je označené jako Výstup a nemá zvýraznění syntaxe.
  • Pokud je výstup v konkrétním podporovaném jazyce, použijte příslušnou značku jazyka. Například mnoho příkazů vypisuje JSON, takže použijte json značku.
  • Pokud použijete nepodporovanou značku jazyka, blok kódu se vykreslí bez zvýraznění syntaxe. Značka jazyka se stane popiskem pro pole vykresleného kódu na webové stránce. Nastavte první písmeno na značce na velké, aby byl popisek na webové stránce velkými písmeny.

Další kroky

Průvodce stylem PowerShellu

  • Last updated on