Udostępnij za pośrednictwem

Najlepsze rozwiązania dotyczące języka Markdown

Ten artykuł zawiera szczegółowe wskazówki dotyczące korzystania z języka Markdown w naszej dokumentacji. Nie jest to samouczek dotyczący języka Markdown. Jeśli potrzebujesz samouczka dotyczącego Markdown, zobacz tę ściągawkę Markdown.

Potok kompilacji, który kompiluje naszą dokumentację, używa języka markdig do przetwarzania dokumentów języka Markdown. Markdig analizuje dokumenty na podstawie reguł najnowszej specyfikacji CommonMark. Platforma OPS jest zgodna ze specyfikacją CommonMark i dodaje pewne rozszerzenia dla funkcji specyficznych dla platformy, takich jak tabele i alerty.

Specyfikacja CommonMark jest bardziej restrykcyjna w konstruowaniu niektórych elementów Markdown. Zwróć szczególną uwagę na szczegóły podane w tym dokumencie.

Używamy rozszerzenia markdownlint w programie VS Code, aby wymusić reguły stylu i formatowania. To rozszerzenie jest instalowane w ramach pakietu Learn Authoring Pack.

Puste wiersze, spacje i karty

Puste wiersze sygnalizuje również koniec bloku w języku Markdown.

  • Umieść pojedyncze pole między blokami języka Markdown różnych typów; na przykład między akapitem a listą lub nagłówkiem.
  • Nie używaj więcej niż jednego pustego wiersza. W HTML wiele pustych wierszy jest renderowane jako pojedynczy pusty wiersz, dlatego dodatkowe puste wiersze są niepotrzebne.
  • Nie używaj wielu kolejnych pustych wierszy w bloku kodu, a kolejne puste wiersze przerywają blok kodu.

Odstępy są istotne w języku Markdown.

  • Usuń dodatkowe spacje na końcu wierszy. Spacje końcowe mogą zmieniać sposób renderowania języka Markdown.
  • Zawsze używaj spacji zamiast kart (twarde karty).

Tytuły i nagłówki

Używaj tylko nagłówków ATX w stylu # (w przeciwieństwie do nagłówków w stylu = lub -).

  • Używaj małych liter w zdaniach — tylko nazwy własne i pierwsza litera tytułu lub nagłówka powinny być wielką literą
  • Dołącz pojedynczą spację między # a pierwszą literą nagłówka.
  • Umieść nagłówki między pojedynczymi pustymi liniami
  • Nie używaj więcej niż jednego H1 na dokument
    • Powinien to być pierwszy nagłówek
    • Powinien on być zgodny z tytułem artykułu
  • Zwiększ poziomy nagłówków o jeden — nie pomijaj poziomów
  • Ogranicz głębokość do H3 lub H4
  • Unikaj używania pogrubienia lub innych znaczników w nagłówkach

Ogranicz długość wiersza do 100 znaków

W przypadku artykułów koncepcyjnych i odniesień do poleceń cmdlet ogranicz wiersze do 100 znaków. W przypadku about_ artykułów ogranicz długość wiersza do 79 znaków. Ograniczenie długości linii poprawia czytelność git diffów i historii. Ułatwia to również innym pisarzom przyczynianie się.

Użyj rozszerzenia Reflow Markdown w programie VS Code, aby sformatować akapity do określonej długości wiersza.

Niektórych typów zawartości nie można łatwo przelać. Na przykład kod wewnątrz bloków kodu może być również trudny do zmiany w zależności od zawartości i języka kodu. Nie można zmienić układu tabeli. W takich przypadkach należy użyć najlepszego osądu, aby zachować zawartość jak najbliżej limitu 100 znaków, jak to możliwe.

Podkreślenie

W celu podkreślenia, język Markdown obsługuje pogrubienie i kursywę. Język Markdown umożliwia użycie * lub _ do podkreślenia. Jednak aby zachować spójność i pokazać intencję:

  • Użyj ** do pogrubienia
  • Użyj _ do kursywy

