PowerShell-Docs — przewodnik dotyczący stylu

  • Artykuł

Ten artykuł zawiera wskazówki dotyczące stylu specyficzne dla PowerShell-Docs zawartości. Opiera się on na informacjach przedstawionych w przeglądzie.

Terminologia produktu

Istnieje kilka wariantów programu PowerShell.

  • PowerShell — to jest wersja domyślna. Program PowerShell 7 i inne uznajemy za jeden, prawdziwy program PowerShell.

  • PowerShell Core — program PowerShell zbudowany na programie .NET Core. Użycie terminu Podstawowe powinno być ograniczone do przypadków, w których konieczne jest odróżnienie go od Windows PowerShell.

  • Windows PowerShell — program PowerShell zbudowany na .NET Framework. Windows PowerShell jest dostarczany tylko w Windows i wymaga pełnej struktury.

    Ogólnie rzecz biorąc, odwołania do "Windows PowerShell" w dokumentacji można zmienić na program PowerShell. "Windows PowerShell" należy używać, Windows PowerShell jest omawiane zachowanie specyficzne dla użytkownika.

Powiązane produkty

  • Visual Studio Code (VS Code) — jest to bezpłatny edytor open source firmy Microsoft. Na początku należy użyć pełnej nazwy. Następnie możesz użyć VS Code. Nie używaj "VSCode".
  • Rozszerzenie programu PowerShell dla Visual Studio Code — rozszerzenie zmienia VS Code w preferowane środowiska IDE dla programu PowerShell. Na początku należy użyć pełnej nazwy. Następnie możesz użyć rozszerzenia programu PowerShell.
  • Azure PowerShell — jest to kolekcja modułów programu PowerShell używanych do zarządzania usługami platformy Azure.
  • Azure Stack PowerShell — jest to kolekcja modułów programu PowerShell używanych do zarządzania rozwiązaniem firmy Microsoft w chmurze hybrydowej.

Specyfika znaczników markdown

Program Microsoft Open Publishing System (OPS), który tworzy naszą dokumentację, używa parserów markdig do przetwarzania dokumentów markdown. Parser Markdig analizuje dokumenty na podstawie reguł najnowszej specyfikacji CommonMark.

Nowa specyfikacja commonmark jest znacznie bardziej rygorystyczna w przypadku konstrukcji niektórych elementów markdown. Zwróć szczególną uwagę na szczegółowe informacje podane w tym dokumencie.

Puste wiersze, spacje i tabulacje

Puste wiersze sygnalizują także koniec bloku w języku Markdown. Między blokami kodu Markdown rożnych typów (na przykład między akapitem a listą lub nagłówkiem) powinien znajdować się jeden znak odstępu.

Wiele kolejnych pustych wierszy jest renderowanych jako pojedynczy pusty wiersz w kodzie HTML. Nie służą one żadnemu celowi. W bloku kodu kolejne puste wiersze łamią blok kodu.

Usuń dodatkowe spacje z końców wierszy.

Uwaga

Odstępy w kodzie Markdown są znaczące. Zawsze używaj spacji zamiast twardych tabulacji. Końcowe spacje mogą zmieniać sposób renderowania znaczników Markdown.

Tytuły i nagłówki