Stosowanie tego wzorca ułatwia innym zrozumienie intencji znaczników, gdy w dokumencie znajduje się kombinacja pogrubienia i kursywy.

Listach

Jeśli lista zawiera wiele zdań lub akapitów, rozważ użycie nagłówka niższego poziomu zamiast listy.

Otaczaj listy pojedynczym pustym wierszem.

Listy nieurządzane

  • Nie kończ elementów listy z kropką, chyba że zawierają wiele zdań.
  • Użyj znaku łącznika (-) dla punktorów elementów listy, aby uniknąć pomyłek z znacznikiem wyróżnienia, który używa gwiazdki (*).
  • Aby uwzględnić akapit lub inne elementy w elemencie punktor, wstaw podział wiersza i wyrównaj wcięcie do pierwszego znaku po punktorze.

Na przykład:

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

Jest to lista zawierająca elementy podrzędne w elemencie punktorowym.

  • Pierwszy punkt listy

    Zdanie objaśniające pierwszy punkt.

    • Element punktoru podrzędnego

      Zdanie objaśniające podpunkt.

  • Drugi punkt programu

  • Trzeci element punktoru

Listy uporządkowane

  • Wszystkie elementy na liście numerowanej powinny używać liczby 1. , a nie zwiększać każdego elementu.
    • Renderowanie języka Markdown zwiększa wartość automatycznie.
    • Ułatwia to zmienianie kolejności elementów i standaryzację wcięcia zawartości podrzędnej.
  • Aby wstawić akapit lub inne elementy pod elementem numerowanym, wyrównaj wcięcie z pierwszym znakiem po numerze elementu.

Na przykład:

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.

Wynikowy kod Markdown jest renderowany w następujący sposób:

  1. Dla pierwszego elementu wstaw jedną spację po 1. Długie zdania powinny być zawijane do następnego wiersza i muszą być wyrównane do pierwszego znaku po znaczniku listy numerowanej.

    Aby dołączyć drugi element, wstaw podział wiersza po pierwszym i wyrównaj wcięcia. Wcięcie drugiego elementu musi być wyrównane do pierwszego znaku po znaczniku listy numerowanej.

  2. Następny numerowany element zaczyna się tutaj.

Obrazy

Składnia do uwzględnienia obrazu to:

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

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

Gdzie alt text jest krótkim opisem obrazu i <folderPath> jest ścieżką względną do obrazu.

  • Tekst alternatywny jest wymagany do obsługi czytników zawartości ekranu dla osób niedowidzących.
  • Obrazy powinny być przechowywane w media/<article-name> folderze w folderze zawierającym artykuł.
    • Utwórz folder zgodny z nazwą pliku artykułu w folderze media . Skopiuj obrazy tego artykułu do tego nowego folderu.
  • Nie udostępniaj obrazów między artykułami.
    • Jeśli obraz jest używany przez wiele artykułów, każdy folder musi mieć kopię tego obrazu.
    • Uniemożliwia to zmianę obrazu w jednym artykule, która ma wpływ na inny artykuł.

Obsługiwane są następujące typy plików obrazów: *.png, , *.gif*.jpeg, , *.jpg*.svg

Rozszerzenie języka Markdown — okna alertów

Pakiet Learn Authoring Pack zawiera narzędzia, które obsługują funkcje unikatowe dla naszego systemu publikowania. Alerty to rozszerzenie języka Markdown umożliwiające tworzenie cytatów blokowych, które są renderowane za pomocą kolorów i ikon wyróżniających znaczenie zawartości. Obsługiwane są następujące typy alertów:

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

Te alerty wyglądają następująco w witrynie Microsoft Learn:

Blok notatek

Uwaga

Informacje, które użytkownik powinien zauważyć, nawet podczas przeglądania pobieżnego.

Sekcja porad

Wskazówka

Opcjonalne informacje ułatwiające użytkownikowi powodzenie.

Ważny blok

Ważne