Należy używać tylko nagłówków ATX (styl # — w przeciwieństwie do nagłówków w stylu = lub -).

  • Używaj wielkości liter jak przypadku zdania — tylko nazwy własne i pierwsza litera tytułu lub nagłówka powinny być pisane wielkimi literami.
  • Między znakiem # i pierwszą literą nagłówka musi znajdować się pojedyncza spacja.
  • Nagłówki powinny być otoczone pojedynczymi pustymi wierszami.
  • Dokument może zawierać tylko jeden element H1.
  • Poziomy nagłówka powinny być zwiększane o jeden. Nie pomijaj poziomów
  • Nie używaj pogrubienia ani innych znaczników w nagłówkach

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

Dotyczy to artykułów koncepcyjnych i informacji o poleceniach cmdlet. Ograniczenie długości linii zwiększa czytelność różnic i historii usługi Git. Ułatwia to również innym autorom udział w pracy.

Użyj rozszerzenia Reflow Markdown w Visual Studio Code, aby łatwo zmienić układ akapitów, aby dopasować je do zalecanej długości linii.

About_topics są ograniczone do 80 znaków. Aby uzyskać bardziej szczegółowe informacje, zobacz Formatowanie About_ plików.

Listy

Jeśli lista zawiera wiele zdań lub akapitów, rozważ użycie nagłówka podrzędnego, a nie listy.

Listy powinny być otoczone pojedynczymi pustymi wierszami.

Listy nieuporządkowane

Nie kończyj elementów listy z okresem, chyba że zawierają one wiele zdań. Użyj znaków łącznika (-) jako punktorów elementów listy. Pozwala to uniknąć ich pomylenia ze znacznikami pogrubienia lub kursywy, które używają gwiazdki [*]. Aby umieścić akapit lub inne elementy w ramach elementu z punktorem, wstaw podział wiersza i wyrównaj wcięcie do pierwszego znaku po punktorze.

Na przykład:

This is a list that contain 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 obszarze elementu punktora.

  • Element pierwszego punktora

    Zdanie objaśniające pierwszy punktor.

    • Element punktora podrzędnego

      Zdanie objaśniające punktor podrzędny.

  • Element drugiego punktora

  • Element trzeciego punktora

Listy uporządkowane

Aby umieścić akapit lub inne elementy w ramach elementu numerowanego, wyrównaj wcięcie do pierwszego znaku po numerze elementu. Wszystkie elementy na liście numerowanych powinny używać liczby, a nie 1. zwiększania każdego elementu. Podczas renderowania kodu Markdown wartość jest zwiększana automatycznie. Ułatwia to zmianę kolejności elementów i standaryzuje wcięcia zawartości podrzędnej.

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 (like this one), 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. For single digit items, like
   this one, you indent to column 4. For double digits items, for example item number
   10, you indent to column 5.

1. The next numbered item starts here.

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

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

    Aby dołączyć drugi element (taki jak ten), wstaw podział wiersza po pierwszym elemencie i wyrównaj wcięcia. Wcięcie drugiego elementu musi być wyrównane do pierwszego znaku po znaczniku listy numerowanej. W przypadku elementów z liczbą jednocyfrową, takich jak ten, należy zastosować wcięcie do kolumny 4. W przypadku elementów z liczbą dwucyfrową, na przykład 10, należy zastosować wcięcie do kolumny 5.

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

Obrazy

Składnia używana w celu dołączenia obrazu to:

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

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

Gdzie element alt text jest krótkim opisem obrazu, a element <folder path> jest ścieżką względną do obrazu. Alternatywny tekst jest wymagany na potrzeby czytników zawartości ekranu dla osób niedowidzących.

Obrazy powinny być przechowywane media/<article-name> w folderze w folderze zawierającym artykuł. Nie udostępniaj obrazów między artykułami. Utwórz folder pasujący do nazwy pliku artykułu w folderze media. Skopiuj obrazy dla tego artykułu do nowego folderu. Jeśli obraz jest używany w wielu artykułach, każdy folder obrazów musi zawierać jego kopię. To rozwiązanie zapobiega sytuacji, gdy zmiana obrazu w jednym artykule ma wpływ na inny artykuł.

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

Rozszerzenia Markdown obsługiwane przez platformę Open Publishing

Pakiet Microsoft Docs Authoring Pack zawiera narzędzia, które obsługują funkcje unikatowe dla naszego systemu publikowania. Alerty to rozszerzenie markdown do tworzenia blokowych kuotetek renderowanych docs.microsoft.com z kolorami i ikonami, które wyróżniają istotność 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 w witrynie docs.microsoft.com wyglądają następująco:

Blok notatki

Uwaga

Information the user should notice even if skimming.

Blok porad

Porada

Optional information to help a user be more successful.

Ważny blok

Ważne

Essential information required for user success.

Blok ostrzegawcy

Przestroga

Negative potential consequences of an action.

Blok ostrzeżeń

Ostrzeżenie

Niektóre niebezpieczne konsekwencje akcji.

  • Hiperlinki muszą używać składni języka Markdown [friendlyname](url-or-path) . Odwołania do linków są obsługiwane.

  • System publikowania obsługuje trzy typy linków:

    • Linki adresów URL
    • Linki do plików
    • Linki odsyłacze

  • Linki do innych artykułów w docs.microsoft.com muszą być ścieżkami względnym witryny

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

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

  • Wszystkie elementy w sekcji Powiązane linki u dołu powinny być hiperlinkami

  • Nie używaj znaków wstecz, pogrubień ani innych znaczników w nawiasach kwadratowych hiperlinku.

  • Podczas dokumentowania określonego adresu URI można używać nagie adresy URL. Ten URI musi być ujęty w cudzysłowy. 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.

Tworzenie linków do innej zawartości w docs.microsoft.com

  • Linki url do innych artykułów w docs.microsoft.com muszą być ścieżkami względnym witryny. Najprostszym sposobem utworzenia linku względnego jest skopiowanie adresu URL z przeglądarki, a następnie usunięcie z wartości https://docs.microsoft.com/en-us wklejanej do znaczników markdown. Nie uwzględniaj lokalizacji regionalnych w adresach URL we właściwościach firmy Microsoft (usuń /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 — dodawany do adresu URL po przekierowaniu ze starego artykułu do jego nowej lokalizacji

    Jeśli musisz utworzyć link do określonej wersji dokumentu, musisz dodać parametr do &preserve-view=true ciągu zapytania. Na przykład: ?view=powershell-5.1&preserve-view=true

  • Link do pliku służy do łączenia z jednego artykułu referencyjnego do innego lub z jednego artykułu koncepcyjnego do innego. Jeśli musisz utworzyć link do artykułu referencyjnego dla określonej wersji programu PowerShell, musisz użyć linku adresu URL.

    • Linki do plików zawierają względną ścieżkę pliku (na przykład: ../folder/file.md )
    • Wszystkie ścieżki plików używają znaków ukośnika / ()

  • Linki odsyłacze to specjalna funkcja obsługiwana przez system publikowania. Linki odsyłacze w artykułach koncepcyjnych mogą być linkami do interfejsu API platformy .NET lub odwoływać się do polecenia 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 polecenia cmdlet mają następujący format: xref:<module-name>.<cmdlet-name> . Na przykład aby połączyć się z Get-Content poleceniem cmdlet w module Microsoft.PowerShell.Management.

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

Linki do linków do plików i adresów URL są dozwolone. Dodaj kotwicę na końcu ścieżki docelowej. Na 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.

Formatowanie elementów składni polecenia

  • Zawsze używaj pełnej nazwy dla polecenia cmdlet i parametrów. Unikaj używania aliasów, chyba że specjalnie demonstrujesz alias.

  • Właściwość, parametr, obiekt, nazwy typów, nazwy klas, metody klas powinny być pogrubione.

    • Wartości właściwości i parametrów powinny być opakowane w backticks ( ` ).
    • Podczas odwoływania się do typów przy użyciu stylu w nawiasach kwadratowych użyj nawiasów klamrowych. Na przykład: [System.Io.FileInfo]

  • Słowa kluczowe języka, nazwy polecenia cmdlet, funkcje, zmienne, natywne pliki EXE, ścieżki plików i wbudowane przykłady składni powinny być opakowane w znaki backtick ` ().

    Na przykład:

    The following code uses `Get-ChildItem` to list the contents of `C:\Windows` and assigns
the output to the `$files` variable.

```powershell
$files = Get-ChildItem C:\Windows
```

    • Słowa kluczowe i operatory programu PowerShell powinny być małymi literami

    • Użyj odpowiedniej wielkości (Pascal) dla nazw i parametrów polecenia cmdlet

    • W przypadku przywoływania parametru według nazwy nazwa powinna być pogrubiona. W przypadku ilustrowania użycia parametru z prefiksem w postaci łącznika parametr należy otoczyć znakami akcentu. Na przykład:

      The parameter's name is **Name**, but it's typed as `-Name` when used on the command
line as a parameter.

    • W przypadku przedstawiania przykładowego użycia polecenia zewnętrznego przykład należy otoczyć znakami akcentu. Zawsze uwzględniaj rozszerzenie pliku w poleceniu natywnym. Na przykład:

      To start the spooler service on a remote computer named DC01, you type `sc.exe \\DC01 start spooler`.

      Do uwzględnienia rozszerzenia pliku zapewnia wykonanie poprawnego polecenia zgodnie z pierwszeństwom poleceń programu PowerShell.

  • Podczas pisania artykułu koncepcyjnego (w przeciwieństwie do dokumentacji) pierwsze wystąpienie nazwy polecenia cmdlet powinno być hiperlinkiem do dokumentacji polecenia cmdlet. Nie używaj znaków wstecz, pogrubień ani innych znaczników w nawiasach kwadratowych hiperlinku.

    Na przykład:

    This [Write-Host](/powershell/module/Microsoft.PowerShell.Utility/Write-Host) cmdlet
uses the **Object** parameter to ...

    Aby uzyskać więcej informacji, zobacz sekcję Hiperlinki w tym artykule.

Markdown dla przykładów kodu

Kod Markdown obsługuje dwa różne style kodu:

  • Zakresy kodu (wbudowane) — oznaczone pojedynczym znakiem backtick ( ` ). Używany w akapicie, a nie jako autonomiczny blok.
  • Bloki kodu — blok wielo wierszowy otoczony ciągami z trzema znakami backtick ``` (). Bloki kodu mogą również mieć etykietę języka po znaku backticks. Etykieta języka umożliwia wyróżnianie składni zawartości bloku kodu.

Wszystkie bloki kodu powinny być zawarte w ograniczniku kodu. Nigdy nie używaj wcięcia dla bloków kodu. Markdown umożliwia ten wzorzec, ale może być problematyczny i należy go unikać.

Blok kodu to jeden lub więcej wierszy kodu otoczony przez ogrodzenie kodu z potrójnym ``` kodem (). Znaczniki ogranicznika kodu muszą znajdować się w osobnych wierszach przed i po przykładzie kodu. Znacznik na początku bloku kodu może mieć opcjonalną etykietę języka. Platforma OPS (Open Publishing System) firmy Microsoft używa etykiety języka do obsługi funkcji wyróżniania składni.

Aby uzyskać pełną listę obsługiwanych tagów języka, zobacz odgrodzone bloki kodu w scentralizowanym przewodniku współautora.

Na platformie OPS dodano także przycisk Kopiuj, który umożliwia skopiowanie zawartości bloku kodu do schowka. Dzięki temu możesz szybko wkleić kod do skryptu, aby przetestować przykładowy kod. Jednak nie wszystkie przykłady w naszej dokumentacji są przeznaczone do uruchamiania w stanie, w ile jest. Niektóre bloki kodu to proste ilustracje koncepcji programu PowerShell.

W naszej dokumentacji są używane trzy typy bloków kodu:

  1. Bloki składni
  2. Przykłady ilustracyjne
  3. Przykłady wykonywalne

Bloki kodu składni

Bloki kodu składni są używane do opisywania składni polecenia. Nie używaj tagu języka na ogrodzeniu kodu. Ten przykład przedstawia wszystkie możliwe parametry polecenia cmdlet Get-Command.

```
Get-Command [-Verb <String[]>] [-Noun <String[]>] [-Module <String[]>]
  [-FullyQualifiedModule <ModuleSpecification[]>] [-TotalCount <Int32>] [-Syntax]
  [-ShowCommandInfo] [[-ArgumentList] <Object[]>] [-All] [-ListImported]
  [-ParameterName <String[]>] [-ParameterType <PSTypeName[]>] [<CommonParameters>]
```

Ten przykład ogólnie opisuje instrukcję for:

```
for (<init>; <condition>; <repeat>)
{<statement list>}
```

Przykłady ilustracyjne

Przykłady ilustracyjne służą do wyjaśniania pojęć programu PowerShell. Nie są one przeznaczone do kopiowania do schowka w celu wykonania. Są one najczęściej używane w przypadku prostych przykładów, które są łatwe do wpisania i łatwe do zrozumienia. Blok kodu może zawierać wiersz polecenia programu PowerShell i przykładowe dane wyjściowe.

Oto prosty przykład ilustrujący operatory porównania programu PowerShell. W tym przypadku przykład nie jest przeznaczony do skopiowania i uruchomienia przez użytkownika.

```powershell
PS> 2 -eq 2
True

PS> 2 -eq 3
False

PS> 1,2,3 -eq 2
2

PS> "abc" -eq "abc"
True

PS> "abc" -eq "abc", "def"
False

PS> "abc", "def" -eq "abc"
abc
```

Przykłady wykonywalne

Złożone przykłady lub przykłady, które mają zostać skopiowane i wykonane, powinny używać następujących znaczników w stylu bloku:

```powershell
<Your PowerShell code goes here>
```

Dane wyjściowe wyświetlane przez polecenia programu PowerShell powinny znajdować się w bloku kodu Output, aby zapobiec wyróżnianiu składni. Na przykład:

```powershell
Get-Command -Module Microsoft.PowerShell.Security
```

```Output
CommandType  Name                        Version    Source
-----------  ----                        -------    ------
Cmdlet       ConvertFrom-SecureString    3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       ConvertTo-SecureString      3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-Acl                     3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-CmsMessage              3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-Credential              3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Get-PfxCertificate          3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       New-FileCatalog             3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Protect-CmsMessage          3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-Acl                     3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-AuthenticodeSignature   3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Set-ExecutionPolicy         3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Test-FileCatalog            3.0.0.0    Microsoft.PowerShell.Security
Cmdlet       Unprotect-CmsMessage        3.0.0.0    Microsoft.PowerShell.Security
```

Etykieta kodu wyjściowego nie jest oficjalnym "językiem" obsługiwanym przez system wyróżniania składni. Ta etykieta jest jednak przydatna, ponieważ firma OPS dodaje etykietę "Output" (Dane wyjściowe) do ramki pola kodu na stronie internetowej. Pole kodu "Dane wyjściowe" nie wyróżnia składni.

Reguły stylu kodowania

Unikaj kontynuacji wierszy w przykładach kodu.

Unikaj używania znaków kontynuacji wiersza (`) w przykładach kodu programu PowerShell. Trudno je zauważyć i mogą powodować problemy, jeśli na końcu wiersza znajdują się dodatkowe spacje.

  • Użyj funkcji splatting programu PowerShell, aby zmniejszyć długość wiersza dla poleceń cmdlet, które mają kilka parametrów.
  • Skorzystaj z możliwości naturalnego podziału wiersza programu PowerShell, takich jak znaki po potoku ( ), otwierając nawiasy | klamrowe ( ), nawiasy ( ) i { ( nawiasy [ ().

Unikaj korzystania z monitów programu PowerShell w przykładach

Użycie ciągu wiersza polecenia nie jest zalecane i powinno być ograniczone do scenariuszy, które mają na celu zilustrować użycie wiersza polecenia. W większości tych przykładów ciąg monitu powinien mieć wartość PS> . Ten monit jest niezależny od wskaźników specyficznych dla systemu operacyjnego.

Monity są wymagane w przykładach w celu zilustrowania poleceń, które zmieniają monit lub gdy wyświetlana ścieżka jest istotna dla scenariusza. Poniższy przykład ilustruje, jak monit zmienia się podczas korzystania z dostawcy rejestru.

PS C:\> cd HKCU:\System\
PS HKCU:\System\> dir

    Hive: HKEY_CURRENT_USER\System

Name                   Property
----                   --------
CurrentControlSet
GameConfigStore        GameDVR_Enabled                       : 1
                       GameDVR_FSEBehaviorMode               : 2
                       Win32_AutoGameModeDefaultProfile      : {2, 0, 1, 0...}
                       Win32_GameModeRelatedProcesses        : {1, 0, 1, 0...}
                       GameDVR_HonorUserFSEBehaviorMode      : 0
                       GameDVR_DXGIHonorFSEWindowsCompatible : 0

Nie używaj aliasów w przykładach

Użyj pełnej nazwy wszystkich polecenia cmdlet i parametrów, chyba że szczegółowo udokumentowano alias. Nazwy parametrów i polecenia cmdlet muszą używać odpowiednich nazw z użyciem języka Pascal.

Używanie parametrów w przykładach

Unikaj używania parametrów pozycyjnych. Ogólnie rzecz biorąc, w przykładzie należy zawsze uwzględnić nazwę parametru, nawet jeśli parametr ma wartość pozycyjną. Zwiększa to czytelność przykładów.

Artykuły referencyjne dotyczące formatowania polecenia cmdlet

Artykuły referencyjne poleceń cmdlet mają określoną strukturę. Ta struktura jest definiowana przez narzędzie PlatyPS. PlatyPS generuje pomoc polecenia cmdlet dla modułów programu PowerShell w znacznikach Markdown. Po zmodyfikowaniu plików Markdown narzędzie PlatyPS jest używane do tworzenia plików pomocy MAML używanych przez polecenie cmdlet Get-Help.

Narzędzie PlatyPS zawiera ustalony, zapisany w kodzie schemat dla dokumentacji poleceń cmdlet. Dokument platyPS.schema.md próbuje opisać tę strukturę. Naruszenia schematu powodują błędy kompilacji, które muszą zostać naprawione przed zaakceptowaniem Twojego materiału.

  • Nie usuwaj żadnych struktur nagłówków ATX. Narzędzie PlatyPS oczekuje określonego zestawu nagłówków.
  • Nagłówki Input type i Output type muszą mieć typ. Jeśli polecenie cmdlet nie bierze danych wejściowych ani nie zwraca wartości, użyj wartości None .
  • Śródwierszowych zakresów kodu można używać w dowolnym akapicie.
  • Ogrodzone bloki kodu są dozwolone tylko w sekcji PRZYKŁADY.

W schemacie PlatyPS element EXAMPLES jest nagłówkiem H2. Każdy przykład to nagłówek H3. W ramach przykładu schemat nie zezwala na oddzielanie bloków kodu akapitami. Schemat umożliwia następującą strukturę:

### Example X - Title sentence

0 or more paragraphs
1 or more code blocks
0 or more paragraphs.

Ponumeruj wszystkie przykłady i dodaj krótki tytuł.

Na przykład:

### Example 1: Get cmdlets, functions, and aliases

This command gets the PowerShell cmdlets, functions, and aliases that are installed on the
computer.

```powershell
Get-Command
```

### Example 2: Get commands in the current session

```powershell
Get-Command -ListImported
```

Formatowanie plików About_

About_* Pliki są zapisywane w języku Markdown, ale są dostarczane jako pliki w postaci zwykłego tekstu. Do konwersji znaczników markdown na zwykły tekst używamy edytora Pandoc. About_* Pliki są sformatowane w celu zapewnienia najlepszej zgodności we wszystkich wersjach programu PowerShell i przy użyciu narzędzi do publikowania.

Podstawowe wskazówki dotyczące formatowania:

  • Ogranicz normalne wiersze do 80 znaków

  • Bloki kodu są ograniczone do 76 znaków

  • Liczba blokowych kuotech (i alertów) jest ograniczona do 78 znaków

  • W przypadku używania tych specjalnych metaznak \ $ , i < :

    • W nagłówku te znaki muszą być znakami ucieczki przy użyciu wiodącego znaku lub muszą być ujęte w zakresy kodu przy \ użyciu znaków wstecz ( ` )

    • W akapicie te znaki należy umieścić w zakresach kodu. Na przykład:

      ### The purpose of the \$foo variable

The `$foo` variable is used to store ...

  • Tabele muszą mieścić się w obrębie 76 znaków

    • Ręcznie zawiń zawartość komórek w wielu wierszach.

    • Używaj otwierających i zamykających znaków | w każdym wierszu.

    • W poniższym przykładzie pokazano, jak poprawnie skonstruować tabelę zawierającą informacje zawijania w wielu wierszach w komórce.

      ```
|Operator|Description                |Example                          |
|--------|---------------------------|---------------------------------|
|`-is`   |Returns TRUE when the input|`(get-date) -is [DateTime]`      |
|        |is an instance of the      |`True`                           |
|        |specified .NET type.       |                                 |
|`-isNot`|Returns TRUE when the input|`(get-date) -isNot [DateTime]`   |
|        |not an instance of the     |`False`                          |
|        |specified.NET type.        |                                 |
|`-as`   |Converts the input to the  |`"5/7/07" -as [DateTime]`        |
|        |specified .NET type.       |`Monday, May 7, 2007 12:00:00 AM`|
```

      Uwaga

      Ograniczenie 76 kolumn ma zastosowanie tylko do About_* tematów. W artykułach referencyjnych dotyczących pojęć lub polecenia cmdlet można używać szerokich kolumn.

Następne kroki

Redakcyjna lista kontrolna