Niezbędne informacje wymagane do pomyślnego działania użytkownika.

Blok ostrożności

Ostrożność

Negatywne potencjalne konsekwencje działania.

Blok ostrzegawczy

Ostrzeżenie

Niebezpieczne pewne konsekwencje działania.

Markdown — rozszerzenie: tabele

Tabela to rozmieszczenie danych z wierszami i kolumnami składającymi się z:

  • Pojedynczy wiersz nagłówka
  • Linia ogranicznika oddzielająca nagłówek od danych
  • Zero lub więcej wierszy danych

Każdy wiersz składa się z komórek zawierających dowolny tekst rozdzielony potokami (|). Rura prowadząca i końcowa jest również zalecana w celu zapewnienia przejrzystości. Odstępy między potokami i zawartością komórek są przycinane. Nie można wstawić elementów na poziomie bloku w tabeli. Cała zawartość wiersza musi znajdować się w jednym wierszu.

Wiersz ogranicznika składa się z komórek, których jedyną zawartością są łączniki (-) i opcjonalnie, dwukropek wiodący lub końcowy (:) lub oba, aby wskazać odpowiednio wyrównanie lewe, prawe lub środkowe.

W przypadku małych tabel rozważ użycie listy. Lista jest:

  • Łatwiejsza obsługa i odczytywanie
  • Można zmieścić się w limicie 100 znaków na linię.
  • Bardziej dostępny dla użytkowników korzystających z czytników zawartości ekranu w celu uzyskania pomocy wizualnej

Aby uzyskać więcej informacji, zobacz sekcję Tabeledokumentacji języka Markdown dla usługi Microsoft Learn.

  • Hiperlinki muszą używać składni [friendlyname](url-or-path)języka Markdown.

  • System publikowania obsługuje trzy typy łączy:

    • Linki adresów URL
    • Linki do plików
    • Odsyłacze krzyżowe

  • Wszystkie adresy URL zewnętrznych witryn internetowych powinny używać protokołu HTTPS, chyba że nie jest to prawidłowe dla witryny docelowej.

  • Linki muszą mieć przyjazną nazwę, zazwyczaj tytuł połączonego artykułu

  • Unikaj używania backticksów, pogrubionych lub innych znaczników wewnątrz nawiasów hiperłącza.

  • Surowe URL-e mogą być używane podczas dokumentowania określonego identyfikatora URI, ale muszą być ujęte w apostrofy zwrotne. Na przykład:

    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.

  • Użyj odnośników tam, gdzie jest to dozwolone. Odwołania do linków w akapitach sprawiają, że akapity są bardziej czytelne.

    Odwołania do linków dzielą link w *Markdownzie* na dwie części:

    • odwołanie do linku — [friendlyname][id]
    • definicja łącza — [id]: url-or-path
  • Linki URL do innych artykułów na learn.microsoft.com muszą używać ścieżek względnych witryny. Najłatwiejszym sposobem utworzenia linku względnego do witryny jest skopiowanie adresu URL z przeglądarki, a następnie usunięcie https://learn.microsoft.com/en-us z wartości wklejanej do kodu markdown.
  • Nie dołączaj lokalizacji do adresów URL we właściwościach Microsoftu ani do linków Wikipedii; należy usunąć /en-us z adresu URL.
  • Usuń wszystkie niepotrzebne parametry zapytania z adresu URL. Przykłady, które należy usunąć:
    • ?view=powershell-5.1 — służy do łączenia z określoną wersją programu PowerShell
    • ?redirectedfrom=MSDN — dodany do adresu URL po przekierowaniu ze starego artykułu do nowej lokalizacji
  • Jeśli musisz połączyć się z określoną wersją dokumentu, musisz dodać &preserve-view=true parametr do ciągu zapytania. Przykład: ?view=powershell-5.1&preserve-view=true
  • W witrynach firmy Microsoft linki adresów URL nie zawierają rozszerzeń plików (na przykład nie .md)
  • Link do pliku służy do łączenia z jednego artykułu odniesienia do innego lub z jednego artykułu koncepcyjnego do innego w tym samym zestawie dokumentów.
    • Jeśli musisz utworzyć link z artykułu koncepcyjnego do artykułu referencyjnego, musisz użyć linku adresu URL.
    • Jeśli musisz połączyć się z artykułem w innym zestawie dokumentów lub w repozytoriach, musisz użyć linku adresu URL.
  • Użyj względnych ścieżek plików (na przykład: ../folder/file.md)
  • Wszystkie ścieżki plików używają znaków ukośnika do przodu (/)
  • Uwzględnij rozszerzenie pliku (na przykład .md)

Linki krzyżowe to specjalna funkcja obsługiwana przez system publikowania. Linki krzyżowe można używać w artykułach koncepcyjnych, aby połączyć się z interfejsem API platformy .NET lub dokumentacją poleceń cmdlet.

  • Aby uzyskać linki do dokumentacji interfejsu API platformy .NET, zobacz Używanie linków w dokumentacji w centralnym przewodniku współautora.

  • Linki do odwołania do poleceń cmdlet mają następujący format: xref:<module-name>.<cmdlet-name>. Aby na przykład odwołać się do polecenia Get-Content cmdlet w module Microsoft.PowerShell.Management.

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

Łączenie głębokie

Linkowanie głębokie jest dozwolone zarówno dla linków URL, jak i linków do plików.

  • Tekst kotwicy musi być napisany małymi literami.
  • Dodaj kotwicę na końcu ścieżki docelowej. Przykład:
    • [about_Splatting](about_Splatting.md#splatting-with-arrays)
    • [custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)

Aby uzyskać więcej informacji, zobacz Używanie linków w dokumentacji.

Zakresy kodu

Zakresy kodu są używane do fragmentów kodu wbudowanego w akapicie. Użyj pojedynczych znaczników (`), aby wskazać zakres kodu. Na przykład:

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

Ten przykład jest renderowany jako:

Nazwy poleceń cmdlet programu PowerShell używają Verb-Noun konwencji nazewnictwa.

Bloki kodu

Bloki kodu są używane do przykładów poleceń, przykładów kodu wielowierszowego, języków zapytań i danych wyjściowych. Istnieją dwa sposoby wskazania, że sekcja tekstu w pliku artykułu jest blokiem kodu: przez otoczenie go potrójnymi apostrofami (```) lub przez jego wcięcie.

Nigdy nie używaj wcięcia, ponieważ łatwo o błędy, a inny autor może mieć trudności ze zrozumieniem twojej intencji, kiedy trzeba edytować artykuł.

Ogrodzone bloki kodu mogą zawierać opcjonalny tag wskazujący składnię języka zawartą w bloku. Platforma publikowania obsługuje listę tagów języka. Tag języka służy do wyróżniania składni podczas renderowania artykułu na stronie internetowej. Tag języka nie uwzględnia wielkości liter, ale należy użyć małych liter z wyjątkiem kilku specjalnych przypadków.

  • Ogrodzenia kodu bez tagów mogą służyć do bloków składni lub innych typów zawartości, w których wyróżnianie składni nie jest wymagane.
  • W przypadku wyświetlania danych wyjściowych polecenia użyj oznaczonego ogrodzenia kodu z tagiem języka Output. Pole renderowane jest oznaczone jako Dane wyjściowe i nie ma wyróżniania składni.
  • Jeśli dane wyjściowe są w określonym obsługiwanym języku, użyj odpowiedniego tagu języka. Na przykład wiele poleceń zwraca kod JSON, więc użyj tagu json .
  • Jeśli używasz nieobsługiwanego tagu języka, blok kodu będzie renderowany bez wyróżniania składni. Tag języka staje się etykietą pola renderowanego kodu na stronie internetowej. Zmień tag tak, aby etykieta została napisana wielką literą na stronie internetowej.

Następne kroki

Przewodnik po stylu programu PowerShell